@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 неделя начинается с понедельника. Может быть указан день недели, а не :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) и всегда включают крайние значения. Для убывающего диапазона используйте 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 возвращает даты в формате "extended" для лучшей читаемости. Также поддерживает формат "basic" через опцию :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}