Calendar.ISO (Elixir v1.12.0-dev) View Source

A calendar implementation that follows to ISO 8601.

This calendar implements the proleptic Gregorian calendar and is therefore compatible with the calendar used in most countries today. The proleptic means the Gregorian rules for leap years are applied for all time, consequently the dates give different results before the year 1583 from when the Gregorian calendar was adopted.

Given this is the default calendar used by Elixir, it has one difference compared to the ISO8601 specification in that it allows a whitespace instead of T as a seperator between date and times both when parsing and formatting. Strict formatting can be done by using the to_iso8601 found in NaiveDateTime and DateTime.

Note that while ISO 8601 allows times and datetimes to specify 24:00:00 as the zero hour of the next day, this notation is not supported by Elixir.

Link to this section Summary

Types

"Before the Current Era" or "Before the Common Era" (BCE), for those years less than 1.

The "Current Era" or the "Common Era" (CE) which starts in year 1.

Integer that represents the day of the week, where 1 is Monday and 7 is Sunday.

The calendar era.

Microseconds with stored precision.

Functions

Converts the given date into a string.

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.

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

Returns if the given year is a leap year.

Returns how many months there are in the given year.

Converts the Calendar.iso_days/0 format to the datetime format specified by this calendar.

Parses a date string.

Parses a naive datetime string.

Parses a time string.

Parses a UTC datetime string.

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

Converts a day fraction to this Calendar's representation of time.

Returns the normalized day fraction of the specified time.

Determines if the date given is valid according to the proleptic Gregorian calendar.

Determines if the date given is valid according to the proleptic Gregorian calendar.

Calculates the year and era from the given year.

Link to this section Types

Specs

bce() :: 0

"Before the Current Era" or "Before the Common Era" (BCE), for those years less than 1.

Specs

ce() :: 1

The "Current Era" or the "Common Era" (CE) which starts in year 1.

Specs

day() :: 1..31

Specs

day_of_week() :: 1..7

Integer that represents the day of the week, where 1 is Monday and 7 is Sunday.

Specs

day_of_year() :: 1..366

Specs

era() :: bce() | ce()

The calendar era.

The ISO calendar has two eras:

  • CE - which starts in year 1 and is defined as era 1.
  • BCE - for those years less than 1 and is defined as era 0.

Specs

hour() :: 0..23

Specs

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.

Specs

minute() :: 0..59

Specs

month() :: 1..12

Specs

quarter_of_year() :: 1..4

Specs

second() :: 0..59

Specs

weekday() ::
  :monday | :tuesday | :wednesday | :thursday | :friday | :saturday | :sunday

Specs

year() :: -9999..9999

Specs

year_of_era() :: {1..10000, era()}

Link to this section Functions

Link to this function

date_to_string(year, month, day, format \\ :extended)

View Source (since 1.4.0)

Specs

date_to_string(year(), month(), day(), :basic | :extended) :: String.t()

Converts the given date into a string.

By default, returns dates formatted in the "extended" format, for human readability. It also supports the "basic" format by passing the :basic option.

Examples

iex> Calendar.ISO.date_to_string(2015, 2, 28)
"2015-02-28"
iex> Calendar.ISO.date_to_string(2017, 8, 1)
"2017-08-01"
iex> Calendar.ISO.date_to_string(-99, 1, 31)
"-0099-01-31"

iex> Calendar.ISO.date_to_string(2015, 2, 28, :basic)
"20150228"
iex> Calendar.ISO.date_to_string(-99, 1, 31, :basic)
"-00990131"
Link to this function

datetime_to_string(year, month, day, hour, minute, second, microsecond, time_zone, zone_abbr, utc_offset, std_offset, format \\ :extended)

View Source (since 1.4.0)

Specs

Converts the datetime (with time zone) into a string.

By default, returns datetimes formatted in the "extended" format, for human readability. It also supports the "basic" format by passing the :basic option.

Examples

