NaiveDateTime

Структура NaiveDateTime (без часового пояса) и функции.

Структура NaiveDateTime содержит поля год, месяц, день, час, минута, секунда, микросекунда и календарь. Новые даты и времена без часового пояса можно создать с помощью функций new/2 и new/8 или с использованием сигила ~N:

iex> ~N[2000-01-01 23:00:07]
~N[2000-01-01 23:00:07]

К полям даты и времени в структуре можно получить доступ напрямую:

iex> naive = ~N[2000-01-01 23:00:07]
iex> naive.year
2000
iex> naive.second
7

Мы называем их «наивными», потому что эта форма представления даты и времени не имеет часового пояса. Это означает, что время может фактически не существовать в определенных регионах мира, даже если оно является допустимым.

Например, когда в регионе применяются изменения летнего времени, часы обычно переводятся вперёд или назад на один час. Это означает, что некоторые даты и времена никогда не происходят или могут происходить более одного раза. Поскольку NaiveDateTime не проверяется по часовому поясу, такие ошибки останутся незамеченными.

Функции этого модуля работают со структурой NaiveDateTime, а также с любой структурой, содержащей те же поля, что и структура NaiveDateTime, например, DateTime. Такие функции ожидают Calendar.naive_datetime/0 в своих описаниях типов (вместо t/0).

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

Сравнение наивных дат и времён

Сравнения в Elixir с использованием ==/2, >/2, </2 и аналогичных функций являются структурными и основаны на полях структуры NaiveDateTime. Для правильного сравнения наивных дат и времён используйте функцию compare/2.

Использование эпох

Функции add/3 и diff/3 могут использоваться для вычислений с датами и временами или для получения количества секунд между моментами. Например, если нужно вычислить количество секунд с эпохи Unix (1970-01-01 00:00:00):

iex> NaiveDateTime.diff(~N[2010-04-17 14:00:00], ~N[1970-01-01 00:00:00])
1271512800

iex> NaiveDateTime.add(~N[1970-01-01 00:00:00], 1_271_512_800)
~N[2010-04-17 14:00:00]

Эти функции оптимизированы для работы со стандартными эпохами, такими как эпоха Unix выше или эпоха григорианского календаря (0000-01-01 00:00:00).

Резюме

Типы

t()

Функции

add(naive_datetime, integer, unit \\ :second)

Добавляет заданное количество времени к NaiveDateTime

compare(naive_datetime1, naive_datetime2)

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

convert!(naive_datetime, calendar)

Преобразует заданную naive_datetime из одного календаря в другой

convert(naive_datetime, calendar)

Преобразует заданную naive_datetime из одного календаря в другой

diff(naive_datetime1, naive_datetime2, unit \\ :second)

Вычитает naive_datetime2 из naive_datetime1

from_erl!(tuple, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)

Преобразует кортеж Erlang даты и времени в структуру NaiveDateTime

from_erl(tuple, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)

Преобразует кортеж Erlang даты и времени в структуру NaiveDateTime

from_iso8601!(string, calendar \\ Calendar.ISO)

Парсит расширенный формат «Дата и время суток», описанный в ISO 8601:2004

from_iso8601(string, calendar \\ Calendar.ISO)

Парсит расширенный формат «Дата и время суток», описанный в ISO 8601:2004

new(date, time)

Создаёт наивную дату и время из структур даты и времени

new(year, month, day, hour, minute, second, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)

Создаёт новую наивную дату и время по ISO

to_date(naive_date_time)

Преобразует NaiveDateTime в Date

to_erl(naive_datetime)

Преобразует структуру NaiveDateTime в кортеж Erlang даты и времени

to_iso8601(naive_datetime, format \\ :extended)

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

to_string(naive_datetime)

Преобразует заданную наивную дату и время в строку в соответствии с её календарём

to_time(naive_datetime)

Преобразует NaiveDateTime в Time

truncate(naive_datetime, precision)

Возвращает заданную наивную дату и время с полем микросекунд, усечённым до заданной точности (:microsecond, :millisecond или :second)

utc_now(calendar \\ Calendar.ISO)

Возвращает текущую наивную дату и время в UTC

Типы

t()

t() :: %NaiveDateTime{
  calendar: Calendar.calendar(),
  day: Calendar.day(),
  hour: Calendar.hour(),
  microsecond: Calendar.microsecond(),
  minute: Calendar.minute(),
  month: Calendar.month(),
  second: Calendar.second(),
  year: Calendar.year()
}

