Calendar.ISO

Реализация календаря, которая соответствует ISO 8601.

Этот календарь реализует пролептический григорианский календарь и поэтому совместим с календарём, используемым в большинстве стран сегодня. Пролептический означает, что правила григорианского календаря для високосных лет применяются для всего времени, следовательно, даты дают разные результаты до 1583 года, с момента принятия григорианского календаря.

Обратите внимание, что хотя ISO 8601 позволяет времени и дате-времени указать 24:00:00 как нулевой час следующего дня, эта запись не поддерживается Elixir.

Обзор

Функции

date_to_string(year, month, day, format \\ :extended): Преобразует заданную дату в строку.
datetime_to_string(year, month, day, hour, minute, second, microsecond, time_zone, zone_abbr, utc_offset, std_offset, format \\ :extended): Преобразует дату и время (с часовым поясом) в строку.
day_of_era(year, month, day): Вычисляет день и эру по заданному year, month, и day.
day_of_week(year, month, day): Вычисляет день недели по заданному year, month, и day.
day_of_year(year, month, day): Вычисляет день года по заданному year, month, и day.
day_rollover_relative_to_midnight_utc(): См. Calendar.day_rollover_relative_to_midnight_utc/0 для документации.
days_in_month(year, month): Возвращает количество дней в заданном году-месяце.
leap_year?(year): Возвращает, является ли данный год високосным.
months_in_year(year): Возвращает количество месяцев в данном году.
naive_datetime_from_iso_days(arg): Преобразует формат Calendar.iso_days/0 в формат даты и времени, указанный этим календарём.
naive_datetime_to_iso_days(year, month, day, hour, minute, second, microsecond): Возвращает формат Calendar.iso_days/0 указанной даты.
naive_datetime_to_string(year, month, day, hour, minute, second, microsecond, format \\ :extended): Преобразует дату и время (без часового пояса) в строку.
quarter_of_year(year, month, day): Вычисляет квартал года по заданному year, month, и day.
time_from_day_fraction(arg): Преобразует дробную часть дня в представление времени в этом календаре.
time_to_day_fraction(hour, minute, second, arg): Возвращает нормированную дробную часть дня указанного времени.
time_to_string(hour, minute, second, microsecond, format \\ :extended): Преобразует заданное время в строку.
valid_date?(year, month, day): Определяет, является ли заданная дата действительной в соответствии с пролептическим григорианским календарём.
valid_time?(hour, minute, second, arg): Определяет, является ли заданная дата действительной в соответствии с пролептическим григорианским календарём.
year_of_era(year): Вычисляет год и эру по заданному year.

Типы

day()

Спецификации

day() :: 1..31

month()

Спецификации

month() :: 1..12

year()

Спецификации

year() :: -9999..9999

Функции

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

Характеристики

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

Преобразует заданную дату в строку.

По умолчанию возвращает даты в формате "extended" для лучшей читаемости. Также поддерживается формат "basic", передав опцию :basic.

Примеры

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"

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

Характеристики

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(),
  :basic | :extended
) :: String.t()

Преобразует дату и время (с часовым поясом) в строку.

По умолчанию возвращает даты и время в формате "extended" для лучшей читаемости. Также поддерживается формат "basic", передав опцию :basic.

Примеры

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"

day_of_era(year, month, day)

Характеристики

day_of_era(year(), month(), day()) :: {day :: pos_integer(), era :: 0..1}

Вычисляет день и эру по заданному year, month, и day.

Примеры

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}

day_of_week(year, month, day)

Характеристики

day_of_week(year(), month(), day()) :: 1..7

Вычисляет день недели по заданному year, month, и day.

Это целое число от 1 до 7, где 1 — понедельник, а 7 — воскресенье.

Примеры

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

Характеристики

day_of_year(year(), month(), day()) :: 1..366

Вычисляет день года по заданному year, month, и day.

Это целое число от 1 до 366.

Примеры

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

day_rollover_relative_to_midnight_utc()

Характеристики

day_rollover_relative_to_midnight_utc() :: {0, 1}

См. Calendar.day_rollover_relative_to_midnight_utc/0 для документации.

days_in_month(year, month)

Характеристики

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

Возвращает количество дней в заданном месяце года.

Примеры

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()

Возвращает значение true, если год високосный, иначе false.

Примеры

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)

Характеристики

months_in_year(year()) :: 12

Возвращает количество месяцев в заданном году.

Пример

iex> Calendar.ISO.months_in_year(2004)
12

naive_datetime_from_iso_days(arg)

Характеристики

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

Преобразует формат Calendar.iso_days/0 в формат даты и времени, используемый в этом календаре.

Примеры

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)

Характеристики

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

Возвращает формат Calendar.iso_days/0 заданной даты.

Примеры

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, format \\ :extended)

Характеристики

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

Преобразует дату и время (без часового пояса) в строку.

Примеры

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"

quarter_of_year(year, month, day)

Характеристики

quarter_of_year(year(), month(), day()) :: 1..4

Вычисляет квартал года по заданному year, month, и day.

Это целое число от 1 до 4.

Примеры

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

time_from_day_fraction(arg)

Характеристики

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

Преобразует дробь дня в представление времени в этом календаре.

Примеры

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)

Характеристики

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

Возвращает нормализованную дробь дня указанного времени.

Примеры

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, format \\ :extended)

Характеристики

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

Преобразует заданное время в строку.

По умолчанию возвращает время в формате "extended" для лучшей читаемости. Также поддерживается формат "basic", передав опцию :basic.

Примеры

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"

valid_date?(year, month, day)

Характеристики

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

Определяет, является ли заданная дата действительной в соответствии с пролептическим григорианским календарем.

Примеры

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)

Характеристики

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

Определяет, является ли заданное время действительным в соответствии с пролептическим григорианским календарем.

Обратите внимание, что, хотя ISO 8601 позволяет временам указывать 24:00:00 как нулевой час следующего дня, такая запись не поддерживается в Elixir. Также встроенный календарь Calendar.ISO не поддерживает високосные секунды.

Примеры

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

year_of_era(year)

Характеристики

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

Вычисляет год и эру по заданному year.

Календарь ISO имеет две эры: текущая, начинающаяся с года 1 (эра "1"), и вторая эра для лет меньших 1 (эра "0").

Примеры

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}