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

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

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

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

Типы для года, месяца, дня и других значений переопределены. Например, тип month/0 указан как целое число вместо 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(): Любой массив или структура, содержащие поля даты и времени без учёта часового пояса.
second()
std_offset(): Стандартное смещение часового пояса в секундах (как правило, не равно нулю в летнее время).
time(): Любой массив или структура, содержащие поля времени.
time_zone(): Идентификатор часового пояса в соответствии с базой данных IANA tz (например, Europe/Zurich).
time_zone_database(): Указывает базу данных часовых поясов для операций с календарём.
utc_offset(): Смещение часового пояса относительно UTC в секундах для стандартного времени.
week()
year()
zone_abbr(): Аббревиатура часового пояса (например, CET, CEST, или BST).

Обработчики

END_OF_DOCUMENT_MARKER

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

Любой 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 или структура, содержащая поля даты и времени без часового пояса.

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 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 в секундах для стандартного времени.

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

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

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

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

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

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 если заданная дата описывает корректную дату в календаре.

END_OF_DOCUMENT_MARKER

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:

Формат	Описание	Примеры (в ISO)
a	Сокращённое название дня	Пн
A	Полное название дня	Понедельник
b	Сокращённое название месяца	Янв
B	Полное название месяца	Январь
c	Предпочтительное представление даты+времени	2018-10-17 12:34:56
d	День месяца	01, 31
f	Микросекунды (не поддерживает ширину и модификаторы отступа)	000000, 999999, 0123
H	Час, используя 24-часовой формат	00, 23
I	Час, используя 12-часовой формат	01, 12
j	День года	001, 366
m	Месяц	01, 12
M	Минута	00, 59
p	"ДП" или "НП" (полдень — "НП", полночь — "ДП")	ДП, НП
P	"дп" или "нп" (полдень — "нп", полночь — "дп")	дп, нп
q	Квартал	1, 2, 3, 4
s	Количество секунд с эпохи, 1970-01-01 00:00:00+0000 (UTC)	1565888877
S	Секунда	00, 59, 60
u	День недели	1 (Понедельник), 7 (Воскресенье)
x	Предпочтительное представление даты (без времени)	2018-10-17
X	Предпочтительное представление времени (без даты)	12:34:56
y	Год в формате 2 цифр	01, 01, 86, 18
Y	Год	-0001, 0001, 1986
z	+hhmm/-hhmm смещение часового пояса от UTC (пустая строка, если неявное)	+0300, -0530
Z	Аббревиатура часового пояса (пустая строка, если неявное)	ВОСТ, ЦЕТ
%	Буквальный символ "%"	%

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

Примеры

Без параметров пользователя:

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.16.3/Calendar.html