Функции

add(naive_datetime, integer, unit \\ :second) (since 1.4.0)

add(t(), integer(), System.time_unit()) :: t()

Добавляет заданное количество времени к NaiveDateTime.

Принимает integer в любом unit доступном из System.time_unit/0. Отрицательные значения сместят время назад.

Это действие возможно только в том случае, если оба календаря могут быть преобразованы в Calendar.ISO.

Примеры

# adds seconds by default
iex> NaiveDateTime.add(~N[2014-10-02 00:29:10], 2)
~N[2014-10-02 00:29:12]

# accepts negative offsets
iex> NaiveDateTime.add(~N[2014-10-02 00:29:10], -2)
~N[2014-10-02 00:29:08]

# can work with other units
iex> NaiveDateTime.add(~N[2014-10-02 00:29:10], 2_000, :millisecond)
~N[2014-10-02 00:29:12]

# keeps the same precision
iex> NaiveDateTime.add(~N[2014-10-02 00:29:10.021], 21, :second)
~N[2014-10-02 00:29:31.021]

# changes below the precision will not be visible
iex> hidden = NaiveDateTime.add(~N[2014-10-02 00:29:10], 21, :millisecond)
iex> hidden.microsecond # ~N[2014-10-02 00:29:10]
{21000, 0}

# from Gregorian seconds
iex> NaiveDateTime.add(~N[0000-01-01 00:00:00], 63_579_428_950)
~N[2014-10-02 00:29:10]

compare(naive_datetime1, naive_datetime2) (since 1.4.0)

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

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

Возвращает :gt если первая дата позже второй и :lt в обратном случае. Если две NaiveDateTime равны, возвращается :eq.

Примеры

iex> NaiveDateTime.compare(~N[2016-04-16 13:30:15], ~N[2016-04-28 16:19:25])
:lt
iex> NaiveDateTime.compare(~N[2016-04-16 13:30:15.1], ~N[2016-04-16 13:30:15.01])
:gt

Эту функцию также можно использовать для сравнения DateTime без информации о часовом поясе:

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> NaiveDateTime.compare(dt, ~N[2000-02-29 23:00:07])
:eq
iex> NaiveDateTime.compare(dt, ~N[2000-01-29 23:00:07])
:gt
iex> NaiveDateTime.compare(dt, ~N[2000-03-29 23:00:07])
:lt

convert!(naive_datetime, calendar) (since 1.5.0)

convert!(Calendar.naive_datetime(), Calendar.calendar()) :: t()

Преобразует заданную naive_datetime из одного календаря в другой.

Если не удаётся однозначно преобразовать между календарями (см. Calendar.compatible_calendars?/2), генерируется ArgumentError.

Примеры

Представьте, что кто-то реализует Calendar.Holocene, календарь, основанный на григорианском календаре, который добавляет ровно 10 000 лет к текущему году григорианского календаря:

iex> NaiveDateTime.convert!(~N[2000-01-01 13:30:15], Calendar.Holocene)
%NaiveDateTime{calendar: Calendar.Holocene, year: 12000, month: 1, day: 1,
               hour: 13, minute: 30, second: 15, microsecond: {0, 0}}

convert(naive_datetime, calendar) (since 1.5.0)

convert(Calendar.naive_datetime(), Calendar.calendar()) ::
  {:ok, t()} | {:error, :incompatible_calendars}

Преобразует заданную naive_datetime из одного календаря в другой.

Если не удаётся однозначно преобразовать между календарями (см. Calendar.compatible_calendars?/2), возвращается кортеж {:error, :incompatible_calendars}.

Примеры

Представьте, что кто-то реализует Calendar.Holocene, календарь, основанный на григорианском календаре, который добавляет ровно 10 000 лет к текущему году григорианского календаря:

iex> NaiveDateTime.convert(~N[2000-01-01 13:30:15], Calendar.Holocene)
{:ok, %NaiveDateTime{calendar: Calendar.Holocene, year: 12000, month: 1, day: 1,
                     hour: 13, minute: 30, second: 15, microsecond: {0, 0}}}

diff(naive_datetime1, naive_datetime2, unit \\ :second) (since 1.4.0)

diff(t(), t(), System.time_unit()) :: integer()

Вычитает naive_datetime2 из naive_datetime1.

Ответ может быть возвращён в любом unit доступном из System.time_unit/0.

Функция возвращает разницу в секундах, где секунды измеряются согласно Calendar.ISO.

