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

Этот модуль определяет обязанности по работе с календарями, датами, временем и датами и временем в 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).

Вызовы обратного вызова

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): Преобразует 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, используемый для "времени по часам" (wall time).

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

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

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	"AM" или "PM" (полдень "PM", полночь "AM")	AM, PM
P	"am" или "pm" (полдень "pm", полночь "am")	am, pm
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	Смещение часового пояса от UTC (+hhmm/-hhmm) (пустая строка, если неявное)	+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, :millisecond, или :second).