A NaiveDateTime struct (without a time zone) and functions.
The NaiveDateTime struct contains the fields year, month, day, hour, minute, second, microsecond and calendar. New naive date times can be built with the new/7
function or using the ~N
sigil:
iex> ~N[2000-01-01 23:00:07]
~N[2000-01-01 23:00:07]
Both new/7
and sigil return a struct where the date fields can be accessed directly:
iex> naive = ~N[2000-01-01 23:00:07]
iex> naive.year
2000
iex> naive.second
7
The naive bit implies this datetime representation does not have a timezone. This means the datetime may not actually exist in certain areas in the world even though it is valid.
For example, when daylight saving changes are applied by a region, the clock typically moves forward or backward by one hour. This means certain datetimes never occur or may occur more than once. Since NaiveDateTime
is not validated against a timezone, such errors would go unnoticed.
Developers should avoid creating the NaiveDateTime struct directly and instead rely on the functions provided by this module as well as the ones in 3rd party calendar libraries.
Converts an Erlang datetime tuple to a NaiveDateTime
struct
Converts an Erlang datetime tuple to a NaiveDateTime
struct
Parses the extended “Date and time of day” format described by ISO8601:2004
Parses the extended “Date and time of day” format described by ISO8601:2004
Builds a naive date time from date and time structs
Builds a new ISO naive date time
Converts a NaiveDateTime
into a Date
Converts a NaiveDateTime
struct to an Erlang datetime tuple
Converts the given naive date time to ISO8601
Converts the given naive date time to a string according to its calendar
Converts a NaiveDateTime
into Time
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(:calendar.datetime, Calendar.microsecond) :: {:ok, NaiveDateTime.t} | {:error, atom}
Converts an Erlang datetime tuple to a NaiveDateTime
struct.
Attempting to convert an invalid ISO calendar date will produce an error tuple.
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!(:calendar.datetime, Calendar.microsecond) :: NaiveDateTime.t | no_return
Converts an Erlang datetime tuple to a NaiveDateTime
struct.
Raises if the datetime is invalid. Attempting to convert an invalid ISO calendar date will produce an error tuple.
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(String.t) :: {:ok, NaiveDateTime.t} | {:error, atom}
Parses the extended “Date and time of day” format described by ISO8601:2004.
Timezone offset may be included in the string but they will be simply discarded as such information is not included in naive date times.
As specified in the standard, the separator “T” may be omitted if desired as there is no ambiguity within this function.
Time representations with reduced accuracy are not supported.
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.t) :: NaiveDateTime.t | no_return
Parses the extended “Date and time of day” format described by ISO8601:2004.
Raises if the format is invalid.
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.t, Time.t) :: {:ok, NaiveDateTime.t}
Builds a naive date time from date and time structs.
iex> NaiveDateTime.new(~D[2010-01-13], ~T[23:00:07.005])
{:ok, ~N[2010-01-13 23:00:07.005]}
new(Calendar.year, Calendar.month, Calendar.day, Calendar.hour, Calendar.minute, Calendar.second, Calendar.microsecond) :: {:ok, NaiveDateTime.t} | {:error, atom}
Builds a new ISO naive date time.
Expects all values to be integers. Returns {:ok, naive_date_time}
if each entry fits its appropriate range, returns {:error, reason}
otherwise.
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}
Converts a NaiveDateTime
into a Date
.
Because Date
does not hold time information, data will be lost during the conversion.
iex> NaiveDateTime.to_date(~N[2002-01-13 23:00:07])
~D[2002-01-13]
to_erl(NaiveDateTime.t) :: :calendar.datetime
Converts a NaiveDateTime
struct to an Erlang datetime tuple.
Only supports converting naive date times which are in the ISO calendar, attempting to convert naive date times from other calendars will raise.
WARNING: Loss of precision may occur, as Erlang time tuples only store hour/minute/second.
iex> NaiveDateTime.to_erl(~N[2000-01-01 13:30:15])
{{2000, 1, 1}, {13, 30, 15}}
to_iso8601(NaiveDateTime.t) :: String.t
Converts the given naive date time to ISO8601.
Only supports converting naive date times which are in the ISO calendar, attempting to convert naive date times from other calendars will raise.
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(NaiveDateTime.t) :: String.t
Converts the given naive date time to a string according to its calendar.
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"
Converts a NaiveDateTime
into Time
.
Because Time
does not hold date information, data will be lost during the conversion.
iex> NaiveDateTime.to_time(~N[2002-01-13 23:00:07])
~T[23:00:07]
© 2012–2017 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.3.3/NaiveDateTime.html