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

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

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

Чтобы сдвинуть дату на Duration в соответствии с его базовым календарем, используйте Date.shift/2.

Примеры

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 after?(Calendar.date(), Calendar.date()) :: boolean()

Возвращает true, если первая дата строго позже второй.

Примеры

iex> Date.after?(~D[2022-02-02], ~D[2021-01-01])
true
iex> Date.after?(~D[2021-01-01], ~D[2021-01-01])
false
iex> Date.after?(~D[2021-01-01], ~D[2022-02-02])
false

@spec before?(Calendar.date(), Calendar.date()) :: boolean()

Возвращает true, если первая дата строго раньше второй.

Примеры

iex> Date.before?(~D[2021-01-01], ~D[2022-02-02])
true
iex> Date.before?(~D[2021-01-01], ~D[2021-01-01])
false
iex> Date.before?(~D[2022-02-02], ~D[2021-01-01])
false

@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 неделя начинается с понедельника. В качестве starting_on может быть указан день недели, а не :default.

Примеры

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()) ::
  {: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 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 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 неделя заканчивается в воскресенье. В качестве starting_on может быть указан день недели, а не :default.

Примеры

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], :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()) :: {: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_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_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()) :: {: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 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 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()) ::
  {: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 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 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) и всегда включительными. Для убывающего диапазона используйте range/3 со значением шага -1 в качестве первого аргумента.

Примеры

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

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

iex> range = Date.range(~D[2001-01-01], ~D[2002-01-01])
iex> range
Date.range(~D[2001-01-01], ~D[2002-01-01])
iex> Enum.count(range)
366
iex> ~D[2001-02-01] in range
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
Date.range(~D[2001-01-01], ~D[2002-01-01], 2)
iex> Enum.count(range)
183
iex> ~D[2001-01-03] in range
true
iex> Enum.take(range, 3)
[~D[2001-01-01], ~D[2001-01-03], ~D[2001-01-05]]

@spec shift(Calendar.date(), Duration.t() | [unit_pair]) :: t()
when unit_pair:
       {:year, integer()}
       | {:month, integer()}
       | {:week, integer()}
       | {:day, integer()}

Сдвигает заданную date на duration в соответствии с её календарём.

Допустимые единицы измерения: :year, :month, :week, :day.

При использовании календаря ISO по умолчанию временные промежутки сворачиваются и применяются в порядке сначала месяцы, затем дни:

• при сдвиге на 1 год и 2 месяца дата фактически сдвигается на 14 месяцев
• при сдвиге на 2 недели и 3 дня дата сдвигается на 17 дней

При сдвиге по месяцам дни округляются вниз до ближайшей корректной даты.

Генерирует исключение ArgumentError при вызове с единицами измерения времени.

Примеры

iex> Date.shift(~D[2016-01-03], month: 2)
~D[2016-03-03]
iex> Date.shift(~D[2016-01-30], month: -1)
~D[2015-12-30]
iex> Date.shift(~D[2016-01-31], year: 4, day: 1)
~D[2020-02-01]
iex> Date.shift(~D[2016-01-03], Duration.new!(month: 2))
~D[2016-03-03]

# leap years
iex> Date.shift(~D[2024-02-29], year: 1)
~D[2025-02-28]
iex> Date.shift(~D[2024-02-29], year: 4)
~D[2028-02-29]

# rounding down
iex> Date.shift(~D[2015-01-31], month: 1)
~D[2015-02-28]

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