Calendar.ISO

Стандартная реализация календаря, григорианский календарь, соответствующий ISO 8601.

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

Соответствие ISO 8601

Спецификация ISO 8601 богата функциями, но позволяет приложениям выборочно реализовывать большинство её частей. Выбор, сделанный Elixir, перечислен ниже.

Функции

Стандартная библиотека поддерживает минимальный набор возможных функций ISO 8601. В частности, парсер поддерживает только даты календаря и не поддерживает форматы порядковых и недельных дат.

По умолчанию Elixir парсит только даты/времена в расширенном формате. Вы можете включить парсинг дат/времени в базовом формате.

NaiveDateTime.to_iso8601/2 и DateTime.to_iso8601/2 позволяют создавать строки в базовом или расширенном формате, а Calendar.strftime/2 позволяет форматировать даты и время любым желаемым образом.

Elixir не поддерживает форматы с пониженной точностью (например, дата без компоненты дня) или десятичной точности в самом младшем компоненте (например, 10:01:25,5). Нет функций для парсинга интервалов или продолжительности ISO 8601.

Примеры

Elixir по умолчанию ожидает расширенный формат при парсинге:

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("20150123T235007")
{:error, :invalid_format}

Парсинг можно ограничить базовым, если это необходимо:

iex> Calendar.ISO.parse_naive_datetime("20150123T235007Z", :basic)
{:ok, {2015, 1, 23, 23, 50, 7, {0, 0}}}
iex> Calendar.ISO.parse_naive_datetime("20150123T235007Z", :extended)
{:error, :invalid_format}

При парсинге поддерживаются только даты календаря; порядковые и недельные даты не поддерживаются.

iex> Calendar.ISO.parse_date("2015-04-15")
{:ok, {2015, 4, 15}}
iex> Calendar.ISO.parse_date("2015-105")
{:error, :invalid_format}
iex> Calendar.ISO.parse_date("2015-W16")
{:error, :invalid_format}
iex> Calendar.ISO.parse_date("2015-W016-3")
{:error, :invalid_format}

Года, месяцы, дни, часы, минуты и секунды должны быть полностью указаны:

iex> Calendar.ISO.parse_date("2015-04-15")
{:ok, {2015, 4, 15}}
iex> Calendar.ISO.parse_date("2015-04")
{:error, :invalid_format}
iex> Calendar.ISO.parse_date("2015")
{:error, :invalid_format}

iex> Calendar.ISO.parse_time("23:50:07.0123456")
{:ok, {23, 50, 7, {12345, 6}}}
iex> Calendar.ISO.parse_time("23:50:07")
{:ok, {23, 50, 7, {0, 0}}}
iex> Calendar.ISO.parse_time("23:50")
{:error, :invalid_format}
iex> Calendar.ISO.parse_time("23")
{:error, :invalid_format}

Расширения

Парсер и форматировщик используют одно расширение ISO 8601: расширенную запись года.

Это позволяет датам предшествовать знак + или -, расширяя диапазон выражаемых лет от значения по умолчанию (0000..9999) до -9999..9999. Elixir по-прежнему ограничивает годы в этом формате четырьмя цифрами.

Примеры

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_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-23 23:50:07")
{:ok, {2015, 1, 23, 23, 50, 7, {0, 0}}}

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

Дополнения

ISO 8601 не допускает пробел вместо T в качестве разделителя между датой и временем при парсинге и форматировании. Это достаточно распространённое представление, и Elixir позволяет его при парсинге.

Форматирование дат в NaiveDateTime.to_iso8601/1 и DateTime.to_iso8601/1 действительно генерируют соответствующие спецификации строковые представления, используя разделитель T.

Примеры

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.0123456")
{:ok, {2015, 1, 23, 23, 50, 7, {12345, 6}}}

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

Типы

bce(): "До нашей эры" (до 1).
ce(): «Наша эра» (начало в году 1).
day()
day_of_week(): Целое число, представляющее день недели, где 1 — понедельник, а 7 — воскресенье.
day_of_year()
era(): Эра календаря.
format()
hour()
microsecond(): Микросекунды с хранимой точностью.
minute()
month()
quarter_of_year()
second()
utc_offset()
weekday()
year()
year_of_era()

