Дата
Структура 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).
Краткое описание
Типы
Функции
- 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)
Парсит расширенный формат «Даты», описанный в ISO 8601:2004.
- from_iso8601!(string, calendar \\ Calendar.ISO)
Парсит расширенный формат «Даты», описанный в 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)
Спецификации
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)
Спецификации
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)
Спецификации
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)
Спецификации
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} day_of_era(date)
Спецификации
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)
Спецификации
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)
Спецификации
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)
Спецификации
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)
Спецификации
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)
Спецификации
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)
Спецификации
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)
Спецификации
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)
Спецификации
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 даты.
Поддерживает только преобразование дат, которые находятся в календаре 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} to_iso8601(date, format \\ :extended)
Спецификации
to_iso8601(Calendar.date(), :extended | :basic) :: String.t()
Преобразует заданную date в ISO 8601:2004.
По умолчанию, Date.to_iso8601/2 возвращает даты в формате «расширенный» для удобства чтения человеком. Также поддерживается формат «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"
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)
Спецификации
utc_today(Calendar.calendar()) :: t()
Возвращает текущую дату в формате UTC.
Примеры
iex> date = Date.utc_today() iex> date.year >= 2016 true
year_of_era(date)
Спецификации
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}
© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.9.4/Date.html