Примеры

iex> NaiveDateTime.diff(~N[2014-10-02 00:29:12], ~N[2014-10-02 00:29:10])
2
iex> NaiveDateTime.diff(~N[2014-10-02 00:29:12], ~N[2014-10-02 00:29:10], :microsecond)
2_000_000
iex> NaiveDateTime.diff(~N[2014-10-02 00:29:10.042], ~N[2014-10-02 00:29:10.021], :millisecond)
21
iex> NaiveDateTime.diff(~N[2014-10-02 00:29:10], ~N[2014-10-02 00:29:12])
-2
iex> NaiveDateTime.diff(~N[-0001-10-02 00:29:10], ~N[-0001-10-02 00:29:12])
-2

# to Gregorian seconds
iex> NaiveDateTime.diff(~N[2014-10-02 00:29:10], ~N[0000-01-01 00:00:00])
63579428950

from_erl!(tuple, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)

from_erl!(:calendar.datetime(), Calendar.microsecond(), Calendar.calendar()) ::
  t() | no_return()

Преобразует кортеж Erlang даты и времени в структуру NaiveDateTime структуры.

Возбуждает исключение, если дата и время недопустимы. Попытка преобразования недопустимой даты ISO-календаря приведёт к ошибке.

Примеры

iex> NaiveDateTime.from_erl!({{2000, 1, 1}, {13, 30, 15}})
~N[2000-01-01 13:30:15]
iex> NaiveDateTime.from_erl!({{2000, 1, 1}, {13, 30, 15}}, {5000, 3})
~N[2000-01-01 13:30:15.005]
iex> NaiveDateTime.from_erl!({{2000, 13, 1}, {13, 30, 15}})
** (ArgumentError) cannot convert {{2000, 13, 1}, {13, 30, 15}} to naive datetime, reason: :invalid_date

from_erl(tuple, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)

from_erl(:calendar.datetime(), Calendar.microsecond(), Calendar.calendar()) ::
  {:ok, t()} | {:error, atom()}

Преобразует кортеж Erlang datetime в структуру NaiveDateTime.

Попытка конвертировать недействительную дату ISO календаря приведет к ошибочному кортежу.

Примеры

iex> NaiveDateTime.from_erl({{2000, 1, 1}, {13, 30, 15}})
{:ok, ~N[2000-01-01 13:30:15]}
iex> NaiveDateTime.from_erl({{2000, 1, 1}, {13, 30, 15}}, {5000, 3})
{:ok, ~N[2000-01-01 13:30:15.005]}
iex> NaiveDateTime.from_erl({{2000, 13, 1}, {13, 30, 15}})
{:error, :invalid_date}
iex> NaiveDateTime.from_erl({{2000, 13, 1}, {13, 30, 15}})
{:error, :invalid_date}

from_iso8601!(string, calendar \\ Calendar.ISO)

from_iso8601!(String.t(), Calendar.calendar()) :: t() | no_return()

Парсит расширенный формат «Дата и время» согласно ISO 8601:2004.

Возбуждает исключение, если формат недействителен.

Примеры

iex> NaiveDateTime.from_iso8601!("2015-01-23T23:50:07.123Z")
~N[2015-01-23 23:50:07.123]
iex> NaiveDateTime.from_iso8601!("2015-01-23T23:50:07,123Z")
~N[2015-01-23 23:50:07.123]
iex> NaiveDateTime.from_iso8601!("2015-01-23P23:50:07")
** (ArgumentError) cannot parse "2015-01-23P23:50:07" as naive datetime, reason: :invalid_format

from_iso8601(string, calendar \\ Calendar.ISO)

from_iso8601(String.t(), Calendar.calendar()) ::
  {:ok, t()} | {:error, atom()}

Парсит расширенный формат «Дата и время» согласно ISO 8601:2004.

Смещение часового пояса может быть включено в строку, но будет просто проигнорировано, так как такая информация не включается в наивные даты и время.

Как указано в стандарте, разделитель «T» можно опустить, если это не вызывает неоднозначности в функции.

Представления времени с пониженной точностью не поддерживаются.

Обратите внимание, что, хотя ISO 8601 допускает указание 24:00:00 как нуля часов следующего дня, такая запись не поддерживается Elixir.

Примеры

iex> NaiveDateTime.from_iso8601("2015-01-23 23:50:07")
{:ok, ~N[2015-01-23 23:50:07]}
iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07")
{:ok, ~N[2015-01-23 23:50:07]}
iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07Z")
{:ok, ~N[2015-01-23 23:50:07]}