Функции

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): Преобразует datetime (с часовым поясом) в строку.
day_of_era(year, month, day): Вычисляет день и эру по заданному year, month, и day.
day_of_week(year, month, day, starting_on): Вычисляет день недели по заданному 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): Возвращает количество дней в заданном году-месяце.
iso_days_to_beginning_of_day(arg): Преобразует Calendar.iso_days/0 в первый момент дня.
iso_days_to_end_of_day(arg): Преобразует Calendar.iso_days/0 в последний момент дня.
leap_year?(year): Возвращает, является ли данный год високосным.
months_in_year(year): Возвращает количество месяцев в данном году.
naive_datetime_from_iso_days(arg): Преобразует формат Calendar.iso_days/0 в формат datetime, заданный этим календарём.
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): Преобразует datetime (без часового пояса) в строку.
parse_date(string): Парсит дату string в формате :extended.
parse_date(string, format): Парсит дату string в соответствии с заданным format.
parse_naive_datetime(string): Парсит неявное datetime string в формате :extended.
parse_naive_datetime(string, format): Парсит неявное datetime string в соответствии с заданным format.
parse_time(string): Парсит время string в формате :extended.
parse_time(string, format): Парсит время string в соответствии с заданным format.
parse_utc_datetime(string): Парсит UTC datetime string в формате :extended.
parse_utc_datetime(string, format): Парсит UTC datetime string в соответствии с заданным format.
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): Преобразует заданное время в строку.
time_unit_to_precision(int): Преобразует System.time_unit/0 в точность.
valid_date?(year, month, day): Определяет, является ли заданная дата допустимой в соответствии с пролептическим григорианским календарём.
valid_time?(hour, minute, second, microsecond): Определяет, является ли заданное время допустимым в соответствии с пролептическим григорианским календарём.
year_of_era(year): Вычисляет год и эру по заданному year.
year_of_era(year, month, day): Обработчик календаря для вычисления года и эры по заданному year, month и day.

bce()Source

@type bce() :: 0

"До нашей эры" или "До новой эры" (до н. э.), для тех лет, которые меньше 1.

ce()Source

@type ce() :: 1

«Наша эра» или «Новая эра» (н. э.), которая начинается в году 1.

day()Source

@type day() :: 1..31

day_of_week()Source

@type day_of_week() :: 1..7

Целое число, представляющее день недели, где 1 — понедельник, а 7 — воскресенье.

day_of_year()Source

@type day_of_year() :: 1..366

era()Source

@type era() :: bce() | ce()

Эра календаря.

Календарь ISO имеет две эры:

CE - которая начинается в году 1 и определяется как эра 1.
BCE - для тех лет, которые меньше 1 и определяется как эра 0.

format()Source

@type format() :: :basic | :extended

hour()Source

@type hour() :: 0..23

microsecond()Source

@type microsecond() :: {0..999_999, 0..6}

Микросекунды с сохранённой точностью.

Точность соответствует числу цифр, которые должны использоваться при представлении микросекунд во внешнем формате. Если точность равна 0, это означает, что микросекунды следует пропускать.

minute()Source

@type minute() :: 0..59

month()Source

@type month() :: 1..12

quarter_of_year()Source

@type quarter_of_year() :: 1..4

second()Source

@type second() :: 0..59

utc_offset()Source

@type utc_offset() :: integer()

weekday()Source

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

year()Source

@type year() :: -9999..9999

year_of_era()Source

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

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

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

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

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

Calendar.ISO

Примеры

Примеры

Примеры

Типы

Функции

bce()Source

ce()Source

day()Source

day_of_week()Source

day_of_year()Source

era()Source

format()Source

hour()Source

microsecond()Source

minute()Source

month()Source

quarter_of_year()Source

second()Source

utc_offset()Source

weekday()Source

year()Source

year_of_era()Source

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

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

day_of_era(year, month, day)Source

day_of_week(year, month, day, starting_on)Source

day_of_year(year, month, day)Source

day_rollover_relative_to_midnight_utc()Source

days_in_month(year, month)Source

iso_days_to_beginning_of_day(arg)Source

iso_days_to_end_of_day(arg)Source

leap_year?(year)Source

months_in_year(year)Source

naive_datetime_from_iso_days(arg)Source

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

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

parse_date(string)Source

parse_date(string, format)Source

parse_naive_datetime(string)Source

parse_naive_datetime(string, format)Source

parse_time(string)Source

parse_time(string, format)Source

parse_utc_datetime(string)Source

parse_utc_datetime(string, format)Source

quarter_of_year(year, month, day)Source

time_from_day_fraction(arg)Source

time_to_day_fraction(hour, minute, second, arg)Source

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

time_unit_to_precision(int)Source

valid_date?(year, month, day)Source

valid_time?(hour, minute, second, microsecond)Source

year_of_era(year)Source

year_of_era(year, month, day)Source