iex> time_zone = "Etc/UTC"
iex> Calendar.ISO.datetime_to_string(2017, 8, 1, 1, 2, 3, {4, 5}, time_zone, "UTC", 0, 0)
"2017-08-01 01:02:03.00000Z"
iex> Calendar.ISO.datetime_to_string(2017, 8, 1, 1, 2, 3, {4, 5}, time_zone, "UTC", 3600, 0)
"2017-08-01 01:02:03.00000+01:00"
iex> Calendar.ISO.datetime_to_string(2017, 8, 1, 1, 2, 3, {4, 5}, time_zone, "UTC", 3600, 3600)
"2017-08-01 01:02:03.00000+02:00"

iex> time_zone = "Europe/Berlin"
iex> Calendar.ISO.datetime_to_string(2017, 8, 1, 1, 2, 3, {4, 5}, time_zone, "CET", 3600, 0)
"2017-08-01 01:02:03.00000+01:00 CET Europe/Berlin"
iex> Calendar.ISO.datetime_to_string(2017, 8, 1, 1, 2, 3, {4, 5}, time_zone, "CDT", 3600, 3600)
"2017-08-01 01:02:03.00000+02:00 CDT Europe/Berlin"

iex> time_zone = "America/Los_Angeles"
iex> Calendar.ISO.datetime_to_string(2015, 2, 28, 1, 2, 3, {4, 5}, time_zone, "PST", -28800, 0)
"2015-02-28 01:02:03.00000-08:00 PST America/Los_Angeles"
iex> Calendar.ISO.datetime_to_string(2015, 2, 28, 1, 2, 3, {4, 5}, time_zone, "PDT", -28800, 3600)
"2015-02-28 01:02:03.00000-07:00 PDT America/Los_Angeles"

iex> time_zone = "Europe/Berlin"
iex> Calendar.ISO.datetime_to_string(2017, 8, 1, 1, 2, 3, {4, 5}, time_zone, "CET", 3600, 0, :basic)
"20170801 010203.00000+0100 CET Europe/Berlin"
Link to this function

day_of_era(year, month, day)

View Source (since 1.8.0)

Specs

day_of_era(year(), month(), day()) :: Calendar.day_of_era()

Calculates the day and era from the given year, month, and day.

Examples

iex> Calendar.ISO.day_of_era(0, 1, 1)
{366, 0}
iex> Calendar.ISO.day_of_era(1, 1, 1)
{1, 1}
iex> Calendar.ISO.day_of_era(0, 12, 31)
{1, 0}
iex> Calendar.ISO.day_of_era(0, 12, 30)
{2, 0}
iex> Calendar.ISO.day_of_era(-1, 12, 31)
{367, 0}
Link to this function

day_of_week(year, month, day, starting_on)

View Source (since 1.11.0)

Specs

day_of_week(year(), month(), day(), :default | weekday()) ::
  {day_of_week(), 1, 7}

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

It is an integer from 1 to 7, where 1 is the given starting_on weekday. For example, if starting_on is set to :monday, then 1 is Monday and 7 is Sunday.

starting_on can also be :default, which is equivalent to :monday.

Examples

iex> Calendar.ISO.day_of_week(2016, 10, 31, :monday)
{1, 1, 7}
iex> Calendar.ISO.day_of_week(2016, 11, 1, :monday)
{2, 1, 7}
iex> Calendar.ISO.day_of_week(2016, 11, 2, :monday)
{3, 1, 7}
iex> Calendar.ISO.day_of_week(2016, 11, 3, :monday)
{4, 1, 7}
iex> Calendar.ISO.day_of_week(2016, 11, 4, :monday)
{5, 1, 7}
iex> Calendar.ISO.day_of_week(2016, 11, 5, :monday)
{6, 1, 7}
iex> Calendar.ISO.day_of_week(2016, 11, 6, :monday)
{7, 1, 7}
iex> Calendar.ISO.day_of_week(-99, 1, 31, :monday)
{4, 1, 7}

