@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()) ::
  {: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 неделя заканчивается в воскресенье. В качестве :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], :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) или убывающими (first > last). Они всегда являются включительно.

Примеры

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