NaiveDateTime

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

Структура NaiveDateTime содержит поля year, month, day, hour, minute, second, microsecond и calendar. Новые даты без часового пояса можно создать с помощью функции new/7 или используя сигил ~N:

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

Оба new/7 и сигил возвращают структуру, где поля даты можно получить напрямую:

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

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

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

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

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

Типы

t()

Функции

from_erl(arg, microsecond \\ {0, 0})

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

from_erl!(tuple, microsecond \\ {0, 0})

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

from_iso8601(arg)

Парсит расширенный формат «Дата и время дня», описанный в ISO8601:2004

from_iso8601!(string)

Парсит расширенный формат «Дата и время дня», описанный в ISO8601:2004

new(date, time)

Создает дату и время без часового пояса из структур date и time

new(year, month, day, hour, minute, second, microsecond \\ {0, 0})

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

to_date(naive_date_time)

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

to_erl(naive_date_time)

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

to_iso8601(naive)

Преобразует заданную дату и время без часового пояса в ISO8601

to_string(naive)

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

to_time(naive_date_time)

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

Типы

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}

Функции

from_erl(arg, microsecond \\ {0, 0})

from_erl(:calendar.datetime, Calendar.microsecond) ::
  {:ok, NaiveDateTime.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})

from_erl!(:calendar.datetime, Calendar.microsecond) ::
  NaiveDateTime.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 date time, reason: :invalid_date

from_iso8601(arg)

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

Парсит расширенный формат «Дата и время дня», описанный в ISO8601:2004.

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

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

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

Примеры

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

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

Парсит расширенный формат «Дата и время дня», описанный в ISO8601: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-23P23:50:07")
** (ArgumentError) cannot parse "2015-01-23P23:50:07" as naive date time, reason: :invalid_format

new(date, time)

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

Создает дату и время без часового пояса из структур date и time.

Примеры

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

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

Создает новую дату и время ISO без часового пояса.

Ожидаются целочисленные значения. Возвращает {:ok, naive_date_time} если каждое значение попадает в соответствующий диапазон, возвращает {: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}

to_date(naive_date_time)

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

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

Примеры

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

to_erl(naive_date_time)

to_erl(NaiveDateTime.t) :: :calendar.datetime

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

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

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

Примеры

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

to_iso8601(naive)

to_iso8601(NaiveDateTime.t) :: String.t

Преобразует заданную дату и время без часового пояса в ISO8601.

Поддерживает только преобразование дат и времени без часового пояса в календаре 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"

to_string(naive)

to_string(NaiveDateTime.t) :: 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"

to_time(naive_date_time)

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

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

Примеры

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