Исходный код NaiveDateTime

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

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

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 и вместо этого полагаться на функции, предоставляемые этим модулем, а также на функции сторонних библиотек календарей.

Сравнение дат и времён без часового пояса

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

iex> Enum.min([~N[2020-01-01 23:00:07], ~N[2000-01-01 23:00:07]], NaiveDateTime)
~N[2000-01-01 23:00:07]

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

Функции 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, amount_to_add, unit \\ :second): Добавляет заданное количество времени к NaiveDateTime.
after?(naive_datetime1, naive_datetime2): Возвращает true если первая NaiveDateTime строго позже второй.
before?(naive_datetime1, naive_datetime2): Возвращает true если первая NaiveDateTime строго раньше второй.
beginning_of_day(naive_datetime): Вычисляет NaiveDateTime, который является первым моментом для заданной NaiveDateTime.
compare(naive_datetime1, naive_datetime2): Сравнивает две структуры NaiveDateTime.
convert(ndt, calendar): Преобразует заданную naive_datetime из одного календаря в другой.
convert!(naive_datetime, calendar): Преобразует заданную naive_datetime из одного календаря в другой.
diff(naive_datetime1, naive_datetime2, unit \\ :second): Вычитает naive_datetime2 из naive_datetime1.
end_of_day(naive_datetime): Вычисляет NaiveDateTime, который является последним моментом для заданной NaiveDateTime.
from_erl(tuple, microsecond \\ {0, 0}, calendar \\ Calendar.ISO): Преобразует кортеж Erlang datetime в структуру NaiveDateTime.
from_erl!(tuple, microsecond \\ {0, 0}, calendar \\ Calendar.ISO): Преобразует кортеж Erlang datetime в структуру NaiveDateTime.
from_gregorian_seconds(seconds, microsecond_precision \\ {0, 0}, calendar \\ Calendar.ISO): Преобразует количество грегорианских секунд в структуру NaiveDateTime.
from_iso8601(string, calendar \\ Calendar.ISO): Парсит расширенный формат «Дата и время» описанный в ISO 8601:2019.
from_iso8601!(string, calendar \\ Calendar.ISO): Парсит расширенный формат «Дата и время» описанный в ISO 8601:2019.
local_now(calendar \\ Calendar.ISO): Возвращает «локальное время» для машины, на которой выполняется программа Elixir.
new(date, time): Создаёт naive datetime из структур date и time.
new(year, month, day, hour, minute, second, microsecond \\ {0, 0}, calendar \\ Calendar.ISO): Создаёт новую ISO naive datetime.
new!(date, time): Создаёт naive datetime из структур date и time.
new!(year, month, day, hour, minute, second, microsecond \\ {0, 0}, calendar \\ Calendar.ISO): Создаёт новую ISO naive datetime.
shift(naive_datetime, duration): Смещает заданный naive_datetime на duration в соответствии с его календарём.
to_date(map): Преобразует NaiveDateTime в Date.
to_erl(naive_datetime): Преобразует структуру NaiveDateTime в кортеж Erlang datetime.
to_gregorian_seconds(map): Преобразует структуру NaiveDateTime в количество грегорианских секунд и микросекунд.
to_iso8601(naive_datetime, format \\ :extended): Преобразует заданную naive datetime в ISO 8601:2019.
to_string(naive_datetime): Преобразует заданную naive datetime в строку в соответствии с её календарём.
to_time(map): Преобразует NaiveDateTime в Time.
truncate(naive_datetime, precision): Возвращает заданную naive datetime с полем microsecond, усечённым до заданной точности (:microsecond, :millisecond или :second).
utc_now(calendar_or_time_unit \\ Calendar.ISO): Возвращает текущую naive datetime в UTC.
utc_now(time_unit, calendar): Возвращает текущую naive datetime в UTC, поддерживая определённый календарь и точность.

Типы

t()Источник

@type 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()
}

END_OF_DOCUMENT_MARKER

Функции

add(naive_datetime, amount_to_add, unit \\ :second)Source

@spec add(
  Calendar.naive_datetime(),
  integer(),
  :day | :hour | :minute | System.time_unit()
) :: t()

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

Принимает значение amount_to_add в любом unit. unit может быть :day, :hour, :minute, :second или любой точностью до долей секунды из System.time_unit/0. По умолчанию используется :second. Отрицательные значения будут перемещать во времени назад.

Эта функция всегда считает единицы измерения в соответствии с 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]

Также можно использовать точность до долей секунды:

iex> NaiveDateTime.add(~N[2014-10-02 00:29:10], 2_000, :millisecond)
~N[2014-10-02 00:29:12.000]

А также дни/часы/минуты:

