Calendar behaviour View Source
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.
Link to this section Summary
Types
A calendar implementation
Any map/struct that contains the date fields
Any map/struct that contains the datetime fields
The internal time format is used when converting between calendars
The internal date format that is used when converting between calendars
Microseconds with stored precision
Any map/struct that contains the naive_datetime fields
The time zone standard offset in seconds (not zero in summer times)
Any map/struct that contains the time fields
The time zone ID according to the IANA tz database (e.g. Europe/Zurich)
Specifies the time zone database for calendar operations
The time zone UTC offset in seconds
The time zone abbreviation (e.g. CET or CEST or BST etc.)
Functions
Returns true
if two calendars have the same moment of starting a new day,
false
otherwise
Gets the current time zone database
Sets the current time zone database
Returns a microsecond tuple truncated to a given precision (:microsecond
,
:millisecond
or :second
)
Callbacks
Converts the date into a string according to the calendar
Converts the datetime (with time zone) into a string according to the calendar
Calculates the day and era from the given year
, month
, and day
Calculates the day of the week from the given year
, month
, and day
Calculates the day of the year from the given year
, month
, and day
Define the rollover moment for the given calendar
Returns how many days there are in the given year-month
Returns true
if the given year is a leap year
Returns how many months there are in the given year
Converts iso_days/0
to the Calendar's datetime format
Converts the given datetime (without time zone) into the iso_days/0
format
Converts the datetime (without time zone) into a string according to the calendar
Calculates the quarter of the year from the given year
, month
, and day
Converts day_fraction/0
to the Calendar's time format
Converts the given time to the day_fraction/0
format
Converts the time into a string according to the calendar
Should return true
if the given date describes a proper date in the calendar
Should return true
if the given time describes a proper time in the calendar
Calculates the year and era from the given year
Link to this section Types
calendar()
View Source
calendar() :: module()
calendar() :: module()
A calendar implementation
date() View Source
Any map/struct that contains the date fields
datetime()
View Source
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()
}
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()
View Source
day() :: pos_integer()
day() :: pos_integer()
day_fraction()
View Source
day_fraction() ::
{parts_in_day :: non_neg_integer(), parts_per_day :: pos_integer()}
day_fraction() :: {parts_in_day :: non_neg_integer(), parts_per_day :: pos_integer()}
The internal time format is used when converting between calendars.
It represents time as a fraction of a day (starting from midnight).
parts_in_day
specifies how much of the day is already passed,
while parts_per_day
signifies how many parts there fit in a day.
day_of_week()
View Source
day_of_week() :: non_neg_integer()
day_of_week() :: non_neg_integer()
era()
View Source
era() :: non_neg_integer()
era() :: non_neg_integer()
hour()
View Source
hour() :: non_neg_integer()
hour() :: non_neg_integer()
iso_days()
View Source
iso_days() :: {days :: integer(), day_fraction()}
iso_days() :: {days :: integer(), day_fraction()}
The internal date format that is used when converting between calendars.
This is the number of days including the fractional part that has passed of the last day since 0000-01-01+00:00T00:00.000000 in ISO 8601 notation (also known as midnight 1 January BC 1 of the proleptic Gregorian calendar).
microsecond()
View Source
microsecond() :: {0..999_999, 0..6}
microsecond() :: {0..999_999, 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()
View Source
minute() :: non_neg_integer()
minute() :: non_neg_integer()
month()
View Source
month() :: pos_integer()
month() :: pos_integer()
naive_datetime() View Source
Any map/struct that contains the naive_datetime fields
second()
View Source
second() :: non_neg_integer()
second() :: non_neg_integer()
std_offset()
View Source
std_offset() :: integer()
std_offset() :: integer()
The time zone standard offset in seconds (not zero in summer times)
time() View Source
Any map/struct that contains the time fields
time_zone()
View Source
time_zone() :: String.t()
time_zone() :: String.t()
The time zone ID according to the IANA tz database (e.g. Europe/Zurich)
time_zone_database()
View Source
time_zone_database() :: module()
time_zone_database() :: module()
Specifies the time zone database for calendar operations.
Many functions in the DateTime
module require a time zone database.
By default, it uses the default time zone database returned by
Calendar.get_time_zone_database/0
, which defaults to
Calendar.UTCOnlyTimeZoneDatabase
which only handles "Etc/UTC"
datetimes and returns {:error, :utc_only_time_zone_database}
for any other time zone.
Other time zone databases (including ones provided by packages) can be configure as default either via configuration:
config :elixir, :time_zone_database, CustomTimeZoneDatabase
or by calling Calendar.put_time_zone_database/1
.
See Calendar.TimeZoneDatabase
for more information on custom
time zone databases.
utc_offset()
View Source
utc_offset() :: integer()
utc_offset() :: integer()
The time zone UTC offset in seconds
week()
View Source
week() :: pos_integer()
week() :: pos_integer()
year()
View Source
year() :: integer()
year() :: integer()
zone_abbr()
View Source
zone_abbr() :: String.t()
zone_abbr() :: String.t()
The time zone abbreviation (e.g. CET or CEST or BST etc.)
Link to this section Functions
compatible_calendars?(calendar, calendar)
View Source
(since 1.5.0)
compatible_calendars?(Calendar.calendar(), Calendar.calendar()) :: boolean()
compatible_calendars?(Calendar.calendar(), Calendar.calendar()) :: boolean()
Returns true
if two calendars have the same moment of starting a new day,
false
otherwise.
If two calendars are not compatible, we can only convert datetimes and times between them. If they are compatible, this means that we can also convert dates as well as naive datetimes between them.
get_time_zone_database()
View Source
(since 1.8.0)
get_time_zone_database() :: time_zone_database()
get_time_zone_database() :: time_zone_database()
Gets the current time zone database.
put_time_zone_database(database)
View Source
(since 1.8.0)
put_time_zone_database(time_zone_database()) :: :ok
put_time_zone_database(time_zone_database()) :: :ok
Sets the current time zone database.
truncate(microsecond_tuple, atom)
View Source
(since 1.6.0)
truncate(Calendar.microsecond(), :microsecond | :millisecond | :second) ::
Calendar.microsecond()
truncate(Calendar.microsecond(), :microsecond | :millisecond | :second) :: Calendar.microsecond()
Returns a microsecond tuple truncated to a given precision (:microsecond
,
:millisecond
or :second
).
Link to this section Callbacks
date_to_string(year, month, day) View Source
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)
View Source
datetime_to_string(
year(),
month(),
day(),
hour(),
minute(),
second(),
microsecond(),
time_zone(),
zone_abbr(),
utc_offset(),
std_offset()
) :: String.t()
datetime_to_string( year(), month(), day(), hour(), minute(), second(), microsecond(), time_zone(), zone_abbr(), utc_offset(), std_offset() ) :: String.t()
Converts the datetime (with time zone) into a string according to the calendar.
day_of_era(year, month, day)
View Source
day_of_era(year(), month(), day()) :: {non_neg_integer(), era()}
day_of_era(year(), month(), day()) :: {non_neg_integer(), era()}
Calculates the day and era from the given year
, month
, and day
.
day_of_week(year, month, day)
View Source
day_of_week(year(), month(), day()) :: day_of_week()
day_of_week(year(), month(), day()) :: day_of_week()
Calculates the day of the week from the given year
, month
, and day
.
day_of_year(year, month, day)
View Source
day_of_year(year(), month(), day()) :: non_neg_integer()
day_of_year(year(), month(), day()) :: non_neg_integer()
Calculates the day of the year from the given year
, month
, and day
.
day_rollover_relative_to_midnight_utc()
View Source
day_rollover_relative_to_midnight_utc() :: day_fraction()
day_rollover_relative_to_midnight_utc() :: day_fraction()
Define the rollover moment for the given calendar.
This is the moment, in your calendar, when the current day ends and the next day starts.
The result of this function is used to check if two calendars rollover at the same time of day. If they do not, we can only convert datetimes and times between them. If they do, this means that we can also convert dates as well as naive datetimes between them.
This day fraction should be in its most simplified form possible, to make comparisons fast.
Examples
- If, in your Calendar, a new day starts at midnight, return {0, 1}.
- If, in your Calendar, a new day starts at sunrise, return {1, 4}.
- If, in your Calendar, a new day starts at noon, return {1, 2}.
- If, in your Calendar, a new day starts at sunset, return {3, 4}.
days_in_month(year, month) View Source
Returns how many days there are in the given year-month.
leap_year?(year) View Source
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.
months_in_year(year) View Source
Returns how many months there are in the given year.
naive_datetime_from_iso_days(iso_days) View Source
Converts iso_days/0
to the Calendar's datetime format.
naive_datetime_to_iso_days(year, month, day, hour, minute, second, microsecond) View Source
Converts the given datetime (without time zone) into the iso_days/0
format.
naive_datetime_to_string(year, month, day, hour, minute, second, microsecond) View Source
Converts the datetime (without time zone) into a string according to the calendar.
quarter_of_year(year, month, day)
View Source
quarter_of_year(year(), month(), day()) :: non_neg_integer()
quarter_of_year(year(), month(), day()) :: non_neg_integer()
Calculates the quarter of the year from the given year
, month
, and day
.
time_from_day_fraction(day_fraction)
View Source
time_from_day_fraction(day_fraction()) ::
{hour(), minute(), second(), microsecond()}
time_from_day_fraction(day_fraction()) :: {hour(), minute(), second(), microsecond()}
Converts day_fraction/0
to the Calendar's time format.
time_to_day_fraction(hour, minute, second, microsecond)
View Source
time_to_day_fraction(hour(), minute(), second(), microsecond()) ::
day_fraction()
time_to_day_fraction(hour(), minute(), second(), microsecond()) :: day_fraction()
Converts the given time to the day_fraction/0
format.
time_to_string(hour, minute, second, microsecond)
View Source
time_to_string(hour(), minute(), second(), microsecond()) :: String.t()
time_to_string(hour(), minute(), second(), microsecond()) :: String.t()
Converts the time into a string according to the calendar.
valid_date?(year, month, day) View Source
Should return true
if the given date describes a proper date in the calendar.
valid_time?(hour, minute, second, microsecond)
View Source
valid_time?(hour(), minute(), second(), microsecond()) :: boolean()
valid_time?(hour(), minute(), second(), microsecond()) :: boolean()
Should return true
if the given time describes a proper time in the calendar.
year_of_era(year) View Source
Calculates the year and era from the given year
.