Исходный код Календарь поведение

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

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

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

Типы для года, месяца, дня и других элементов переопределены. Например, тип month/0 указан как целое число вместо 1..12. Это связано с тем, что разные календари могут иметь разное количество дней в месяце.

Обзор

Типы

календарь(): Реализация календаря.
дата(): Любой массив или структура, содержащая поля даты.
дата-время(): Любой массив или структура, содержащая поля даты и времени.
день()
дробная_часть_дня(): Внутренний формат времени используется при преобразовании между календарями.
день_эры(): Кортеж, представляющий day и era.
день_недели()
эра()
час()
дни_ISO(): Внутренний формат даты, используемый при преобразовании между календарями.
микросекунда(): Микросекунды с сохранённой точностью.
минута()
месяц()
простая_дата_время(): Любой массив или структура, содержащая поля простой даты и времени.
секунда()
стандартная_поправка(): Стандартная поправка часового пояса в секундах ISO (обычно не ноль в летнее время).
время(): Любой массив или структура, содержащая поля времени.
часовой_пояс(): Идентификатор часового пояса согласно базе данных IANA tz (например, Europe/Zurich).
база_данных_часовых_поясов(): Указывает базу данных часовых поясов для операций с календарём.
смещение_UTC(): Смещение часового пояса в секундах UTC для стандартного времени.
неделя()
год()
сокращение_часового_пояса(): Сокращение часового пояса (например, 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): Возвращает количество дней в заданном месяце заданного года.
iso_days_to_beginning_of_day(iso_days): Преобразует заданные iso_days/0 в первый момент дня.
iso_days_to_end_of_day(iso_days): Преобразует заданные iso_days/0 в последний момент дня.
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): Преобразует naive 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.
shift_date(year, month, day, t): Смещает дату на заданную продолжительность в соответствии с календарем.
shift_naive_datetime(year, month, day, hour, minute, second, microsecond, t): Смещает naive datetime на заданную продолжительность в соответствии с календарем.
shift_time(hour, minute, second, microsecond, t): Смещает время на заданную продолжительность в соответствии с календарем.
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 \\ []): Форматирует заданную дату, время или datetime в строку.
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()
}

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

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

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

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

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

second()Source

@type second() :: non_neg_integer()

std_offset()Source

@type std_offset() :: integer()

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

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

time()Source

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

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

time_zone()Source

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

Идентификатор часового пояса согласно базе данных IANA tz (например, 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 в секундах ISO для стандартного времени.

См. также 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).

END_OF_DOCUMENT_MARKER

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

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

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

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

Определяет момент перехода на следующий день для календаря.

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

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

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

Примеры

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

days_in_month(year, month)Source

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

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

iso_days_to_beginning_of_day(iso_days)Source

@callback iso_days_to_beginning_of_day(iso_days()) :: iso_days()

Преобразует заданные iso_days/0 в первый момент дня.

iso_days_to_end_of_day(iso_days)Source

@callback iso_days_to_end_of_day(iso_days()) :: iso_days()

Преобразует заданные iso_days/0 в последний момент дня.

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 в формат datetime календаря.

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

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

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

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

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

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

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, возвращённое datetime_to_string/11, в кортеж datetime.

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

quarter_of_year(year, month, day)Source

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

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

shift_date(year, month, day, t)Source

@callback shift_date(year(), month(), day(), Duration.t()) :: {year(), month(), day()}

Сдвигает дату на заданный интервал времени согласно календарю.

shift_naive_datetime(year, month, day, hour, minute, second, microsecond, t)Source

@callback shift_naive_datetime(
  year(),
  month(),
  day(),
  hour(),
  minute(),
  second(),
  microsecond(),
  Duration.t()
) :: {year(), month(), day(), hour(), minute(), second(), microsecond()}

Сдвигает неявное datetime на заданный интервал времени согласно календарю.

shift_time(hour, minute, second, microsecond, t)Source

@callback shift_time(hour(), minute(), second(), microsecond(), Duration.t()) ::
  {hour(), minute(), second(), microsecond()}

Сдвигает время на заданный интервал времени согласно календарю.

time_from_day_fraction(day_fraction)Source

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

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

END_OF_DOCUMENT_MARKER

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 в противном случае.

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

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

Форматирует заданную дату, время или дату и время в строку.

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

Примеры распространённого использования:

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"

Параметры пользователя

:preferred_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 - функция, которая получает число и возвращает сокращённое название соответствующего дня недели, если параметр не получен, он по умолчанию возвращает сокращённые названия дней недели на английском языке

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

Синтаксис форматирования для аргумента string_format представляет собой последовательность символов в следующем формате:

%<padding><width><format>

где:

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

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

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

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

Допустимые форматы для string_format:

... (rest of the table)

Формат	Описание	Примеры (в 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).

© 2012-2024 The Elixir Team
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.18.1/Calendar.html