iex> NaiveDateTime.add(~N[2015-02-28 00:29:10], 2, :day)
~N[2015-03-02 00:29:10]
iex> NaiveDateTime.add(~N[2015-02-28 00:29:10], 36, :hour)
~N[2015-03-01 12:29:10]
iex> NaiveDateTime.add(~N[2015-02-28 00:29:10], 60, :minute)
~N[2015-02-28 01:29:10]

Это действие объединяет точность даты-времени без часового пояса с заданными единицами измерения:

iex> result = NaiveDateTime.add(~N[2014-10-02 00:29:10], 21, :millisecond)
~N[2014-10-02 00:29:10.021]
iex> result.microsecond
{21000, 3}

Операции с gregorian секундами или с Unix эпохой оптимизированы:

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

Передача DateTime автоматически преобразует её в NaiveDateTime, отбрасывая информацию о часовом поясе:

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.add(dt, 21, :second)
~N[2000-02-29 23:00:28]

Для сдвига даты-времени без часового пояса на Duration и в соответствии с её базовым календарем, используйте NaiveDateTime.shift/2.

after?(naive_datetime1, naive_datetime2)Source

@spec after?(Calendar.naive_datetime(), Calendar.naive_datetime()) :: boolean()

Возвращает true если первая NaiveDateTime строго позже второй.

Примеры

iex> NaiveDateTime.after?(~N[2022-02-02 11:00:00], ~N[2021-01-01 11:00:00])
true
iex> NaiveDateTime.after?(~N[2021-01-01 11:00:00], ~N[2021-01-01 11:00:00])
false
iex> NaiveDateTime.after?(~N[2021-01-01 11:00:00], ~N[2022-02-02 11:00:00])
false

before?(naive_datetime1, naive_datetime2)Source

@spec before?(Calendar.naive_datetime(), Calendar.naive_datetime()) :: boolean()

Возвращает true если первая NaiveDateTime строго раньше второй.

Примеры

iex> NaiveDateTime.before?(~N[2021-01-01 11:00:00], ~N[2022-02-02 11:00:00])
true
iex> NaiveDateTime.before?(~N[2021-01-01 11:00:00], ~N[2021-01-01 11:00:00])
false
iex> NaiveDateTime.before?(~N[2022-02-02 11:00:00], ~N[2021-01-01 11:00:00])
false

beginning_of_day(naive_datetime)Source

@spec beginning_of_day(Calendar.naive_datetime()) :: t()

Вычисляет NaiveDateTime, которая является первым моментом для данной NaiveDateTime.

Чтобы вычислить начало дня для DateTime, вызовите эту функцию, а затем преобразуйте обратно в DateTime:

datetime
|> NaiveDateTime.beginning_of_day()
|> DateTime.from_naive(datetime.time_zone)

Обратите внимание, что начало дня может не существовать или быть неоднозначным в заданном часовом поясе, поэтому вам необходимо соответствующим образом обработать эти случаи.

Примеры

iex> NaiveDateTime.beginning_of_day(~N[2000-01-01 23:00:07.123456])
~N[2000-01-01 00:00:00.000000]

compare(naive_datetime1, naive_datetime2)Source

@spec 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(ndt, calendar)Source

@spec 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}}}

convert!(naive_datetime, calendar)Source

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

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

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

Примеры

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}}

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

@spec diff(
  Calendar.naive_datetime(),
  Calendar.naive_datetime(),
  :day | :hour | :minute | System.time_unit()
) :: integer()

Вычисляет разницу между naive_datetime2 и naive_datetime1.

Результат может быть возвращён в любой единице измерения :day, :hour, :minute, или любой другой, доступной из System.time_unit/0. Единица измерения определяется согласно Calendar.ISO и по умолчанию равна :second.

Дробные результаты не поддерживаются и усекаются.

Примеры

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])
0
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

Также можно вычислить разницу в днях, часах или минутах:

iex> NaiveDateTime.diff(~N[2014-10-10 00:29:10], ~N[2014-10-02 00:29:10], :day)
8
iex> NaiveDateTime.diff(~N[2014-10-02 12:29:10], ~N[2014-10-02 00:29:10], :hour)
12
iex> NaiveDateTime.diff(~N[2014-10-02 00:39:10], ~N[2014-10-02 00:29:10], :minute)
10

Но неполные дни округляются до нуля:

iex> NaiveDateTime.diff(~N[2014-10-10 00:29:09], ~N[2014-10-02 00:29:10], :day)
7

end_of_day(naive_datetime)Source

@spec end_of_day(Calendar.naive_datetime()) :: t()

Вычисляет NaiveDateTime, которая является последним моментом для данной NaiveDateTime.

