Calendar.ISO

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.

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.

Summary

Functions

date_to_string(year, month, day): Converts the given date into a string
datetime_to_string(year, month, day, hour, minute, second, microsecond, time_zone, zone_abbr, utc_offset, std_offset): Converts the datetime (with time zone) into a string
day_of_week(year, month, day): Calculates the day of the week from the given year, month, and day
day_rollover_relative_to_midnight_utc(): See Calendar.day_rollover_relative_to_midlight_utc/0 for documentation
days_in_month(year, month): Returns how many days there are in the given year-month
leap_year?(year): Returns if the given year is a leap year
months_in_year(year): Returns how many months there are in the given year
naive_datetime_from_iso_days(arg): Converts the Calendar.iso_days/0 format to the datetime format specified by this calendar
naive_datetime_to_iso_days(year, month, day, hour, minute, second, microsecond): Returns the Calendar.iso_days/0 format of the specified date
naive_datetime_to_string(year, month, day, hour, minute, second, microsecond): Converts the datetime (without time zone) into a string
time_from_day_fraction(arg): Converts a day fraction to this Calendar’s representation of time
time_to_day_fraction(hour, minute, second, arg): Returns the normalized day fraction of the specified time
time_to_string(hour, minute, second, microsecond): Converts the given time into a string
time_to_string(hour, minute, second, arg, format)
valid_date?(year, month, day): Determines if the date given is valid according to the proleptic Gregorian calendar
valid_time?(hour, minute, second, arg): Determines if the date given is valid according to the proleptic Gregorian calendar. Note that leap seconds are considered valid, but the use of 24:00:00 as the zero hour of the day is considered invalid

Types

day()

day() :: 1..31

month()

month() :: 1..12

year()

year() :: -9999..9999

Functions

date_to_string(year, month, day)

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

Converts the given date into a string.

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"

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

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

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

Examples

iex> Calendar.ISO.datetime_to_string(2017, 8, 1, 1, 2, 3, {4, 5}, "Europe/Berlin", "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}, "Europe/Berlin", "CDT", 3600, 3600)
"2017-08-01 01:02:03.00000+02:00 CDT Europe/Berlin"
iex> Calendar.ISO.datetime_to_string(2015, 2, 28, 1, 2, 3, {4, 5}, "America/Los_Angeles", "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}, "America/Los_Angeles", "PDT", -28800, 3600)
"2015-02-28 01:02:03.00000-07:00 PDT America/Los_Angeles"

day_of_week(year, month, day)

day_of_week(year(), month(), day()) :: 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 Monday and 7 is Sunday.

Examples

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

day_rollover_relative_to_midnight_utc() (since 1.5.0)

day_rollover_relative_to_midnight_utc() :: {0, 1}

See Calendar.day_rollover_relative_to_midlight_utc/0 for documentation.

days_in_month(year, month)

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

leap_year?(year)

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

months_in_year(year) (since 1.7.0)

months_in_year(year()) :: 12

Returns how many months there are in the given year.

Example

iex> Calendar.ISO.months_in_year(2004)
12

naive_datetime_from_iso_days(arg) (since 1.5.0)

naive_datetime_from_iso_days(Calendar.iso_days()) ::
  {Calendar.year(), Calendar.month(), Calendar.day(), Calendar.hour(),
   Calendar.minute(), Calendar.second(), Calendar.microsecond()}

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}}

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

naive_datetime_to_iso_days(
  Calendar.year(),
  Calendar.month(),
  Calendar.day(),
  Calendar.hour(),
  Calendar.minute(),
  Calendar.second(),
  Calendar.microsecond()
) :: Calendar.iso_days()

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}}

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

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

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

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"

time_from_day_fraction(arg) (since 1.5.0)

time_from_day_fraction(Calendar.day_fraction()) ::
  {Calendar.hour(), Calendar.minute(), Calendar.second(),
   Calendar.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}}

time_to_day_fraction(hour, minute, second, arg) (since 1.5.0)

time_to_day_fraction(
  Calendar.hour(),
  Calendar.minute(),
  Calendar.second(),
  Calendar.microsecond()
) :: Calendar.day_fraction()

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}

time_to_string(hour, minute, second, microsecond)

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

Converts the given time into a string.

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"

time_to_string(hour, minute, second, arg, format)

valid_date?(year, month, day) (since 1.5.0)

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

valid_time?(hour, minute, second, arg) (since 1.5.0)

valid_time?(
  Calendar.hour(),
  Calendar.minute(),
  Calendar.secon(),
  Calendar.microsecond()
) :: boolean()

Determines if the date given is valid according to the proleptic Gregorian calendar. Note that leap seconds are considered valid, but the use of 24:00:00 as the zero hour of the day is considered invalid.

Examples

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