Дата
Структура Date и функции.
Структура Date содержит поля year, month, day и calendar. Новые даты можно создать с помощью функции 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(t(), 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.
Поддерживает только преобразование дат в календаре 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.10.4/Date.html
