Дата

Структура Date и функции.

Структура Date содержит поля год, месяц, день и календарь. Новые даты можно создать с помощью функции new/3 или используя сигил ~D (см. Kernel.sigil_D/2):

iex> ~D[2000-01-01]
~D[2000-01-01]

Оба new/3 и сигил возвращают структуру, где к полям даты можно обратиться напрямую:

iex> date = ~D[2000-01-01]
iex> date.year
2000
iex> date.month
1

Функции в этом модуле работают со структурой Date, а также с любой структурой, содержащей те же поля, что и структура Date, такие как NaiveDateTime и DateTime. Такие функции ожидают Calendar.date/0 в своих описаниях типов (вместо t/0).

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

Сравнение дат

Сравнения в Elixir с использованием ==/2, >/2, </2 и аналогичных основаны на полях структуры Date. Для правильного сравнения дат используйте функцию compare/2.

Использование эпох

Функции add/2 и diff/2 могут использоваться для вычисления дат или получения количества дней между моментами. Например, если необходимо вычислить количество дней с момента эпохи Unix (1970-01-01):

iex> Date.diff(~D[2010-04-17], ~D[1970-01-01])
14716

iex> Date.add(~D[1970-01-01], 14716)
~D[2010-04-17]

Эти функции оптимизированы для работы с распространёнными эпохами, такими как эпоха Unix выше или эпоха Григорианского календаря (0000-01-01).

Обзор

Типы

t()

Функции

add(date, days): Добавляет заданное количество дней к заданной date.
compare(date1, date2): Сравнивает две структуры дат.
convert(date, calendar): Преобразует заданную date из её календаря в заданный calendar.
convert!(date, calendar): Аналогично Date.convert/2, но вызывает исключение ArgumentError, если преобразование между двумя календарями невозможно.
day_of_era(date): Вычисляет день эры и эру для заданного календаря date.
day_of_week(date): Вычисляет день недели для заданной date.
day_of_year(date): Вычисляет день года для заданной date.
days_in_month(date): Возвращает количество дней в заданном date месяце.
diff(date1, date2): Вычисляет разницу между двумя датами в полных днях.
from_erl(tuple, calendar \\ Calendar.ISO): Преобразует кортеж Erlang в структуру даты Date.
from_erl!(tuple, calendar \\ Calendar.ISO): Преобразует кортеж Erlang, но вызывает исключение для недействительных дат.
from_iso8601(string, calendar \\ Calendar.ISO): Парсит расширенный формат "Dates", описанный в ISO 8601:2004.
from_iso8601!(string, calendar \\ Calendar.ISO): Парсит расширенный формат "Dates", описанный в ISO 8601:2004.
leap_year?(date): Возвращает true, если год в заданной date является високосным.
months_in_year(date): Возвращает количество месяцев в заданном date году.
new(year, month, day, calendar \\ Calendar.ISO): Создаёт новую дату ISO.
quarter_of_year(date): Вычисляет квартал года для заданной date.
range(first, last): Возвращает диапазон дат.
to_erl(date): Преобразует заданную date в кортеж Erlang.
to_iso8601(date, format \\ :extended): Преобразует заданную date в ISO 8601:2004.
to_string(date): Преобразует заданную дату в строку в соответствии с её календарём.
utc_today(calendar \\ Calendar.ISO): Возвращает текущую дату в формате UTC.
year_of_era(date): Вычисляет год эры и эру для заданного года календаря.

Типы

t()

t() :: %Date{
  calendar: Calendar.calendar(),
  day: Calendar.day(),
  month: Calendar.month(),
  year: Calendar.year()
}

Функции

add(date, days)

(с 1.5.0)

add(Calendar.date(), integer()) :: t()

Добавляет заданное количество дней к заданной date.

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

Примеры

iex> Date.add(~D[2000-01-03], -2)
~D[2000-01-01]
iex> Date.add(~D[2000-01-01], 2)
~D[2000-01-03]
iex> Date.add(~N[2000-01-01 09:00:00], 2)
~D[2000-01-03]
iex> Date.add(~D[-0010-01-01], -2)
~D[-0011-12-30]

