@spec 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]

@spec beginning_of_month(Calendar.date()) :: t()

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

Примеры

iex> Date.beginning_of_month(~D[2000-01-31])
~D[2000-01-01]
iex> Date.beginning_of_month(~D[2000-01-01])
~D[2000-01-01]
iex> Date.beginning_of_month(~N[2000-01-31 01:23:45])
~D[2000-01-01]

@spec beginning_of_week(Calendar.date(), starting_on :: :default | atom()) :: t()

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

Если день уже является первым днем недели, возвращается сам день. Для встроенного календаря ISO неделя начинается с понедельника. В качестве :default может быть задан день недели вместо starting_on.

Примеры

iex> Date.beginning_of_week(~D[2020-07-11])
~D[2020-07-06]
iex> Date.beginning_of_week(~D[2020-07-06])
~D[2020-07-06]
iex> Date.beginning_of_week(~D[2020-07-11], :sunday)
~D[2020-07-05]
iex> Date.beginning_of_week(~D[2020-07-11], :saturday)
~D[2020-07-11]
iex> Date.beginning_of_week(~N[2020-07-11 01:23:45])
~D[2020-07-06]

@spec 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

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

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

Примеры

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

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

@spec 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}}

@spec 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}

@spec day_of_week(Calendar.date(), starting_on :: :default | atom()) ::
  Calendar.day_of_week()

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

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

Можно указать необязательное значение starting_on, которое настраивает день недели, с которого начинается неделя. Значение по умолчанию :default, что соответствует :monday для встроенного календаря ISO. Любой другой день недели может быть задан.

Примеры

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

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

@spec 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

@spec 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

@spec 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

@spec end_of_month(Calendar.date()) :: t()

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

Примеры

iex> Date.end_of_month(~D[2000-01-01])
~D[2000-01-31]
iex> Date.end_of_month(~D[2000-01-31])
~D[2000-01-31]
iex> Date.end_of_month(~N[2000-01-01 01:23:45])
~D[2000-01-31]

@spec end_of_week(Calendar.date(), starting_on :: :default | atom()) :: t()

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

Если день уже является последним днем недели, возвращается сам день. Для встроенного календаря ISO неделя заканчивается в воскресенье. День недели вместо :default может быть задан как starting_on.

Примеры

iex> Date.end_of_week(~D[2020-07-11])
~D[2020-07-12]
iex> Date.end_of_week(~D[2020-07-05])
~D[2020-07-05]
iex> Date.end_of_week(~D[2020-07-06], :sunday)
~D[2020-07-11]
iex> Date.end_of_week(~D[2020-07-06], :sunday)
~D[2020-07-11]
iex> Date.end_of_week(~D[2020-07-06], :saturday)
~D[2020-07-10]
iex> Date.end_of_week(~N[2020-07-11 01:23:45])
~D[2020-07-12]

@spec 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

@spec 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}

@spec from_gregorian_days(integer(), Calendar.calendar()) :: t()

Преобразует количество григорианских дней в структуру Date.

Примеры

iex> Date.from_gregorian_days(1)
~D[0000-01-02]
iex> Date.from_gregorian_days(730_485)
~D[2000-01-01]
iex> Date.from_gregorian_days(-1)
~D[-0001-12-31]

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

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

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

Примеры

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

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

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

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

Примеры

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}

@spec 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

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

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

Пример

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

@spec new!(Calendar.year(), Calendar.month(), Calendar.day(), Calendar.calendar()) ::
  t()

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

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

Примеры

iex> Date.new!(2000, 1, 1)
~D[2000-01-01]
iex> Date.new!(2000, 13, 1)
** (ArgumentError) cannot build date, reason: :invalid_date
iex> Date.new!(2000, 2, 29)
~D[2000-02-29]

@spec 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}

@spec 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

@spec range(Calendar.date(), Calendar.date()) :: 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.take(range, 3)
[~D[2001-01-01], ~D[2001-01-02], ~D[2001-01-03]]

@spec range(Calendar.date(), Calendar.date(), step :: pos_integer() | neg_integer()) ::
  Date.Range.t()

Возвращает диапазон дат с шагом.

Примеры

iex> range = Date.range(~D[2001-01-01], ~D[2002-01-01], 2)
iex> range
#DateRange<~D[2001-01-01], ~D[2002-01-01], 2>
iex> Enum.count(range)
183
iex> Enum.member?(range, ~D[2001-01-03])
true
iex> Enum.take(range, 3)
[~D[2001-01-01], ~D[2001-01-03], ~D[2001-01-05]]

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

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

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

Примеры

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}

@spec to_gregorian_days(Calendar.date()) :: integer()

Преобразует структуру date в количество дней по григорианскому календарю.

Примеры

iex> Date.to_gregorian_days(~D[0000-01-02])
1
iex> Date.to_gregorian_days(~D[2000-01-01])
730_485
iex> Date.to_gregorian_days(~N[2000-01-01 00:00:00])
730_485

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

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

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

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

Примеры

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"

@spec 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"

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

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

Примеры

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

@spec 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}