Календарь поведение

Этот модуль определяет обязанности по работе с календарями, датами, временами и датами-временами в Elixir.

В настоящее время он определяет типы и минимальную реализацию поведения календаря в Elixir. Цель функций календаря в Elixir — предоставить базу для межпрограммной совместимости вместо полнофункционального API для работы с датами и временем.

Для фактических структур даты, времени и даты-времени см. Date, Time, NaiveDateTime и DateTime.

Примечание: обозначения для года, месяца, дня и т.п. избыточны (т.е. целое число вместо 1..12 для месяцев), потому что разные календари могут иметь разное количество дней в месяце, месяцев в году и т.д.

Краткое описание

Типы

calendar(): Реализация календаря
date(): Любой массив/структура, содержащая поля даты
datetime(): Любой массив/структура, содержащая поля даты и времени
day()
day_fraction(): Внутренний формат времени используется при преобразовании между календарями.
day_of_era(): Кортеж, представляющий day и era.
day_of_week()
era()
hour()
iso_days(): Внутренний формат даты, используемый при преобразовании между календарями.
microsecond(): Микросекунды с сохранённой точностью.
minute()
month()
naive_datetime(): Любой массив/структура, содержащая поля naive_datetime
second()
std_offset(): Стандартное смещение часового пояса в секундах (не ноль в летнее время)
time(): Любой массив/структура, содержащая поля времени
time_zone(): Идентификатор часового пояса согласно базе данных IANA tz (например, Europe/Zurich)
time_zone_database(): Указывает базу данных часовых поясов для календарных операций.
utc_offset(): Смещение часового пояса UTC в секундах
week()
year()
zone_abbr(): Аббревиатура часового пояса (например, CET, CEST или BST)

Функции

compatible_calendars?(calendar, calendar): Возвращает true, если два календаря имеют одинаковый момент начала нового дня, false, в противном случае.
get_time_zone_database(): Получает текущую базу данных часовых поясов.
put_time_zone_database(database): Устанавливает текущую базу данных часовых поясов.
truncate(microsecond_tuple, atom): Возвращает кортеж микросекунд, усеченный до заданной точности (:microsecond, :millisecond или :second).

Обратные вызовы

date_to_string(year, month, day): Преобразует дату в строку в соответствии с календарём.
datetime_to_string(year, month, day, hour, minute, second, microsecond, time_zone, zone_abbr, utc_offset, std_offset): Преобразует datetime (с часовым поясом) в строку в соответствии с календарём.
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(): Определяет момент перехода для данного календаря.
days_in_month(year, month): Возвращает количество дней в данном месяце года.
leap_year?(year): Возвращает true, если заданный год является високосным.
months_in_year(year): Возвращает количество месяцев в данном году.
naive_datetime_from_iso_days(iso_days): Преобразует iso_days/0 в формат datetime календаря.
naive_datetime_to_iso_days(year, month, day, hour, minute, second, microsecond): Преобразует заданный datetime (без часового пояса) в формат iso_days/0.
naive_datetime_to_string(year, month, day, hour, minute, second, microsecond): Преобразует datetime (без часового пояса) в строку в соответствии с календарём.
parse_date(arg1): Разбирает строковое представление даты, возвращённое date_to_string/3, в кортеж даты.
parse_naive_datetime(arg1): Разбирает строковое представление даты без часового пояса, возвращённое naive_datetime_to_string/7, в кортеж naive-datetime.
parse_time(arg1): Разбирает строковое представление времени, возвращённое time_to_string/4, в кортеж времени.
parse_utc_datetime(arg1): Разбирает строковое представление даты с UTC, возвращённое datetime_to_string/11, в кортеж datetime.
quarter_of_year(year, month, day): Вычисляет квартал года по заданным year, month, и day.
time_from_day_fraction(day_fraction): Преобразует day_fraction/0 в формат времени календаря.
time_to_day_fraction(hour, minute, second, microsecond): Преобразует заданное время в формат day_fraction/0.
time_to_string(hour, minute, second, microsecond): Преобразует время в строку в соответствии с календарём.
valid_date?(year, month, day): Должно возвращать true, если заданная дата является корректной.
valid_time?(hour, minute, second, microsecond): Должно возвращать true, если заданное время является корректным.
year_of_era(year): Вычисляет год и эру по заданному year.