compare(date1, date2)

(с 1.4.0)

compare(Calendar.date(), Calendar.date()) :: :lt | :eq | :gt

Сравнивает две структуры дат.

Возвращает :gt если первая дата позже второй и :lt в обратном случае. Если две даты равны, возвращается :eq.

Примеры

iex> Date.compare(~D[2016-04-16], ~D[2016-04-28])
:lt

Эта функция также может использоваться для сравнения дат в более сложных типах календарей, учитывая только поля даты:

iex> Date.compare(~D[2016-04-16], ~N[2016-04-28 01:23:45])
:lt
iex> Date.compare(~D[2016-04-16], ~N[2016-04-16 01:23:45])
:eq
iex> Date.compare(~N[2016-04-16 12:34:56], ~N[2016-04-16 01:23:45])
:eq

convert(date, calendar)

(с 1.5.0)

convert(Calendar.date(), Calendar.calendar()) ::
  {:ok, t()} | {:error, :incompatible_calendars}

Преобразует заданную date из её календаря в заданный calendar.

Возвращает {:ok, date} если календари совместимы или {:error, :incompatible_calendars} если они несовместимы.

См. также Calendar.compatible_calendars?/2.

Примеры

Представьте, что кто-то реализовал Calendar.Holocene, календарь, основанный на григорианском календаре, который добавляет ровно 10 000 лет к текущему григорианскому году:

iex> Date.convert(~D[2000-01-01], Calendar.Holocene)
{:ok, %Date{calendar: Calendar.Holocene, year: 12000, month: 1, day: 1}}

convert!(date, calendar)

(с 1.5.0)

convert!(Calendar.date(), Calendar.calendar()) :: t()

Аналогично Date.convert/2, но вызывает исключение ArgumentError, если преобразование между двумя календарями невозможно.

Примеры

iex> Date.convert!(~D[2000-01-01], Calendar.Holocene)
%Date{calendar: Calendar.Holocene, year: 12000, month: 1, day: 1}

day_of_era(date)

(с 1.8.0)

day_of_era(Calendar.date()) :: {Calendar.day(), non_neg_integer()}

Вычисляет день эры и эру для заданного календаря date.

Возвращает кортеж {day, era} представляющий день в рамках эры и номер эры.

Примеры

iex> Date.day_of_era(~D[0001-01-01]) {1, 1} iex> Date.day_of_era(~D[0000-12-31]) {1, 0}

day_of_week(date)

(с 1.4.0)

day_of_week(Calendar.date()) :: Calendar.day()

Вычисляет день недели для заданной date.

Возвращает день недели как целое число. Для календаря ISO 8601 (по умолчанию) это целое число от 1 до 7, где 1 - понедельник, а 7 - воскресенье.

Примеры

iex> Date.day_of_week(~D[2016-10-31])
1
iex> Date.day_of_week(~D[2016-11-01])
2
iex> Date.day_of_week(~N[2016-11-01 01:23:45])
2
iex> Date.day_of_week(~D[-0015-10-30])
3

day_of_year(date)

(с 1.8.0)

day_of_year(Calendar.date()) :: Calendar.day()

Вычисляет день года для заданной date.

Возвращает день года как целое число. Для календаря ISO 8601 (по умолчанию) это целое число от 1 до 366.

Примеры

iex> Date.day_of_year(~D[2016-01-01])
1
iex> Date.day_of_year(~D[2016-11-01])
306
iex> Date.day_of_year(~D[-0015-10-30])
303
iex> Date.day_of_year(~D[2004-12-31])
366

days_in_month(date)

(с 1.4.0)

days_in_month(Calendar.date()) :: Calendar.day()

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

Примеры

iex> Date.days_in_month(~D[1900-01-13])
31
iex> Date.days_in_month(~D[1900-02-09])
28
iex> Date.days_in_month(~N[2000-02-20 01:23:45])
29

