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

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

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

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

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

Обзор

Типы

calendar(): Реализация календаря
date(): Любой массив/структура, содержащий поля даты
datetime(): Любой массив/структура, содержащий поля даты-времени
day()
day_fraction(): Внутренний формат времени используется при преобразовании между календарями.
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): Преобразует дату-время (с часовым поясом) в строку в соответствии с календарём.
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 в формат даты-времени календаря.
naive_datetime_to_iso_days(year, month, day, hour, minute, second, microsecond): Преобразует заданную дату-время (без часового пояса) в формат iso_days/0.
naive_datetime_to_string(year, month, day, hour, minute, second, microsecond): Преобразует дату-время (без часового пояса) в строку в соответствии с календарём.
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_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() :: {0..999_999, 0..6}

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

Точность представляет собой количество цифр, которые должны быть использованы при представлении микросекунд во внешнем формате. Если точность равна 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(), Calendar.calendar()) :: boolean()

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

Если два календаря не совместимы, мы можем преобразовывать только даты и время между ними. Если они совместимы, это означает, что мы также можем преобразовывать даты и 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(Calendar.microsecond(), :microsecond | :millisecond | :second) ::
  Calendar.microsecond()

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

END_OF_DOCUMENT_MARKER

Обработчики событий

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

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

day_of_era(year, month, day)

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

day_of_era(year(), month(), day()) :: {non_neg_integer(), 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()

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

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

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

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

Примеры

Если в вашем календаре новый день начинается в полночь, верните {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 в формат даты и времени календаря.

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

Преобразует заданное время (без часового пояса) в формат 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()

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

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.