iex> Calendar.ISO.day_of_week(2016, 10, 31, :sunday)
{2, 1, 7}
iex> Calendar.ISO.day_of_week(2016, 11, 1, :sunday)
{3, 1, 7}
iex> Calendar.ISO.day_of_week(2016, 11, 2, :sunday)
{4, 1, 7}
iex> Calendar.ISO.day_of_week(2016, 11, 3, :sunday)
{5, 1, 7}
iex> Calendar.ISO.day_of_week(2016, 11, 4, :sunday)
{6, 1, 7}
iex> Calendar.ISO.day_of_week(2016, 11, 5, :sunday)
{7, 1, 7}
iex> Calendar.ISO.day_of_week(2016, 11, 6, :sunday)
{1, 1, 7}
iex> Calendar.ISO.day_of_week(-99, 1, 31, :sunday)
{5, 1, 7}

iex> Calendar.ISO.day_of_week(2016, 10, 31, :saturday)
{3, 1, 7}
Link to this function

day_of_year(year, month, day)

View Source (since 1.8.0)

Specs

day_of_year(year(), month(), day()) :: day_of_year()

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

It is an integer from 1 to 366.

Examples

iex> Calendar.ISO.day_of_year(2016, 1, 31)
31
iex> Calendar.ISO.day_of_year(-99, 2, 1)
32
iex> Calendar.ISO.day_of_year(2018, 2, 28)
59
Link to this function

day_rollover_relative_to_midnight_utc()

View Source (since 1.5.0)

Specs

day_rollover_relative_to_midnight_utc() :: {0, 1}

See Calendar.day_rollover_relative_to_midnight_utc/0 for documentation.

Link to this function

days_in_month(year, month)

View Source (since 1.4.0)

Specs

days_in_month(year(), month()) :: 28..31

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

Examples

iex> Calendar.ISO.days_in_month(1900, 1)
31
iex> Calendar.ISO.days_in_month(1900, 2)
28
iex> Calendar.ISO.days_in_month(2000, 2)
29
iex> Calendar.ISO.days_in_month(2001, 2)
28
iex> Calendar.ISO.days_in_month(2004, 2)
29
iex> Calendar.ISO.days_in_month(2004, 4)
30
iex> Calendar.ISO.days_in_month(-1, 5)
31
Link to this function

leap_year?(year)

View Source (since 1.3.0)

Specs

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

Returns if the given year is a leap year.

Examples

iex> Calendar.ISO.leap_year?(2000)
true
iex> Calendar.ISO.leap_year?(2001)
false
iex> Calendar.ISO.leap_year?(2004)
true
iex> Calendar.ISO.leap_year?(1900)
false
iex> Calendar.ISO.leap_year?(-4)
true
Link to this function

months_in_year(year)

View Source (since 1.7.0)

Specs

months_in_year(year()) :: 12

Returns how many months there are in the given year.

Example

iex> Calendar.ISO.months_in_year(2004)
12
Link to this function

naive_datetime_from_iso_days(arg)

View Source (since 1.5.0)

Specs

Converts the Calendar.iso_days/0 format to the datetime format specified by this calendar.

Examples

iex> Calendar.ISO.naive_datetime_from_iso_days({0, {0, 86400}})
{0, 1, 1, 0, 0, 0, {0, 6}}
iex> Calendar.ISO.naive_datetime_from_iso_days({730_485, {0, 86400}})
{2000, 1, 1, 0, 0, 0, {0, 6}}
iex> Calendar.ISO.naive_datetime_from_iso_days({730_485, {43200, 86400}})
{2000, 1, 1, 12, 0, 0, {0, 6}}
iex> Calendar.ISO.naive_datetime_from_iso_days({-365, {0, 86400000000}})
{-1, 1, 1, 0, 0, 0, {0, 6}}
Link to this function

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

View Source (since 1.5.0)

Specs

Returns the Calendar.iso_days/0 format of the specified date.

Examples