iex> NaiveDateTime.from_iso8601("2015-01-23 23:50:07.0")
{:ok, ~N[2015-01-23 23:50:07.0]}
iex> NaiveDateTime.from_iso8601("2015-01-23 23:50:07,0123456")
{:ok, ~N[2015-01-23 23:50:07.012345]}
iex> NaiveDateTime.from_iso8601("2015-01-23 23:50:07.0123456")
{:ok, ~N[2015-01-23 23:50:07.012345]}
iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07.123Z")
{:ok, ~N[2015-01-23 23:50:07.123]}

iex> NaiveDateTime.from_iso8601("2015-01-23P23:50:07")
{:error, :invalid_format}
iex> NaiveDateTime.from_iso8601("2015:01:23 23-50-07")
{:error, :invalid_format}
iex> NaiveDateTime.from_iso8601("2015-01-23 23:50:07A")
{:error, :invalid_format}
iex> NaiveDateTime.from_iso8601("2015-01-23 23:50:61")
{:error, :invalid_time}
iex> NaiveDateTime.from_iso8601("2015-01-32 23:50:07")
{:error, :invalid_date}

iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07.123+02:30")
{:ok, ~N[2015-01-23 23:50:07.123]}
iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07.123+00:00")
{:ok, ~N[2015-01-23 23:50:07.123]}
iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07.123-02:30")
{:ok, ~N[2015-01-23 23:50:07.123]}
iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07.123-00:00")
{:error, :invalid_format}
iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07.123-00:60")
{:error, :invalid_format}
iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07.123-24:00")
{:error, :invalid_format}

new(date, time)

new(Date.t(), Time.t()) :: {:ok, t()}

Создает наивную дату и время из структур даты и времени.

Примеры

iex> NaiveDateTime.new(~D[2010-01-13], ~T[23:00:07.005])
{:ok, ~N[2010-01-13 23:00:07.005]}

new(year, month, day, hour, minute, second, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)

new(
  Calendar.year(),
  Calendar.month(),
  Calendar.day(),
  Calendar.hour(),
  Calendar.minute(),
  Calendar.second(),
  Calendar.microsecond(),
  Calendar.calendar()
) :: {:ok, t()} | {:error, atom()}

Создает новую наивную дату и время ISO.

Ожидает все значения в виде целых чисел. Возвращает {:ok, naive_datetime} если каждое значение входит в соответствующий диапазон, возвращает {:error, reason} в противном случае.

Примеры

iex> NaiveDateTime.new(2000, 1, 1, 0, 0, 0)
{:ok, ~N[2000-01-01 00:00:00]}
iex> NaiveDateTime.new(2000, 13, 1, 0, 0, 0)
{:error, :invalid_date}
iex> NaiveDateTime.new(2000, 2, 29, 0, 0, 0)
{:ok, ~N[2000-02-29 00:00:00]}
iex> NaiveDateTime.new(2000, 2, 30, 0, 0, 0)
{:error, :invalid_date}
iex> NaiveDateTime.new(2001, 2, 29, 0, 0, 0)
{:error, :invalid_date}

iex> NaiveDateTime.new(2000, 1, 1, 23, 59, 59, {0, 1})
{:ok, ~N[2000-01-01 23:59:59.0]}
iex> NaiveDateTime.new(2000, 1, 1, 23, 59, 59, 999_999)
{:ok, ~N[2000-01-01 23:59:59.999999]}
iex> NaiveDateTime.new(2000, 1, 1, 23, 59, 60, 999_999)
{:ok, ~N[2000-01-01 23:59:60.999999]}
iex> NaiveDateTime.new(2000, 1, 1, 24, 59, 59, 999_999)
{:error, :invalid_time}
iex> NaiveDateTime.new(2000, 1, 1, 23, 60, 59, 999_999)
{:error, :invalid_time}
iex> NaiveDateTime.new(2000, 1, 1, 23, 59, 61, 999_999)
{:error, :invalid_time}
iex> NaiveDateTime.new(2000, 1, 1, 23, 59, 59, 1_000_000)
{:error, :invalid_time}

iex> NaiveDateTime.new(2000, 1, 1, 23, 59, 59, {0, 1}, Calendar.ISO)
{:ok, ~N[2000-01-01 23:59:59.0]}

to_date(naive_date_time)

to_date(t()) :: Date.t()