diff(date1, date2)

(с 1.5.0)

diff(Calendar.date(), Calendar.date()) :: integer()

Вычисляет разницу между двумя датами в полных днях.

Возвращает количество григорианских дней между датами. Сравнивать таким образом можно только структуры Date, которые следуют одному и тому же или совместимому календарю. Если два календаря несовместимы, будет выброшено исключение.

Примеры

iex> Date.diff(~D[2000-01-03], ~D[2000-01-01])
2
iex> Date.diff(~D[2000-01-01], ~D[2000-01-03])
-2
iex> Date.diff(~D[0000-01-02], ~D[-0001-12-30])
3
iex> Date.diff(~D[2000-01-01], ~N[2000-01-03 09:00:00])
-2

from_erl(tuple, calendar \\ Calendar.ISO)

from_erl(:calendar.date(), Calendar.calendar()) ::
  {:ok, t()} | {:error, atom()}

Преобразует кортеж даты Erlang в структуру Date.

Поддерживает преобразование только дат, которые находятся в календаре ISO или других календарях, в которых дни также начинаются в полночь. Попытка преобразования дат из других календарей вернет кортеж ошибки.

Примеры

iex> Date.from_erl({2000, 1, 1})
{:ok, ~D[2000-01-01]}
iex> Date.from_erl({2000, 13, 1})
{:error, :invalid_date}

from_erl!(tuple, calendar \\ Calendar.ISO)

from_erl!(:calendar.date(), Calendar.calendar()) :: t()

Преобразует кортеж даты Erlang, но выбросит исключение для неверных дат.

Примеры

iex> Date.from_erl!({2000, 1, 1})
~D[2000-01-01]
iex> Date.from_erl!({2000, 13, 1})
** (ArgumentError) cannot convert {2000, 13, 1} to date, reason: :invalid_date

from_iso8601(string, calendar \\ Calendar.ISO)

from_iso8601(String.t(), Calendar.calendar()) ::
  {:ok, t()} | {:error, atom()}

Парсит расширенный формат «Даты», описанный в ISO 8601:2004.

Год, прочитанный этой функцией, ограничен четырьмя цифрами.

Примеры

iex> Date.from_iso8601("2015-01-23")
{:ok, ~D[2015-01-23]}

iex> Date.from_iso8601("2015:01:23")
{:error, :invalid_format}

iex> Date.from_iso8601("2015-01-32")
{:error, :invalid_date}

from_iso8601!(string, calendar \\ Calendar.ISO)

from_iso8601!(String.t(), Calendar.calendar()) :: t()

Парсит расширенный формат «Даты», описанный в ISO 8601:2004.

Вызывает исключение, если формат недействителен.

Примеры

iex> Date.from_iso8601!("2015-01-23")
~D[2015-01-23]
iex> Date.from_iso8601!("2015:01:23")
** (ArgumentError) cannot parse "2015:01:23" as date, reason: :invalid_format

leap_year?(date)

(с версии 1.4.0)

leap_year?(Calendar.date()) :: boolean()

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

Примеры

iex> Date.leap_year?(~D[2000-01-01])
true
iex> Date.leap_year?(~D[2001-01-01])
false
iex> Date.leap_year?(~D[2004-01-01])
true
iex> Date.leap_year?(~D[1900-01-01])
false
iex> Date.leap_year?(~N[2004-01-01 01:23:45])
true

months_in_year(date)

(с версии 1.7.0)

months_in_year(Calendar.date()) :: Calendar.month()

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

Пример

iex> Date.months_in_year(~D[1900-01-13])
12

new(year, month, day, calendar \\ Calendar.ISO)

new(Calendar.year(), Calendar.month(), Calendar.day(), Calendar.calendar()) ::
  {:ok, t()} | {:error, atom()}

Создает новую дату ISO.

Ожидает, что все значения будут целыми числами. Возвращает {:ok, date}, если каждое значение входит в соответствующий диапазон, возвращает {:error, reason} в противном случае.

