Дата

Структура Date и функции.

Структура Date содержит поля год, месяц, день и календарь. Новые даты можно создать с помощью функции new/3 или используя сигил ~D:

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 в своих типах (вместо t).

Разработчики должны избегать непосредственного создания структуры Date и вместо этого полагаться на функции, предоставляемые этим модулем, а также на функции сторонних библиотек календарей.

Краткое описание

Типы

t()

Функции

compare(date1, date2): Сравнивает две структуры Date
day_of_week(map): Вычисляет день недели заданной структуры Date
days_in_month(map): Возвращает количество дней в данном месяце даты
from_erl(arg): Преобразует кортеж даты Erlang в структуру Date
from_erl!(tuple): Преобразует кортеж даты Erlang, но вызывает исключение для недопустимых дат
from_iso8601(arg): Разбирает расширенный формат «Дата и время суток», описанный в ISO 8601:2004
from_iso8601!(string): Разбирает расширенный формат «Дата и время суток», описанный в ISO 8601:2004
leap_year?(map): Возвращает true, если год в date является високосным
new(year, month, day): Создает новую дату ISO
to_erl(map): Преобразует структуру Date в кортеж даты Erlang
to_iso8601(map): Преобразует заданную дату во ISO 8601:2004
to_string(map): Преобразует заданную дату в строку в соответствии с ее календарем
utc_today(): Возвращает текущую дату в UTC

Типы

t()

t() :: %Date{calendar: Calendar.calendar(), day: Calendar.day(), month: Calendar.month(), year: Calendar.year()}

Функции

compare(date1, date2)

compare(Calendar.date(), Calendar.date()) :: :lt | :eq | :gt

Сравнивает две структуры Date.

Возвращает :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

day_of_week(map)

day_of_week(Calendar.date()) :: non_neg_integer()

Вычисляет день недели заданной структуры 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

days_in_month(map)

days_in_month(Calendar.date()) :: Calendar.day()

Возвращает количество дней в данном месяце даты.

Примеры

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

from_erl(arg)

from_erl(:calendar.date()) :: {: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)

from_erl!(:calendar.date()) :: t() | no_return()

Преобразует кортеж даты 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(arg)

from_iso8601(String.t()) :: {: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)

from_iso8601!(String.t()) :: t() | no_return()

Разбирает расширенный формат «Дата и время суток», описанный в 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?(map)

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

new(year, month, day)

new(Calendar.year(), Calendar.month(), Calendar.day()) ::
  {: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}

to_erl(map)

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 01:23:45])
{2000, 1, 1}

to_iso8601(map)

to_iso8601(Calendar.date()) :: String.t()

Преобразует заданную дату во ISO 8601:2004.

Примеры

iex> Date.to_iso8601(~D[2000-02-28])
"2000-02-28"
iex> Date.to_iso8601(~N[2000-02-28 01:23:45])
"2000-02-28"

to_string(map)

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"

utc_today()

utc_today() :: t()

Возвращает текущую дату в UTC.

Примеры

iex> date = Date.utc_today()
iex> date.year >= 2016
true