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

Этот модуль определяет обязанности по работе с календарями, датами, временем и датами-временем в 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/struct, содержащий поля даты

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/struct, содержащий поля даты и времени

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 января до нашей эры пролептического григорианского календаря).

microsecond()Source

@type microsecond() :: {non_neg_integer(), 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/struct, содержащий поля naive_datetime

second()Source

@type second() :: non_neg_integer()

std_offset()Source

@type std_offset() :: integer()

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

Его необходимо добавить к utc_offset/0, чтобы получить общее смещение от UTC, используемое для "времени по часам" (wall time).

time()Source

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

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

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 и т. д.)

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

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 может быть любым из типов Calendar (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
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	Секунда	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	Аббревиатура часового пояса (пустая строка, если неявный)	CET, BRST
%	Буквальный символ "%"	%

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

Примеры

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

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, усечённый до заданной точности (:microsecond, :millisecond или :second).

Настройки Календарь поведение

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

Типы

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

Функции

Типы

calendar()Source

date()Source

datetime()Source

day()Source

day_fraction()Source

day_of_era()Source

day_of_week()Source

era()Source

hour()Source

iso_days()Source

microsecond()Source

minute()Source

month()Source

naive_datetime()Source

second()Source

std_offset()Source

time()Source

time_zone()Source

time_zone_database()Source

utc_offset()Source

week()Source

year()Source

zone_abbr()Source

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

date_to_string(year, month, day)Source

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

day_of_era(year, month, day)Source

day_of_week(year, month, day, starting_on)Source

day_of_year(year, month, day)Source

day_rollover_relative_to_midnight_utc()Source

Примеры

days_in_month(year, month)Source

leap_year?(year)Source

months_in_year(year)Source

naive_datetime_from_iso_days(iso_days)Source

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

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

parse_date(t)Source

parse_naive_datetime(t)Source

parse_time(t)Source

parse_utc_datetime(t)Source

quarter_of_year(year, month, day)Source

time_from_day_fraction(day_fraction)Source

time_to_day_fraction(hour, minute, second, microsecond)Source

time_to_string(hour, minute, second, microsecond)Source

valid_date?(year, month, day)Source

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

year_of_era(year, month, day)Source

Функции

compatible_calendars?(calendar, calendar)Source

get_time_zone_database()Source

put_time_zone_database(database)Source

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

Параметры

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

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

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

Примеры

truncate(microsecond_tuple, atom)Source

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