Чтобы вычислить конец дня для DateTime, вызовите эту функцию, а затем преобразуйте обратно в DateTime:

datetime
|> NaiveDateTime.end_of_day()
|> DateTime.from_naive(datetime.time_zone)

Обратите внимание, что конец дня может не существовать или быть неоднозначным в заданном часовом поясе, поэтому вам необходимо соответствующим образом обработать эти случаи.

Примеры

iex> NaiveDateTime.end_of_day(~N[2000-01-01 23:00:07.123456])
~N[2000-01-01 23:59:59.999999]

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

@spec from_erl(
  :calendar.datetime(),
  Calendar.microsecond() | non_neg_integer(),
  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)
{:ok, ~N[2000-01-01 13:30:15.005000]}
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_erl!(tuple, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)Source

@spec from_erl!(
  :calendar.datetime(),
  Calendar.microsecond() | non_neg_integer(),
  Calendar.calendar()
) :: t()

Преобразует кортеж Erlang datetime в структуру 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)
~N[2000-01-01 13:30:15.005000]
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_gregorian_seconds(seconds, microsecond_precision \\ {0, 0}, calendar \\ Calendar.ISO)Source

@spec from_gregorian_seconds(integer(), Calendar.microsecond(), Calendar.calendar()) ::
  t()

Преобразует количество григорианских секунд в структуру NaiveDateTime.

Примеры

iex> NaiveDateTime.from_gregorian_seconds(1)
~N[0000-01-01 00:00:01]
iex> NaiveDateTime.from_gregorian_seconds(63_755_511_991, {5000, 3})
~N[2020-05-01 00:26:31.005]
iex> NaiveDateTime.from_gregorian_seconds(-1)
~N[-0001-12-31 23:59:59]

from_iso8601(строка, календарь \\ Calendar.ISO)Источник

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

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

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

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

Обратите внимание, что високосные секунды не поддерживаются встроенным Calendar.ISO.

Примеры

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}

from_iso8601!(строка, календарь \\ Calendar.ISO)Источник

@spec from_iso8601!(String.t(), Calendar.calendar()) :: t()

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

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

Примеры

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

local_now(календарь \\ Calendar.ISO)Источник

@spec local_now(Calendar.calendar()) :: t()

Возвращает «локальное время» для машины, на которой выполняется программа Elixir.

ВНИМАНИЕ: Эта функция может привести к скрытым ошибкам. Она зависит от конфигурации часового пояса во время выполнения. Это может быть изменено и установлено на часовой пояс, имеющий переходы на летнее время (переход вперёд или назад).

Эта функция может быть использована для отображения текущего времени в соответствии с настройкой часового пояса машины. Примером является приложение для рабочего стола, отображающее часы пользователю. Для других целей использование этой функции, вероятно, является плохой идеей.

В большинстве случаев используйте DateTime.now/2 или DateTime.utc_now/1 вместо этого.

Не включает дробные секунды.

Примеры

iex> naive_datetime = NaiveDateTime.local_now()
iex> naive_datetime.year >= 2019
true

new(дата, время)Источник

@spec 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(год, месяц, день, час, минута, секунда, микросекунда \\ {0, 0}, календарь \\ Calendar.ISO)Источник

@spec new(
  Calendar.year(),
  Calendar.month(),
  Calendar.day(),
  Calendar.hour(),
  Calendar.minute(),
  Calendar.second(),
  Calendar.microsecond() | non_neg_integer(),
  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, 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, 60, 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]}

new!(дата, время)Источник

@spec new!(Date.t(), Time.t()) :: t()

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

Примеры

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

new!(год, месяц, день, час, минута, секунда, микросекунда \\ {0, 0}, календарь \\ Calendar.ISO)Источник

@spec new!(
  Calendar.year(),
  Calendar.month(),
  Calendar.day(),
  Calendar.hour(),
  Calendar.minute(),
  Calendar.second(),
  Calendar.microsecond() | non_neg_integer(),
  Calendar.calendar()
) :: t()

Создаёт новое наивное значение даты и времени ISO.

Ожидает все значения в виде целых чисел. Возвращает naive_datetime если каждое значение находится в соответствующем диапазоне, а в противном случае генерирует исключение.

Примеры

iex> NaiveDateTime.new!(2000, 1, 1, 0, 0, 0)
~N[2000-01-01 00:00:00]
iex> NaiveDateTime.new!(2000, 2, 29, 0, 0, 0)
~N[2000-02-29 00:00:00]
iex> NaiveDateTime.new!(2000, 1, 1, 23, 59, 59, {0, 1})
~N[2000-01-01 23:59:59.0]
iex> NaiveDateTime.new!(2000, 1, 1, 23, 59, 59, 999_999)
~N[2000-01-01 23:59:59.999999]
iex> NaiveDateTime.new!(2000, 1, 1, 23, 59, 59, {0, 1}, Calendar.ISO)
~N[2000-01-01 23:59:59.0]
iex> NaiveDateTime.new!(2000, 1, 1, 24, 59, 59, 999_999)
** (ArgumentError) cannot build naive datetime, reason: :invalid_time