iex> Calendar.ISO.naive_datetime_to_iso_days(0, 1, 1, 0, 0, 0, {0, 6})
{0, {0, 86400000000}}
iex> Calendar.ISO.naive_datetime_to_iso_days(2000, 1, 1, 12, 0, 0, {0, 6})
{730485, {43200000000, 86400000000}}
iex> Calendar.ISO.naive_datetime_to_iso_days(2000, 1, 1, 13, 0, 0, {0, 6})
{730485, {46800000000, 86400000000}}
iex> Calendar.ISO.naive_datetime_to_iso_days(-1, 1, 1, 0, 0, 0, {0, 6})
{-365, {0, 86400000000}}
Link to this function

naive_datetime_to_string(year, month, day, hour, minute, second, microsecond, format \\ :extended)

View Source (since 1.4.0)

Specs

naive_datetime_to_string(
  year(),
  month(),
  day(),
  Calendar.hour(),
  Calendar.minute(),
  Calendar.second(),
  Calendar.microsecond(),
  :basic | :extended
) :: String.t()

Converts the datetime (without time zone) into a string.

By default, returns datetimes formatted in the "extended" format, for human readability. It also supports the "basic" format by passing the :basic option.

Examples

iex> Calendar.ISO.naive_datetime_to_string(2015, 2, 28, 1, 2, 3, {4, 6})
"2015-02-28 01:02:03.000004"
iex> Calendar.ISO.naive_datetime_to_string(2017, 8, 1, 1, 2, 3, {4, 5})
"2017-08-01 01:02:03.00000"

iex> Calendar.ISO.naive_datetime_to_string(2015, 2, 28, 1, 2, 3, {4, 6}, :basic)
"20150228 010203.000004"
Link to this function

parse_date(string)

View Source (since 1.10.0)

Parses a date string.

Examples

iex> Calendar.ISO.parse_date("2015-01-23")
{:ok, {2015, 1, 23}}
iex> Calendar.ISO.parse_date("-2015-01-23")
{:ok, {-2015, 1, 23}}
iex> Calendar.ISO.parse_date("2015:01:23")
{:error, :invalid_format}
iex> Calendar.ISO.parse_date("2015-01-32")
{:error, :invalid_date}
Link to this function

parse_naive_datetime(string)

View Source (since 1.10.0)

Parses a naive datetime string.

Examples

iex> Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:07")
{:ok, {2015, 1, 23, 23, 50, 7, {0, 0}}}
iex> Calendar.ISO.parse_naive_datetime("2015-01-23T23:50:07")
{:ok, {2015, 1, 23, 23, 50, 7, {0, 0}}}
iex> Calendar.ISO.parse_naive_datetime("2015-01-23T23:50:07Z")
{:ok, {2015, 1, 23, 23, 50, 7, {0, 0}}}

iex> Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:07.0")
{:ok, {2015, 1, 23, 23, 50, 7, {0, 1}}}
iex> Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:07,0123456")
{:ok, {2015, 1, 23, 23, 50, 7, {12345, 6}}}
iex> Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:07.0123456")
{:ok, {2015, 1, 23, 23, 50, 7, {12345, 6}}}
iex> Calendar.ISO.parse_naive_datetime("2015-01-23T23:50:07.123Z")
{:ok, {2015, 1, 23, 23, 50, 7, {123000, 3}}}

iex> Calendar.ISO.parse_naive_datetime("2015-01-23P23:50:07")
{:error, :invalid_format}
iex> Calendar.ISO.parse_naive_datetime("2015:01:23 23-50-07")
{:error, :invalid_format}
iex> Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:07A")
{:error, :invalid_format}
iex> Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:61")
{:error, :invalid_time}
iex> Calendar.ISO.parse_naive_datetime("2015-01-32 23:50:07")
{:error, :invalid_date}

