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

Этот модуль определяет обязанности по работе с календарями, датами, временем и датами и временем в 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 (например, Europe/Zurich)
time_zone_database(): Указывает базу данных часовых поясов для операций с календарём.
utc_offset(): Смещение часового пояса UTC в секундах для стандартного времени.
week()
year()
zone_abbr(): Аббревиатура часового пояса (например, CET или CEST или BST, и т. д.)

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

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, starting_on): Вычисляет день недели из заданных 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(t): Парсит строковое представление даты, возвращаемое date_to_string/3, в кортеж даты.
parse_naive_datetime(t): Парсит строковое представление naive datetime, возвращаемое naive_datetime_to_string/7, в кортеж naive datetime.
parse_time(t): Парсит строковое представление времени, возвращаемое time_to_string/4, в кортеж времени.
parse_utc_datetime(t): Парсит строковое представление datetime, возвращаемое 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, month, day): Вычисляет год и эру из заданных year.

Функции

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

Типы

calendar()Source

@type calendar() :: module()

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

date()Source

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

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

datetime()Source

@type 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()
}

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

day()Source

@type day() :: pos_integer()

day_fraction()Source

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

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

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

day_of_era()Source

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

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

day_of_week()Source

@type day_of_week() :: non_neg_integer()

era()Source

@type era() :: non_neg_integer()

hour()Source

@type hour() :: non_neg_integer()

iso_days()Source

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

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

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

microsecond()Source

@type microsecond() :: {value :: non_neg_integer(), precision :: non_neg_integer()}

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

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

minute()Source

@type minute() :: non_neg_integer()

month()Source

@type month() :: pos_integer()

naive_datetime()Source

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

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

second()Source

@type second() :: non_neg_integer()

std_offset()Source

@type std_offset() :: integer()

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

Он должен быть добавлен к utc_offset/0 для получения общего смещения от UTC, используемого для «времени по часам».

time()Source

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

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

time_zone()Source

@type time_zone() :: String.t()

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

time_zone_database()Source

@type 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()Source

@type utc_offset() :: integer()

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

См. также std_offset/0.

week()Source

@type week() :: pos_integer()

year()Source

@type year() :: integer()

zone_abbr()Source

@type zone_abbr() :: String.t()

Аббревиатура часового пояса (например, CET или CEST или BST, и т. д.)

Обработчики

date_to_string(year, month, day)Source

@callback 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 )Source

@callback 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)Source

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

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

day_of_week(year, month, day, starting_on)Source

@callback day_of_week(year(), month(), day(), starting_on :: :default | atom()) ::
  {day_of_week(), first_day_of_week :: non_neg_integer(),
   last_day_of_week :: non_neg_integer()}

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

starting_on представляет собой начальный день недели. Все календари должны поддерживать по крайней мере значение :default. Они также могут поддерживать другие значения, представляющие их дни недели.

day_of_year(year, month, day)Source

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

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

day_rollover_relative_to_midnight_utc()Source

@callback day_rollover_relative_to_midnight_utc() :: day_fraction()

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

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

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

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

Примеры

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

days_in_month(year, month)Source

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

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

leap_year?(year)Source

@callback leap_year?(year()) :: boolean()

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

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

months_in_year(year)Source

@callback months_in_year(year()) :: month()

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

naive_datetime_from_iso_days(iso_days)Source

@callback 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)Source

@callback 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)Source

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

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

parse_date(t)Source

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

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

parse_naive_datetime(t)Source

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

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

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

parse_time(t)Source

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

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

parse_utc_datetime(t)Source

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

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

Возвращаемая дата и время должны быть в формате UTC. Изначальный utc_offset должен быть сохранён в результате.

quarter_of_year(year, month, day)Source

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

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

time_from_day_fraction(day_fraction)Source

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

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

time_to_day_fraction(hour, minute, second, microsecond)Source

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

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

time_to_string(hour, minute, second, microsecond)Source

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

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

valid_date?(year, month, day)Source

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

Должно вернуть true если заданная дата описывает корректную дату в календаре.

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

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

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

year_of_era(year, month, day)Source

@callback year_of_era(year(), month(), day()) :: {year(), era()}

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

Функции

compatible_calendars?(calendar, calendar)Source

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

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

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

get_time_zone_database()Source

@spec get_time_zone_database() :: time_zone_database()

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

put_time_zone_database(database)Source

@spec put_time_zone_database(time_zone_database()) :: :ok

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

strftime(date_or_time_or_datetime, string_format, user_options \\ [])Source

