Elixir

v1.8.1

Calendar.ISO 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.

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

day()
month()
year()

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_era(year, month, day)

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

day_of_week(year, month, day)

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

day_of_year(year, month, day)

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

day_rollover_relative_to_midnight_utc()

See Calendar.day_rollover_relative_to_midnight_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

quarter_of_year(year, month, day)

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

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

year_of_era(year)

Calculates the year and era from the given year

Link to this section Types

Link to this type

month() View Source 
month() :: 1..12

Link to this type

year() View Source 
year() :: -9999..9999

Link to this section Functions

Link to this function

date_to_string(year, month, day) View Source 
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"
Link to this function

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(),
  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> 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"
Link to this function

day_of_era(year, month, day) View Source (since 1.8.0) 
day_of_era(year(), month(), day()) :: {day :: pos_integer(), era :: 0..1}

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) View Source 
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
Link to this function

day_of_year(year, month, day) View Source (since 1.8.0) 
day_of_year(year(), month(), day()) :: 1..366

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) 
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 
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 
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) 
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) 
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}}
Link to this function

naive_datetime_to_iso_days(year, month, day, hour, minute, second, microsecond) View Source (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}}
Link to this function

naive_datetime_to_string(year, month, day, hour, minute, second, microsecond) View Source 
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"
Link to this function

quarter_of_year(year, month, day) View Source (since 1.8.0) 
quarter_of_year(year(), month(), day()) :: 1..4

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) 
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}}
Link to this function

time_to_day_fraction(hour, minute, second, arg) View Source (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}
Link to this function

time_to_string(hour, minute, second, microsecond) View Source 
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"
Link to this function

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

Link to this function

valid_date?(year, month, day) View Source (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
Link to this function

valid_time?(hour, minute, second, arg) View Source (since 1.5.0) 
valid_time?(
  Calendar.hour(),
  Calendar.minute(),
  Calendar.second(),
  Calendar.microsecond()
) :: boolean()

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) 
year_of_era(year()) :: {year(), era :: 0..1}

Calculates the year and era from the given year.

The ISO calendar has two eras: the current era which starts in year 1 and is defined as era "1". And a second era 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}