iex> Calendar.ISO.parse_naive_datetime("2015-01-23T23:50:07.123+02:30")
{:ok, {2015, 1, 23, 23, 50, 7, {123000, 3}}}
iex> Calendar.ISO.parse_naive_datetime("2015-01-23T23:50:07.123+00:00")
{:ok, {2015, 1, 23, 23, 50, 7, {123000, 3}}}
iex> Calendar.ISO.parse_naive_datetime("2015-01-23T23:50:07.123-02:30")
{:ok, {2015, 1, 23, 23, 50, 7, {123000, 3}}}
iex> Calendar.ISO.parse_naive_datetime("2015-01-23T23:50:07.123-00:00")
{:error, :invalid_format}
iex> Calendar.ISO.parse_naive_datetime("2015-01-23T23:50:07.123-00:60")
{:error, :invalid_format}
iex> Calendar.ISO.parse_naive_datetime("2015-01-23T23:50:07.123-24:00")
{:error, :invalid_format}
Link to this function

parse_time(string)

View Source (since 1.10.0)

Parses a time string.

Examples

iex> Calendar.ISO.parse_time("23:50:07")
{:ok, {23, 50, 7, {0, 0}}}
iex> Calendar.ISO.parse_time("23:50:07Z")
{:ok, {23, 50, 7, {0, 0}}}
iex> Calendar.ISO.parse_time("T23:50:07Z")
{:ok, {23, 50, 7, {0, 0}}}

iex> Calendar.ISO.parse_time("23:50:07,0123456")
{:ok, {23, 50, 7, {12345, 6}}}
iex> Calendar.ISO.parse_time("23:50:07.0123456")
{:ok, {23, 50, 7, {12345, 6}}}
iex> Calendar.ISO.parse_time("23:50:07.123Z")
{:ok, {23, 50, 7, {123000, 3}}}

iex> Calendar.ISO.parse_time("2015:01:23 23-50-07")
{:error, :invalid_format}
iex> Calendar.ISO.parse_time("23:50:07A")
{:error, :invalid_format}
iex> Calendar.ISO.parse_time("23:50:07.")
{:error, :invalid_format}
iex> Calendar.ISO.parse_time("23:50:61")
{:error, :invalid_time}
Link to this function

parse_utc_datetime(string)

View Source (since 1.10.0)

Parses a UTC datetime string.

Examples

iex> Calendar.ISO.parse_utc_datetime("2015-01-23T23:50:07Z")
{:ok, {2015, 1, 23, 23, 50, 7, {0, 0}}, 0}

iex> Calendar.ISO.parse_utc_datetime("2015-01-23T23:50:07.123+02:30")
{:ok, {2015, 1, 23, 21, 20, 7, {123000, 3}}, 9000}

iex> Calendar.ISO.parse_utc_datetime("2015-01-23T23:50:07,123+02:30")
{:ok, {2015, 1, 23, 21, 20, 7, {123000, 3}}, 9000}

iex> Calendar.ISO.parse_utc_datetime("-2015-01-23T23:50:07Z")
{:ok, {-2015, 1, 23, 23, 50, 7, {0, 0}}, 0}

iex> Calendar.ISO.parse_utc_datetime("-2015-01-23T23:50:07,123+02:30")
{:ok, {-2015, 1, 23, 21, 20, 7, {123000, 3}}, 9000}

iex> Calendar.ISO.parse_utc_datetime("2015-01-23P23:50:07")
{:error, :invalid_format}
iex> Calendar.ISO.parse_utc_datetime("2015-01-23T23:50:07")
{:error, :missing_offset}
iex> Calendar.ISO.parse_utc_datetime("2015-01-23 23:50:61")
{:error, :invalid_time}
iex> Calendar.ISO.parse_utc_datetime("2015-01-32 23:50:07")
{:error, :invalid_date}
iex> Calendar.ISO.parse_utc_datetime("2015-01-23T23:50:07.123-00:00")
{:error, :invalid_format}
Link to this function

quarter_of_year(year, month, day)

View Source (since 1.8.0)

Specs

quarter_of_year(year(), month(), day()) :: quarter_of_year()

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

It is an integer from 1 to 4.

Examples

