Elixir

v1.4.4

Elixir

Elixir v1.4.4 NaiveDateTime View Source

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 datetimes 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 time zone. 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 time zone, 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.

Link to this section Summary

Types

t()

Functions

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

Adds a specified amount of time to a NaiveDateTime

compare(naive_datetime1, naive_datetime2)

Compares two NaiveDateTime structs

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

Subtract naive_datetime2 from naive_datetime1

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

Converts an Erlang datetime tuple to a NaiveDateTime struct

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

Converts an Erlang datetime tuple to a NaiveDateTime struct

from_iso8601(arg)

Parses the extended “Date and time of day” format described by ISO 8601:2004

from_iso8601!(string)

Parses the extended “Date and time of day” format described by ISO 8601:2004

new(date, time)

Builds a naive datetime from date and time structs

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

Builds a new ISO naive datetime

to_date(naive_date_time)

Converts a NaiveDateTime into a Date

to_erl(map)

Converts a NaiveDateTime struct to an Erlang datetime tuple

to_iso8601(map)

Converts the given naive datetime to ISO 8601:2004

to_string(map)

Converts the given naive datetime to a string according to its calendar

to_time(naive_date_time)

Converts a NaiveDateTime into Time

utc_now()

Returns the current naive datetime in UTC

Link to this section Types

Link to this type t() View Source 
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}

Link to this section Functions

Link to this function add(naive_datetime, integer, unit \\ :second) View Source 
add(t, integer, System.time_unit) :: t

Adds a specified amount of time to a NaiveDateTime.

Accepts an integer in any unit available from System.time_unit/0. Negative values will be move backwards in time.

Examples 

# 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], 63579428950)
~N[2014-10-02 00:29:10]
Link to this function compare(naive_datetime1, naive_datetime2) View Source 
compare(Calendar.naive_datetime, Calendar.naive_datetime) ::
  :lt |
  :eq |
  :gt

Compares two NaiveDateTime structs.

Returns :gt if first is later than the second and :lt for vice versa. If the two NaiveDateTime are equal :eq is returned

Examples 

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

This function can also be used to compare a DateTime without the time zone information:

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
Link to this function diff(naive_datetime1, naive_datetime2, unit \\ :second) View Source 
diff(t, t, System.time_unit) :: integer

Subtract naive_datetime2 from naive_datetime1.

The answer can be returned in any unit available from System.time_unit/0.

Examples 

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
# to gregorian seconds
iex> NaiveDateTime.diff(~N[2014-10-02 00:29:10], ~N[0000-01-01 00:00:00])
63579428950
Link to this function from_erl(arg, microsecond \\ {0, 0}) View Source 
from_erl(:calendar.datetime, Calendar.microsecond) ::
  {:ok, 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.

Examples 

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}
Link to this function from_erl!(tuple, microsecond \\ {0, 0}) View Source 
from_erl!(:calendar.datetime, Calendar.microsecond) ::
  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.

Examples 

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
Link to this function from_iso8601(arg) View Source 
from_iso8601(String.t) :: {:ok, t} | {:error, atom}

Parses the extended “Date and time of day” format described by ISO 8601: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.

Examples 

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}
Link to this function from_iso8601!(string) View Source 
from_iso8601!(String.t) :: t | no_return

Parses the extended “Date and time of day” format described by ISO 8601:2004.

Raises if the format is invalid.

Examples 

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
Link to this function new(date, time) View Source 
new(Date.t, Time.t) :: {:ok, t}

Builds a naive datetime from date and time structs.

Examples 

iex> NaiveDateTime.new(~D[2010-01-13], ~T[23:00:07.005])
{:ok, ~N[2010-01-13 23:00:07.005]}
Link to this function new(year, month, day, hour, minute, second, microsecond \\ {0, 0}) View Source 
new(Calendar.year, Calendar.month, Calendar.day, Calendar.hour, Calendar.minute, Calendar.second, Calendar.microsecond) ::
  {:ok, t} |
  {:error, atom}

Builds a new ISO naive datetime.

Expects all values to be integers. Returns {:ok, naive_datetime} if each entry fits its appropriate range, returns {:error, reason} otherwise.

Examples 

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}
Link to this function to_date(naive_date_time) View Source 
to_date(t) :: Date.t

Converts a NaiveDateTime into a Date.

Because Date does not hold time information, data will be lost during the conversion.

Examples 

iex> NaiveDateTime.to_date(~N[2002-01-13 23:00:07])
~D[2002-01-13]
Link to this function to_erl(map) View Source 
to_erl(t) :: :calendar.datetime

Converts a NaiveDateTime struct to an Erlang datetime tuple.

Only supports converting naive datetimes which are in the ISO calendar, attempting to convert naive datetimes from other calendars will raise.

WARNING: Loss of precision may occur, as Erlang time tuples only store hour/minute/second.

Examples 

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

This function can also be used to convert a DateTime to a erl format without the time zone information:

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}}
Link to this function to_iso8601(map) View Source 
to_iso8601(Calendar.naive_datetime) :: String.t

Converts the given naive datetime to ISO 8601:2004.

Only supports converting naive datetimes which are in the ISO calendar, attempting to convert naive datetimes from other calendars will raise.

Examples

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"

This function can also be used to convert a DateTime to ISO8601 without the time zone information:

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"
Link to this function to_string(map) View Source 
to_string(Calendar.naive_datetime) :: String.t

Converts the given naive datetime to a string according to its calendar.

Examples

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"

This function can also be used to convert a DateTime to a string without the time zone information:

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"
Link to this function to_time(naive_date_time) View Source 
to_time(t) :: Time.t

Converts a NaiveDateTime into Time.

Because Time does not hold date information, data will be lost during the conversion.

Examples 

iex> NaiveDateTime.to_time(~N[2002-01-13 23:00:07])
~T[23:00:07]
Link to this function utc_now() View Source 
utc_now() :: t

Returns the current naive datetime in UTC.

Prefer using DateTime.utc_now/0 when possible as, opposite to NaiveDateTime, it will keep the time zone information.

Examples 

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