Примеры

iex> Date.new(2000, 1, 1)
{:ok, ~D[2000-01-01]}
iex> Date.new(2000, 13, 1)
{:error, :invalid_date}
iex> Date.new(2000, 2, 29)
{:ok, ~D[2000-02-29]}

iex> Date.new(2000, 2, 30)
{:error, :invalid_date}
iex> Date.new(2001, 2, 29)
{:error, :invalid_date}

quarter_of_year(date)

(с версии 1.8.0)

quarter_of_year(Calendar.date()) :: non_neg_integer()

Вычисляет квартал года заданной date.

Возвращает номер дня года как целое число. Для календаря ISO 8601 (по умолчанию) это целое число от 1 до 4.

Примеры

iex> Date.quarter_of_year(~D[2016-10-31])
4
iex> Date.quarter_of_year(~D[2016-01-01])
1
iex> Date.quarter_of_year(~N[2016-04-01 01:23:45])
2
iex> Date.quarter_of_year(~D[-0015-09-30])
3

range(first, last)

(с версии 1.5.0)

range(Date.t(), Date.t()) :: Date.Range.t()

Возвращает диапазон дат.

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

Диапазоны дат могут быть возрастающими (first <= last) или убывающими (first > last). Они всегда включают граничные значения.

Примеры

iex> Date.range(~D[1999-01-01], ~D[2000-01-01])
#DateRange<~D[1999-01-01], ~D[2000-01-01]>

Диапазон дат реализует протокол Enumerable, что означает, что функции из модуля Enum могут использоваться для работы с диапазонами:

iex> range = Date.range(~D[2001-01-01], ~D[2002-01-01])
iex> Enum.count(range)
366
iex> Enum.member?(range, ~D[2001-02-01])
true
iex> Enum.reduce(range, 0, fn _date, acc -> acc - 1 end)
-366

to_erl(date)

to_erl(Calendar.date()) :: :calendar.date()

Преобразует заданную date в кортеж даты Erlang.

Примеры

iex> Date.to_erl(~D[2000-01-01])
{2000, 1, 1}

iex> Date.to_erl(~N[2000-01-01 00:00:00])
{2000, 1, 1}

to_iso8601(date, format \\ :extended)

to_iso8601(Calendar.date(), :extended | :basic) :: String.t()

Преобразует заданную date в формат ISO 8601:2004.

По умолчанию, Date.to_iso8601/2 возвращает даты в формате «расширенном» для удобства чтения человеком. Также поддерживается формат «базовый» при помощи опции :basic.

Примеры

iex> Date.to_iso8601(~D[2000-02-28])
"2000-02-28"

iex> Date.to_iso8601(~D[2000-02-28], :basic)
"20000228"

iex> Date.to_iso8601(~N[2000-02-28 00:00:00])
"2000-02-28"

to_string(date)

to_string(Calendar.date()) :: String.t()

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

Примеры

iex> Date.to_string(~D[2000-02-28])
"2000-02-28"
iex> Date.to_string(~N[2000-02-28 01:23:45])
"2000-02-28"
iex> Date.to_string(~D[-0100-12-15])
"-0100-12-15"

utc_today(calendar \\ Calendar.ISO)

(с версии 1.4.0)

utc_today(Calendar.calendar()) :: t()

Возвращает текущую дату в UTC.

Примеры

iex> date = Date.utc_today()
iex> date.year >= 2016
true

year_of_era(date)

(с версии 1.8.0)

year_of_era(Calendar.date()) :: {Calendar.year(), non_neg_integer()}

Вычисляет год эры и номер эры для данного календарного года.

Возвращает кортеж {year, era} представляющий год в пределах эры и номер эры.

Примеры

iex> Date.year_of_era(~D[0001-01-01])
{1, 1}
iex> Date.year_of_era(~D[0000-12-31])
{1, 0}
iex> Date.year_of_era(~D[-0001-01-01])
{2, 0}