iex> Calendar.ISO.quarter_of_year(2016, 1, 31)
1
iex> Calendar.ISO.quarter_of_year(2016, 4, 3)
2
iex> Calendar.ISO.quarter_of_year(-99, 9, 31)
3
iex> Calendar.ISO.quarter_of_year(2018, 12, 28)
4
Link to this function

time_from_day_fraction(arg)

View Source (since 1.5.0)

Specs

time_from_day_fraction(Calendar.day_fraction()) ::
  {hour(), minute(), second(), microsecond()}

Converts a day fraction to this Calendar's representation of time.

Examples

iex> Calendar.ISO.time_from_day_fraction({1, 2})
{12, 0, 0, {0, 6}}
iex> Calendar.ISO.time_from_day_fraction({13, 24})
{13, 0, 0, {0, 6}}
Link to this function

time_to_day_fraction(hour, minute, second, arg)

View Source (since 1.5.0)

Specs

Returns the normalized day fraction of the specified time.

Examples

iex> Calendar.ISO.time_to_day_fraction(0, 0, 0, {0, 6})
{0, 86400000000}
iex> Calendar.ISO.time_to_day_fraction(12, 34, 56, {123, 6})
{45296000123, 86400000000}
Link to this function

time_to_string(hour, minute, second, microsecond, format \\ :extended)

View Source (since 1.5.0)

Specs

time_to_string(
  Calendar.hour(),
  Calendar.minute(),
  Calendar.second(),
  Calendar.microsecond(),
  :basic | :extended
) :: String.t()

Converts the given time into a string.

By default, returns times formatted in the "extended" format, for human readability. It also supports the "basic" format by passing the :basic option.

Examples

iex> Calendar.ISO.time_to_string(2, 2, 2, {2, 6})
"02:02:02.000002"
iex> Calendar.ISO.time_to_string(2, 2, 2, {2, 2})
"02:02:02.00"
iex> Calendar.ISO.time_to_string(2, 2, 2, {2, 0})
"02:02:02"

iex> Calendar.ISO.time_to_string(2, 2, 2, {2, 6}, :basic)
"020202.000002"
iex> Calendar.ISO.time_to_string(2, 2, 2, {2, 6}, :extended)
"02:02:02.000002"
Link to this function

valid_date?(year, month, day)

View Source (since 1.5.0)

Specs

valid_date?(year(), month(), day()) :: boolean()

Determines if the date given is valid according to the proleptic Gregorian calendar.

Examples

iex> Calendar.ISO.valid_date?(2015, 2, 28)
true
iex> Calendar.ISO.valid_date?(2015, 2, 30)
false
iex> Calendar.ISO.valid_date?(-1, 12, 31)
true
iex> Calendar.ISO.valid_date?(-1, 12, 32)
false
Link to this function

valid_time?(hour, minute, second, microsecond)

View Source (since 1.5.0)

Specs

Determines if the date given is valid according to the proleptic Gregorian calendar.

Note that while ISO 8601 allows times to specify 24:00:00 as the zero hour of the next day, this notation is not supported by Elixir. Leap seconds are not supported as well by the built-in Calendar.ISO.

Examples

iex> Calendar.ISO.valid_time?(10, 50, 25, {3006, 6})
true
iex> Calendar.ISO.valid_time?(23, 59, 60, {0, 0})
false
iex> Calendar.ISO.valid_time?(24, 0, 0, {0, 0})
false
Link to this function

year_of_era(year)

View Source (since 1.8.0)

Specs

year_of_era(year()) :: {1..10000, era()}

Calculates the year and era from the given year.

The ISO calendar has two eras: the "current era" (CE) which starts in year 1 and is defined as era 1. And "before the current era" (BCE) for those years less than 1, defined as era 0.

Examples

iex> Calendar.ISO.year_of_era(1)
{1, 1}
iex> Calendar.ISO.year_of_era(2018)
{2018, 1}
iex> Calendar.ISO.year_of_era(0)
{1, 0}
iex> Calendar.ISO.year_of_era(-1)
{2, 0}