shift(naive_datetime, длительность)Источник

@spec shift(Calendar.naive_datetime(), Duration.duration()) :: t()

Смещает заданное naive_datetime на duration в соответствии с его календарём.

Допустимые единицы измерения: :year, :month, :week, :day, :hour, :minute, :second, :microsecond.

При использовании по умолчанию календаря ISO длительности сворачиваются и применяются в порядке месяцев, затем секунд и микросекунд:

при смещении на 1 год и 2 месяца, дата фактически смещается на 14 месяцев
недели, дни и более мелкие единицы сворачиваются в секунды и микросекунды

При смещении на месяц дни округляются вниз до ближайшей допустимой даты.

Примеры

iex> NaiveDateTime.shift(~N[2016-01-31 00:00:00], month: 1)
~N[2016-02-29 00:00:00]
iex> NaiveDateTime.shift(~N[2016-01-31 00:00:00], year: 4, day: 1)
~N[2020-02-01 00:00:00]
iex> NaiveDateTime.shift(~N[2016-01-31 00:00:00], year: -2, day: 1)
~N[2014-02-01 00:00:00]
iex> NaiveDateTime.shift(~N[2016-01-31 00:00:00], second: 45)
~N[2016-01-31 00:00:45]
iex> NaiveDateTime.shift(~N[2016-01-31 00:00:00], microsecond: {100, 6})
~N[2016-01-31 00:00:00.000100]

# leap years
iex> NaiveDateTime.shift(~N[2024-02-29 00:00:00], year: 1)
~N[2025-02-28 00:00:00]
iex> NaiveDateTime.shift(~N[2024-02-29 00:00:00], year: 4)
~N[2028-02-29 00:00:00]

# rounding down
iex> NaiveDateTime.shift(~N[2015-01-31 00:00:00], month: 1)
~N[2015-02-28 00:00:00]

to_date(карта)Источник

@spec to_date(Calendar.naive_datetime()) :: Date.t()

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

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

Примеры

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

to_erl(naive_datetime)Источник

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

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

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

ВНИМАНИЕ: Возможно потеря точности, так как кортежи даты и времени Erlang хранят только час, минуту и секунду.

Примеры

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

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

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_gregorian_seconds(карта)Источник

@spec to_gregorian_seconds(Calendar.naive_datetime()) ::
  {integer(), non_neg_integer()}

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

Примеры

iex> NaiveDateTime.to_gregorian_seconds(~N[0000-01-01 00:00:01])
{1, 0}
iex> NaiveDateTime.to_gregorian_seconds(~N[2020-05-01 00:26:31.005])
{63_755_511_991, 5000}

to_iso8601(naive_datetime, формат \\ :extended)Источник

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

Преобразует заданное наивное значение даты и времени в ISO 8601:2019.

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

Примеры

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)Источник

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

Преобразует заданное наивное значение даты и времени в строку в соответствии с его календарём.

Для повышения читабельности эта функция следует предложению RFC3339 об удалении разделителя «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(карта)Источник

@spec to_time(Calendar.naive_datetime()) :: Time.t()

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

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

Примеры

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

truncate(naive_datetime, precision)Source

@spec 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_or_time_unit \\ Calendar.ISO)Source

@spec utc_now(Calendar.calendar() | :native | :microsecond | :millisecond | :second) ::
  t()

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

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

Вы также можете указать единицу времени для автоматического усечения нативного значения даты и времени. Это доступно начиная с версии v1.15.0.

Примеры

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

iex> naive_datetime = NaiveDateTime.utc_now(:second)
iex> naive_datetime.microsecond
{0, 0}

utc_now(time_unit, calendar)Source

@spec utc_now(:native | :microsecond | :millisecond | :second, Calendar.calendar()) ::
  t()

Возвращает текущее нативное значение даты и времени в UTC, поддерживая определённый календарь и точность.

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

Примеры

iex> naive_datetime = NaiveDateTime.utc_now(:second, Calendar.ISO)
iex> naive_datetime.year >= 2016
true

iex> naive_datetime = NaiveDateTime.utc_now(:second, Calendar.ISO)
iex> naive_datetime.microsecond
{0, 0}

© 2012-2024 The Elixir Team
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.18.1/NaiveDateTime.html