END_OF_DOCUMENT_MARKER

Типы

calendar()

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

calendar() :: module()

Реализация календаря

date()

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

date() :: %{
  optional(any()) => any(),
  :calendar => calendar(),
  :year => year(),
  :month => month(),
  :day => day()
}

Любой массив/структура, содержащий поля даты

datetime()

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

datetime() :: %{
  optional(any()) => any(),
  :calendar => calendar(),
  :year => year(),
  :month => month(),
  :day => day(),
  :hour => hour(),
  :minute => minute(),
  :second => second(),
  :microsecond => microsecond(),
  :time_zone => time_zone(),
  :zone_abbr => zone_abbr(),
  :utc_offset => utc_offset(),
  :std_offset => std_offset()
}

Любой массив/структура, содержащий поля даты и времени

day()

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

day() :: pos_integer()

day_fraction()

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

day_fraction() ::
  {parts_in_day :: non_neg_integer(), parts_per_day :: pos_integer()}

Внутренний формат времени используется при преобразовании между календарями.

Он представляет время как долю дня (начиная с полуночи). parts_in_day указывает, сколько времени прошло, а parts_per_day — сколько частей укладывается в день.

day_of_era()

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

day_of_era() :: {day :: non_neg_integer(), era()}

Кортеж, представляющий day и era.

day_of_week()

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

day_of_week() :: non_neg_integer()

era()

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

era() :: non_neg_integer()

hour()

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

hour() :: non_neg_integer()

iso_days()

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

iso_days() :: {days :: integer(), day_fraction()}

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

Это количество дней, включая дробную часть прошедшего дня с 0000-01-01+00:00T00:00.000000 в формате ISO 8601 (также известный как полночь 1 января до н. э. пролептического григорианского календаря).

microsecond()

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

microsecond() :: {non_neg_integer(), non_neg_integer()}

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

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

minute()

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

minute() :: non_neg_integer()

month()

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

month() :: pos_integer()

naive_datetime()

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

naive_datetime() :: %{
  optional(any()) => any(),
  :calendar => calendar(),
  :year => year(),
  :month => month(),
  :day => day(),
  :hour => hour(),
  :minute => minute(),
  :second => second(),
  :microsecond => microsecond()
}

Любой массив/структура, содержащий поля naive_datetime

second()

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

second() :: non_neg_integer()

std_offset()

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

std_offset() :: integer()

Стандартное смещение часового пояса во секундах (не ноль в летнее время)

time()

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

time() :: %{
  optional(any()) => any(),
  :hour => hour(),
  :minute => minute(),
  :second => second(),
  :microsecond => microsecond()
}

Любой массив/структура, содержащий поля времени

time_zone()

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

time_zone() :: String.t()

Идентификатор часового пояса по базе данных IANA tz (например, Europe/Zurich)

time_zone_database()

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

time_zone_database() :: module()

Указывает базу данных часовых поясов для операций с календарём.

Многие функции в модуле DateTime требуют базы данных часовых поясов. По умолчанию используется база данных по умолчанию, возвращаемая Calendar.get_time_zone_database/0, которая по умолчанию устанавливает Calendar.UTCOnlyTimeZoneDatabase, которая обрабатывает только даты и время "Etc/UTC" и возвращает {:error, :utc_only_time_zone_database} для любого другого часового пояса.

Другие базы данных часовых поясов (включая те, которые предоставляются пакетами) можно настроить по умолчанию либо через конфигурацию:

config :elixir, :time_zone_database, CustomTimeZoneDatabase

либо вызвав Calendar.put_time_zone_database/1.

См. Calendar.TimeZoneDatabase для получения дополнительной информации о пользовательских базах данных часовых поясов.

utc_offset()

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

utc_offset() :: integer()

Смещение часового пояса от UTC в секундах

week()

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

week() :: pos_integer()

year()

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

year() :: integer()

zone_abbr()

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

zone_abbr() :: String.t()

Сокращение часового пояса (например, CET или CEST или BST, и т. д.)

Функции

compatible_calendars?(calendar, calendar)

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

compatible_calendars?(calendar(), calendar()) :: boolean()

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

Если два календаря несовместимы, мы можем преобразовывать только datetime и time между ними. Если они совместимы, это означает, что мы также можем преобразовывать даты и naive datetime между ними.

