NaiveDateTime
Структура NaiveDateTime (без часового пояса) и функции.
Структура NaiveDateTime содержит поля year, month, day, hour, minute, second, microsecond и calendar. Новые наивные даты и времена можно создать с помощью функций new/2 и new/8 или используя сигил ~N (см. Kernel.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.
Использование эпох
Функции 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).
Резюме
Типы
Функции
- add(naive_datetime, amount_to_add, 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(map)
Преобразует
NaiveDateTimeвDate.- to_erl(naive_datetime)
Преобразует структуру
NaiveDateTimeв кортеж даты и времени Erlang.- to_iso8601(naive_datetime, format \\ :extended)
Преобразует данное наивное время в ISO 8601:2004.
- to_string(naive_datetime)
Преобразует данное наивное время в строку в соответствии с его календарём.
- to_time(map)
Преобразует
NaiveDateTimeвTime.- truncate(naive_datetime, precision)
Возвращает данное наивное время с полем microsecond, усечённым до заданной точности (
:microsecond,:millisecondили:second).- utc_now(calendar \\ Calendar.ISO)
Возвращает текущее наивное время в UTC.
Типы
t()
Specs
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, amount_to_add, unit \\ :second)
Спецификации
add(Calendar.naive_datetime(), integer(), System.time_unit()) :: t()
Добавляет заданное количество времени к NaiveDateTime.
Принимает amount_to_add в любом unit доступном от System.time_unit/0. Отрицательные значения сместят дату назад во времени.
Примеры
# 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] Передача 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] compare(naive_datetime1, naive_datetime2)
Спецификации
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)
Спецификации
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)
Спецификации
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}} diff(naive_datetime1, naive_datetime2, unit \\ :second)
Спецификации
diff(Calendar.naive_datetime(), Calendar.naive_datetime(), 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()) ::
{:ok, t()} | {:error, atom()} Преобразует кортеж Erlang даты и времени в структуру 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_erl!(tuple, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)
Спецификации
from_erl!(:calendar.datetime(), Calendar.microsecond(), Calendar.calendar()) :: t()
Преобразует кортеж 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_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. Обратите внимание, что високосные секунды не поддерживаются встроенным календарем 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!(string, calendar \\ Calendar.ISO)
Спецификации
from_iso8601!(String.t(), Calendar.calendar()) :: t()
Разбирает расширенный формат «дата и время суток», описанный в 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 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, 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]} to_date(map)
Спецификации
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)
Спецификации
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 в формат 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 возвращает наивные даты и время в формате «extended» для удобства чтения человеком. Также поддерживается формат «basic» при передаче опции :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(map)
Спецификации
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)
Спецификации
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)
Характеристики
utc_now(Calendar.calendar()) :: t()
Возвращает текущее простое время в UTC.
Предпочтительнее использовать DateTime.utc_now/0 по возможности, так как, в отличие от NaiveDateTime, он сохранит информацию о часовом поясе.
Примеры
iex> naive_datetime = NaiveDateTime.utc_now() iex> naive_datetime.year >= 2016 true
© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.9.4/NaiveDateTime.html