@spec strftime(map(), String.t(), keyword()) :: String.t()

Форматирует полученное значение datetime в строку.

Значение datetime может быть любым типом календаря (Time, Date, NaiveDateTime и DateTime) или любой мапой, если она содержит все необходимые поля для форматирования. Например, если вы используете %Y для форматирования года, значение datetime должно содержать поле :year. Поэтому, если вы передаёте Time или карту без поля :year в формат, ожидающий %Y, будет поднято исключение.

Параметры

:preferred_datetime - строка с предпочтительным форматом отображения значений datetime, она не может содержать формат %c и по умолчанию равна "%Y-%m-%d %H:%M:%S", если параметр не передан
:preferred_date - строка с предпочтительным форматом отображения дат, она не может содержать формат %x и по умолчанию равна "%Y-%m-%d", если параметр не передан
:preferred_time - строка с предпочтительным форматом отображения времени, она не может содержать формат %X и по умолчанию равна "%H:%M:%S", если параметр не передан
:am_pm_names - функция, которая получает либо :am , либо :pm и возвращает название периода дня, если параметр не передан, то по умолчанию возвращает "am" и "pm", соответственно
:month_names - функция, которая получает число и возвращает название соответствующего месяца, если параметр не передан, по умолчанию возвращает названия месяцев на английском языке
:abbreviated_month_names - функция, которая получает число и возвращает сокращённое название соответствующего месяца, если параметр не передан, по умолчанию возвращает сокращённые названия месяцев на английском языке
:day_of_week_names - функция, которая получает число и возвращает название соответствующего дня недели, если параметр не передан, по умолчанию возвращает названия дней недели на английском языке
:abbreviated_day_of_week_names - функция, которая получает число и возвращает сокращённое название соответствующего дня недели, если параметр не передан, по умолчанию возвращает сокращённые названия дней недели на английском языке

Синтаксис форматирования

Синтаксис форматирования для strftime — это последовательность символов в следующем формате:

%<padding><width><format>

где:

%: обозначает начало форматируемого раздела
<padding>: устанавливает выравнивание (см. ниже)
<width>: число, определяющее минимальный размер форматируемого раздела
<format>: сам формат (см. ниже)

Допустимые варианты выравнивания

-: без выравнивания, удаляет все выравнивания из формата
_: выравнивание пробелами
0: выравнивание нулями

Допустимые форматы

Допустимые форматы:

Формат	Описание	Примеры (в ISO)
a	Сокращённое название дня	Пн
A	Полное название дня	Понедельник
b	Сокращённое название месяца	Янв
B	Полное название месяца	Январь
c	Предпочтительное представление даты и времени	2018-10-17 12:34:56
d	Число месяца	01, 31
f	Микросекунды (не поддерживает ширину и модификаторы выравнивания)	000000, 999999, 0123

Любой другой символ будет интерпретирован как недопустимый формат и вызовет ошибку

Примеры

Без параметров:

iex> Calendar.strftime(~U[2019-08-26 13:52:06.0Z], "%y-%m-%d %I:%M:%S %p")
"19-08-26 01:52:06 PM"

iex> Calendar.strftime(~U[2019-08-26 13:52:06.0Z], "%a, %B %d %Y")
"Mon, August 26 2019"

iex> Calendar.strftime(~U[2020-04-02 13:52:06.0Z], "%B %-d, %Y")
"April 2, 2020"

iex> Calendar.strftime(~U[2019-08-26 13:52:06.0Z], "%c")
"2019-08-26 13:52:06"

С параметрами:

iex> Calendar.strftime(~U[2019-08-26 13:52:06.0Z], "%c", preferred_datetime: "%H:%M:%S %d-%m-%y")
"13:52:06 26-08-19"

iex> Calendar.strftime(
...>  ~U[2019-08-26 13:52:06.0Z],
...>  "%A",
...>  day_of_week_names: fn day_of_week ->
...>    {"segunda-feira", "terça-feira", "quarta-feira", "quinta-feira",
...>    "sexta-feira", "sábado", "domingo"}
...>    |> elem(day_of_week - 1)
...>  end
...>)
"segunda-feira"

iex> Calendar.strftime(
...>  ~U[2019-08-26 13:52:06.0Z],
...>  "%B",
...>  month_names: fn month ->
...>    {"январь", "февраль", "март", "апрель", "май", "июнь",
...>    "июль", "август", "сентябрь", "октябрь", "ноябрь", "декабрь"}
...>    |> elem(month - 1)
...>  end
...>)
"август"

truncate(microsecond_tuple, atom)Source

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

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