Calendar behaviour

This module defines the responsibilities for working with calendars, dates, times and datetimes in Elixir.

Currently it defines types and the minimal implementation for a calendar behaviour in Elixir. The goal of the Calendar features in Elixir is to provide a base for interoperability instead of full-featured datetime API.

For the actual date, time and datetime structures, see Date, Time, NaiveDateTime and DateTime.

Note the year, month, day, etc designations are overspecified (i.e. an integer instead of 1..12 for months) because different calendars may have a different number of days per month, months per year and so on.

Summary

Types

calendar()

A calendar implementation

date()

Any map/struct that contains the date fields

datetime()

Any map/struct that contains the datetime fields

day()

hour()

microsecond()

Microseconds with stored precision

minute()

month()

naive_datetime()

Any map/struct that contains the naive_datetime fields

second()

From 0 to 60 to account for leap seconds

std_offset()

The time zone standard offset in seconds (not zero in summer times)

time()

Any map/struct that contains the time fields

time_zone()

The time zone ID according to the IANA tz database (e.g. Europe/Zurich)

utc_offset()

The time zone UTC offset in seconds

year()

zone_abbr()

The time zone abbreviation (e.g. CET or CEST or BST etc.)

Callbacks

date_to_string(year, month, day)

Converts the date into a string according to the calendar

datetime_to_string(year, month, day, hour, minute, second, microsecond, time_zone, zone_abbr, utc_offset, std_offset)

Coverts the date time (with time zone) into a string according to the calendar

day_of_week(year, month, day)

Calculates the day of the week from the given year, month, and day

days_in_month(year, month)

Returns how many days there are in the given year-month

leap_year?(year)

Returns true if the given year is a leap year

naive_datetime_to_string(year, month, day, hour, minute, second, microsecond)

Converts the date time (without time zone) into a string according to the calendar

Types

calendar()

calendar() :: module()

A calendar implementation

date()

date() :: %{optional(any()) => any(), :calendar => calendar(), :year => year(), :month => month(), :day => day()}

Any map/struct that contains the date fields

datetime()

datetime() :: %{optional(any()) => any(), :calendar => calendar(), :year => year(), :month => month(), :day => day(), :hour => hour(), :minute => minute(), :second => second(), :microsecond => microsecond(), :time_zone => time_zone(), :zone_abbr => zone_abbr(), :utc_offset => utc_offset(), :std_offset => std_offset()}

Any map/struct that contains the datetime fields

day()

day() :: integer()

hour()

hour() :: 0..23

microsecond()

microsecond() :: {0..999999, 0..6}

Microseconds with stored precision.

The precision represents the number of digits that must be used when representing the microseconds to external format. If the precision is 0, it means microseconds must be skipped.

minute()

minute() :: 0..59

month()

month() :: integer()

naive_datetime()

naive_datetime() :: %{optional(any()) => any(), :calendar => calendar(), :year => year(), :month => month(), :day => day(), :hour => hour(), :minute => minute(), :second => second(), :microsecond => microsecond()}

Any map/struct that contains the naive_datetime fields

second()

second() :: 0..60

From 0 to 60 to account for leap seconds

std_offset()

std_offset() :: integer()

The time zone standard offset in seconds (not zero in summer times)

time()

time() :: %{optional(any()) => any(), :hour => hour(), :minute => minute(), :second => second(), :microsecond => microsecond()}

Any map/struct that contains the time fields

time_zone()

time_zone() :: String.t()

The time zone ID according to the IANA tz database (e.g. Europe/Zurich)

utc_offset()

utc_offset() :: integer()

The time zone UTC offset in seconds

year()

year() :: integer()

zone_abbr()

zone_abbr() :: String.t()

The time zone abbreviation (e.g. CET or CEST or BST etc.)

Callbacks

date_to_string(year, month, day)

date_to_string(year(), month(), day()) :: String.t()

Converts the date into a string according to the calendar.

datetime_to_string(year, month, day, hour, minute, second, microsecond, time_zone, zone_abbr, utc_offset, std_offset)

datetime_to_string(year(), month(), day(), hour(), minute(), second(), microsecond(), time_zone(), zone_abbr(), utc_offset(), std_offset()) :: String.t()

Coverts the date time (with time zone) into a string according to the calendar.

day_of_week(year, month, day)

day_of_week(year(), month(), day()) :: non_neg_integer()

Calculates the day of the week from the given year, month, and day.

days_in_month(year, month)

days_in_month(year(), month()) :: day()

Returns how many days there are in the given year-month.

leap_year?(year)

leap_year?(year()) :: boolean()

Returns true if the given year is a leap year.

A leap year is a year of a longer length than normal. The exact meaning is up to the calendar. A calendar must return false if it does not support the concept of leap years.

naive_datetime_to_string(year, month, day, hour, minute, second, microsecond)

naive_datetime_to_string(year(), month(), day(), hour(), minute(), second(), microsecond()) :: String.t()

Converts the date time (without time zone) into a string according to the calendar.