get_time_zone_database()

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

get_time_zone_database() :: time_zone_database()

Получает текущую базу данных часовых поясов.

put_time_zone_database(database)

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

put_time_zone_database(time_zone_database()) :: :ok

Устанавливает текущую базу данных часовых поясов.

truncate(microsecond_tuple, atom)

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

truncate(microsecond(), :microsecond | :millisecond | :second) :: microsecond()

Возвращает кортеж микросекунд, усечённый до заданной точности (:microsecond, :millisecond или :second).

Функции обратного вызова

date_to_string(year, month, day)

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

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

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

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

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

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

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

day_of_era(year, month, day)

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

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

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

day_of_week(year, month, day)

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

day_of_week(year(), month(), day()) :: day_of_week()

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

day_of_year(year, month, day)

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

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

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

day_rollover_relative_to_midnight_utc()

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

day_rollover_relative_to_midnight_utc() :: day_fraction()

Определяет момент перехода для данного календаря.

Это момент в вашем календаре, когда заканчивается текущий день и начинается следующий.

Результат этой функции используется для проверки, переходят ли два календаря в новый день в одно и то же время. Если нет, мы можем только преобразовывать datetime и время между ними. Если да, это означает, что мы также можем преобразовывать даты и неявные datetime между ними.

Эта доля дня должна быть представлена в максимально упрощенном виде для ускорения сравнений.

Примеры

Если в вашем календаре новый день начинается в полночь, верните {0, 1}.
Если в вашем календаре новый день начинается на рассвете, верните {1, 4}.
Если в вашем календаре новый день начинается в полдень, верните {1, 2}.
Если в вашем календаре новый день начинается на закате, верните {3, 4}.

days_in_month(year, month)

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

days_in_month(year(), month()) :: day()

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

leap_year?(year)

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

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

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

Високосный год — это год, длина которого больше обычной. Точное значение зависит от календаря. Календарь должен возвращать false , если он не поддерживает понятие високосных лет.

months_in_year(year)

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

months_in_year(year()) :: month()

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

naive_datetime_from_iso_days(iso_days)

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

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

Преобразует iso_days/0 в формат datetime календаря.

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

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

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

Преобразует заданный datetime (без часового пояса) в формат iso_days/0.

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

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

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

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

parse_date(arg1)

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

parse_date(String.t()) :: {:ok, {year(), month(), day()}} | {:error, atom()}

Парсит строковое представление даты, возвращенное функцией date_to_string/3, в кортеж даты.

parse_naive_datetime(arg1)

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

parse_naive_datetime(String.t()) ::
  {:ok, {year(), month(), day(), hour(), minute(), second(), microsecond()}}
  | {:error, atom()}

Парсит строковое представление неявного datetime, возвращенное функцией naive_datetime_to_string/7, в кортеж неявного datetime.

Заданная строка может содержать смещение часового пояса, но оно игнорируется.

parse_time(arg1)

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

parse_time(String.t()) ::
  {:ok, {hour(), minute(), second(), microsecond()}} | {:error, atom()}

Парсит строковое представление времени, возвращенное функцией time_to_string/4, в кортеж времени.

parse_utc_datetime(arg1)

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

parse_utc_datetime(String.t()) ::
  {:ok, {year(), month(), day(), hour(), minute(), second(), microsecond()},
   utc_offset()}
  | {:error, atom()}

Парсит строковое представление datetime, возвращенное функцией datetime_to_string/11, в кортеж datetime.

Возвращаемый datetime должен быть в формате UTC. Исходный utc_offset , в котором он был написан, должен быть возвращен в результате.

quarter_of_year(year, month, day)

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

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

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

time_from_day_fraction(day_fraction)

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

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

Преобразует day_fraction/0 в формат времени календаря.

time_to_day_fraction(hour, minute, second, microsecond)

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

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

Преобразует заданное время в формат day_fraction/0.

time_to_string(hour, minute, second, microsecond)

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

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

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

valid_date?(year, month, day)

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

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

Должно возвращать true , если заданная дата соответствует корректной дате в календаре.

valid_time?(hour, minute, second, microsecond)

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

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

Должно возвращать true , если заданное время соответствует корректной временной отметке в календаре.

year_of_era(year)

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

year_of_era(year()) :: {year(), era()}

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