Преобразует NaiveDateTime в Date.

Поскольку Date не содержит информации о времени, данные будут потеряны при преобразовании.

Примеры

iex> NaiveDateTime.to_date(~N[2002-01-13 23:00:07])
~D[2002-01-13]

to_erl(naive_datetime)

to_erl(Calendar.naive_datetime()) :: :calendar.datetime()

Преобразует структуру NaiveDateTime в кортеж Erlang datetime.

Поддерживает только преобразование наивных дат и времени в календаре ISO, попытка конвертировать наивные даты и время из других календарей приведет к исключению.

ПРЕДУПРЕЖДЕНИЕ: Может произойти потеря точности, так как кортежи времени Erlang хранят только часы/минуты/секунды.

Примеры

iex> NaiveDateTime.to_erl(~N[2000-01-01 13:30:15])
{{2000, 1, 1}, {13, 30, 15}}

Эта функция также может быть использована для преобразования DateTime в формат erl без информации о часовом поясе:

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> NaiveDateTime.to_erl(dt)
{{2000, 2, 29}, {23, 00, 07}}

to_iso8601(naive_datetime, format \\ :extended)

to_iso8601(Calendar.naive_datetime(), :basic | :extended) :: String.t()

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

По умолчанию, NaiveDateTime.to_iso8601/2 возвращает наивные даты и время, отформатированные в «расширенном» формате для лучшей читаемости. Также поддерживается «базовый» формат путем передачи параметра :basic.

Поддерживает только преобразование наивных дат и времени в календаре ISO, попытка конвертировать наивные даты и время из других календарей приведет к исключению.

Примеры

iex> NaiveDateTime.to_iso8601(~N[2000-02-28 23:00:13])
"2000-02-28T23:00:13"

iex> NaiveDateTime.to_iso8601(~N[2000-02-28 23:00:13.001])
"2000-02-28T23:00:13.001"

iex> NaiveDateTime.to_iso8601(~N[2000-02-28 23:00:13.001], :basic)
"20000228T230013.001"

Эта функция также может быть использована для преобразования DateTime в ISO 8601 без информации о часовом поясе:

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> NaiveDateTime.to_iso8601(dt)
"2000-02-29T23:00:07"

to_string(naive_datetime)

to_string(Calendar.naive_datetime()) :: String.t()

Преобразует заданную наивную дату и время в строку в соответствии с её календарем.

Примеры

iex> NaiveDateTime.to_string(~N[2000-02-28 23:00:13])
"2000-02-28 23:00:13"
iex> NaiveDateTime.to_string(~N[2000-02-28 23:00:13.001])
"2000-02-28 23:00:13.001"
iex> NaiveDateTime.to_string(~N[-0100-12-15 03:20:31])
"-0100-12-15 03:20:31"

Эта функция также может быть использована для преобразования DateTime в строку без информации о часовом поясе:

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> NaiveDateTime.to_string(dt)
"2000-02-29 23:00:07"

to_time(naive_datetime)

to_time(t()) :: Time.t()

Преобразует NaiveDateTime в Time.

Поскольку Time не содержит информации о дате, данные будут утеряны при преобразовании.

Примеры

iex> NaiveDateTime.to_time(~N[2002-01-13 23:00:07])
~T[23:00:07]

truncate(naive_datetime, precision) (since 1.6.0)

truncate(t(), :microsecond | :millisecond | :second) :: t()

Возвращает заданную наивную дату и время с усечённым полем микросекунд до указанной точности (:microsecond, :millisecond или :second).

Примеры

iex> NaiveDateTime.truncate(~N[2017-11-06 00:23:51.123456], :microsecond)
~N[2017-11-06 00:23:51.123456]

iex> NaiveDateTime.truncate(~N[2017-11-06 00:23:51.123456], :millisecond)
~N[2017-11-06 00:23:51.123]

iex> NaiveDateTime.truncate(~N[2017-11-06 00:23:51.123456], :second)
~N[2017-11-06 00:23:51]

utc_now(calendar \\ Calendar.ISO) (since 1.4.0)

utc_now(Calendar.calendar()) :: t()

Возвращает текущую наивную дату и время в UTC.

Предпочтительнее использовать DateTime.utc_now/0 по возможности, так как, в отличие от NaiveDateTime, она сохранит информацию о часовом поясе.

Примеры

iex> naive_datetime = NaiveDateTime.utc_now()
iex> naive_datetime.year >= 2016
true