UTC DateTime v0.0.5 UTCDateTime View Source

A datetime implementation constraint to UTC.

Link to this section Summary

Types

Common datetime epochs.

t()

A datetime implementation constraint to UTC.

Functions

A UTCDateTime representing the given epoch.

Converts the given datetime into a UTCDateTime.

Converts a erl_datetime (Erlang datetime tuple) to UTCDateTime.

Converts a erl_datetime (Erlang datetime tuple) to UTCDateTime.

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

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

Parses the extended "Date and time of day" format described by RFC 3339.

Parses the extended "Date and time of day" format described by RFC 3339.

Handles the sigil ~Z to create a UTCDateTime.

Converts a UTCDateTime struct to an Erlang datetime tuple.

Converts the given utc_datetime to ISO 8601:2004.

Converts the given utc_datetime to RFC3339.

Converts the given utc_datetime to a string using the format defined by RFC 3339.

Returns the current UTC datetime.

Link to this section Types

Link to this type

epoch()

View Source
epoch() ::
  :cobol
  | :dotnet
  | :dvb
  | :dyalog_alp
  | :go
  | :google_sheets
  | :libre_office_calc
  | :lotus
  | :mjd
  | :ms_c
  | :ms_com
  | :ms_excel
  | :mumps
  | :ntfs
  | :pascal
  | :posix
  | :rata_die
  | :rexx
  | :unix
  | :usno
  | :uuid
  | :vms
  | :win
  | :win32
  | :win64
  | :win_nt

Common datetime epochs.

Epochs

EpochDateAliases
:go0001-01-01:dotnet, :rata_die, :rexx
:uuid1582-10-15
:win1601-01-01:win_nt, :win32, :cobol, :ntfs
:mumps1840-12-31
:vms1858-11-17:vms, :usno, :dvb, :mjd
:pascal1899-12-30:ms_com, :libre_office_calc, :google_sheets
:ms_c1899-12-31:dyalog_alp
:ms_excel1900-01-00:ms_excel, :lotus
:unix1970-01-01:posix
Link to this type

t()

View Source
t() :: %UTCDateTime{
  day: Calendar.day(),
  hour: Calendar.hour(),
  microsecond: Calendar.microsecond(),
  minute: Calendar.minute(),
  month: Calendar.month(),
  second: Calendar.second(),
  year: Calendar.year()
}

A datetime implementation constraint to UTC.

Link to this section Functions

Link to this function

compare(utc_datetime1, utc_datetime2)

View Source
compare(t(), t()) :: :lt | :eq | :gt

Compares two UTCDateTime structs.

Returns :gt if first (utc_datetime1) is later than the second (utc_datetime2) and :lt for vice versa. If the two UTCDateTime are equal :eq is returned.

Examples

iex> UTCDateTime.compare(~Z[2016-04-16 13:30:15], ~Z[2016-04-28 16:19:25])
:lt
iex> UTCDateTime.compare(~Z[2016-04-16 13:30:15.1], ~Z[2016-04-16 13:30:15.01])
:gt
iex> UTCDateTime.compare(~Z[2016-04-16 13:30:15.654321], ~Z[2016-04-16 13:30:15.654321])
:eq
Link to this function

epoch(epoch)

View Source
epoch(epoch :: epoch()) :: t() | no_return()

A UTCDateTime representing the given epoch.

Epochs

EpochDateAliases
:go0001-01-01:dotnet, :rata_die, :rexx
:uuid1582-10-15
:win1601-01-01:win_nt, :win32, :cobol, :ntfs
:mumps1840-12-31
:vms1858-11-17:vms, :usno, :dvb, :mjd
:pascal1899-12-30:ms_com, :libre_office_calc, :google_sheets
:ms_c1899-12-31:dyalog_alp
:ms_excel1900-01-00:ms_excel, :lotus
:unix1970-01-01:posix

Examples

iex> UTCDateTime.epoch(:unix)
~Z[1970-01-01 00:00:00]

iex> UTCDateTime.epoch(:win)
~Z[1601-01-01 00:00:00]

iex> UTCDateTime.epoch(:go)
~Z[0001-01-01 00:00:00]
Link to this function

from_date(date, time \\ ~T"00:00:00")

View Source
from_date(Date.t(), Time.t()) :: UTCDateTime.t()

Converts a Date into UTCDateTime.

Because Date does not hold time information, it is possible to supply a Time to set on the given Date.

If no Time is supplied the UTCDateTime will default to: 00:00:00.

Examples

iex> UTCDateTime.from_date(~D[2002-01-13])
~Z[2002-01-13 00:00:00]

iex> UTCDateTime.from_date(~D[2002-01-13], ~T[23:00:07])
~Z[2002-01-13 23:00:07]
Link to this function

from_datetime(datetime)

View Source
from_datetime(DateTime.t()) :: UTCDateTime.t()

Converts the given datetime into a UTCDateTime.

Any datetime with a none UTC time zone will be converted to UTC.

Examples

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "UTC",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 1},
...>                utc_offset: 0, std_offset: 0, time_zone: "Etc/UTC"}
iex> UTCDateTime.from_datetime(dt)
~Z[2000-02-29 23:00:07.0]
iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 1},
...>                utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> UTCDateTime.from_datetime(dt)
~Z[2000-02-29 22:00:07.0]
Link to this function

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

View Source
from_erl(:calendar.datetime(), Calendar.microsecond()) ::
  {:ok, UTCDateTime.t()}
  | {:error,
     reason ::
       :invalid_format
       | :invalid_month
       | :invalid_day
       | :invalid_hour
       | :invalid_minute
       | :invalid_second}

Converts a erl_datetime (Erlang datetime tuple) to UTCDateTime.

A tuple of microsecond (precision) can additionally be given to extend the datetime.

Examples

iex> UTCDateTime.from_erl({{2000, 1, 1}, {13, 30, 15}})
{:ok, ~Z[2000-01-01 13:30:15]}

iex> UTCDateTime.from_erl({{2000, 1, 1}, {13, 30, 15}}, {5000, 3})
{:ok, ~Z[2000-01-01 13:30:15.005]}
iex> UTCDateTime.from_erl({{2000, 13, 1}, {13, 30, 15}})
{:error, :invalid_month}
iex> UTCDateTime.from_erl({{2000, 12, 32}, {13, 30, 15}})
{:error, :invalid_day}
iex> UTCDateTime.from_erl({{2000, 12, 31}, {25, 30, 15}})
{:error, :invalid_hour}
iex> UTCDateTime.from_erl({{2000, 12, 31}, {13, 61, 15}})
{:error, :invalid_minute}
iex> UTCDateTime.from_erl({{2000, 12, 31}, {13, 30, 61}})
{:error, :invalid_second}
Link to this function

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

View Source

Converts a erl_datetime (Erlang datetime tuple) to UTCDateTime.

Raises if the datetime is invalid.

A tuple of microsecond (precision) can additionally be given to extend the datetime.

Examples

iex> UTCDateTime.from_erl!({{2000, 1, 1}, {13, 30, 15}})
~Z[2000-01-01 13:30:15]
iex> UTCDateTime.from_erl!({{2000, 1, 1}, {13, 30, 15}}, {5000, 3})
~Z[2000-01-01 13:30:15.005]
iex> UTCDateTime.from_erl!({{2000, 13, 1}, {13, 30, 15}})
** (ArgumentError) cannot convert {{2000, 13, 1}, {13, 30, 15}} to UTC datetime, reason: :invalid_month
Link to this function

from_iso8601(datetime)

View Source
from_iso8601(String.t()) ::
  {:ok, UTCDateTime.t()}
  | {:error,
     reason ::
       :invalid_format
       | :invalid_month
       | :invalid_day
       | :invalid_hour
       | :invalid_minute
       | :invalid_second}

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

Time zone offset may be included in the string but they will be converted to UTC time and stored as such.

The year parsed by this function is limited to four digits and, while ISO 8601 allows datetimes to specify 24:00:00 as the zero hour of the next day, this notation is not supported by Elixir.

Note leap seconds are not supported.

Examples

iex> UTCDateTime.from_iso8601("2015-01-23t23:50:07")
{:ok, ~Z[2015-01-23 23:50:07]}
iex> UTCDateTime.from_iso8601("2015-01-23T23:50:07")
{:ok, ~Z[2015-01-23 23:50:07]}
iex> UTCDateTime.from_iso8601("2015-01-23 23:50:07")
{:ok, ~Z[2015-01-23 23:50:07]}
iex> UTCDateTime.from_iso8601("2015-01-23T23:50:07Z")
{:ok, ~Z[2015-01-23 23:50:07]}
iex> UTCDateTime.from_iso8601("2015-01-23T23:50:07.0")
{:ok, ~Z[2015-01-23 23:50:07.0]}
iex> UTCDateTime.from_iso8601("2015-01-23T23:50:07,0123456")
{:ok, ~Z[2015-01-23 23:50:07.012345]}
iex> UTCDateTime.from_iso8601("2015-01-23T23:50:07.0123456")
{:ok, ~Z[2015-01-23 23:50:07.012345]}
iex> UTCDateTime.from_iso8601("2015-01-23T23:50:07.123Z")
{:ok, ~Z[2015-01-23 23:50:07.123]}
iex> UTCDateTime.from_iso8601("2016-02-29T23:50:07")
{:ok, ~Z[2016-02-29 23:50:07]}
iex> UTCDateTime.from_iso8601("2015-01-23P23:50:07")
{:error, :invalid_format}
iex> UTCDateTime.from_iso8601("2015:01:23 23-50-07")
{:error, :invalid_format}
iex> UTCDateTime.from_iso8601("2015-01-23 23:50:07A")
{:error, :invalid_format}
iex> UTCDateTime.from_iso8601("2015-01-23T24:50:07")
{:error, :invalid_hour}
iex> UTCDateTime.from_iso8601("2015-01-23T23:61:07")
{:error, :invalid_minute}
iex> UTCDateTime.from_iso8601("2015-01-23T23:50:61")
{:error, :invalid_second}
iex> UTCDateTime.from_iso8601("2015-13-12T23:50:07")
{:error, :invalid_month}
iex> UTCDateTime.from_iso8601("2015-01-32T23:50:07")
{:error, :invalid_day}
iex> UTCDateTime.from_iso8601("2015-02-29T23:50:07")
{:error, :invalid_day}
iex> UTCDateTime.from_iso8601("2015-01-23T23:50:07.123+02:30")
{:ok, ~Z[2015-01-23 21:20:07.123]}
iex> UTCDateTime.from_iso8601("2015-01-23T23:50:07.123+00:00")
{:ok, ~Z[2015-01-23 23:50:07.123]}
iex> UTCDateTime.from_iso8601("2015-01-23T23:50:07.123-02:30")
{:ok, ~Z[2015-01-24 02:20:07.123]}
iex> UTCDateTime.from_iso8601("2015-01-23T23:50:07.123-00:00")
{:error, :invalid_format}
iex> UTCDateTime.from_iso8601("2015-01-23T23:50:07.123-00:60")
{:error, :invalid_format}
iex> UTCDateTime.from_iso8601("2015-01-23T23:50:07.123-24:00")
{:error, :invalid_format}
Link to this function

from_iso8601!(datetime)

View Source
from_iso8601!(String.t()) :: UTCDateTime.t() | no_return()

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

Raises if the format is invalid.

For more examples see: from_iso8601/1.

Examples

iex> UTCDateTime.from_iso8601!("2015-01-23T23:50:07.123Z")
~Z[2015-01-23 23:50:07.123]
iex> UTCDateTime.from_iso8601!("2015-01-23T23:50:07,123Z")
~Z[2015-01-23 23:50:07.123]
iex> UTCDateTime.from_iso8601!("2015-01-23P23:50:07")
** (ArgumentError) cannot parse "2015-01-23P23:50:07" as UTC datetime, reason: :invalid_format
Link to this function

from_naive(naive_datetime)

View Source
from_naive(NaiveDateTime.t()) :: t()

Converts the given NaiveDateTime to UTCDateTime.

It expects the given naive_datetime to be in the "Etc/UTC" time zone.

Examples

iex> UTCDateTime.from_naive(~N[2016-05-24 13:26:08.003])
~Z[2016-05-24 13:26:08.003]
Link to this function

from_rfc3339(datetime)

View Source
from_rfc3339(String.t()) ::
  {:ok, UTCDateTime.t()}
  | {:error,
     reason ::
       :invalid_format
       | :invalid_month
       | :invalid_day
       | :invalid_hour
       | :invalid_minute
       | :invalid_second}

Parses the extended "Date and time of day" format described by RFC 3339.

Time zone offset may be included in the string but they will be converted to UTC time and stored as such.

The year parsed by this function is limited to four digits and, while RFC 3339 allows datetimes to specify 24:00:00 as the zero hour of the next day, this notation is not supported.

Passing -00:00 as undefined timezone is also not supported and will be interpreted as UTC.

Note leap seconds are not supported.

Examples

iex> UTCDateTime.from_rfc3339("2015-01-23t23:50:07")
{:ok, ~Z[2015-01-23 23:50:07]}
iex> UTCDateTime.from_rfc3339("2015-01-23T23:50:07")
{:ok, ~Z[2015-01-23 23:50:07]}
iex> UTCDateTime.from_rfc3339("2015-01-23T23:50:07Z")
{:ok, ~Z[2015-01-23 23:50:07]}
iex> UTCDateTime.from_rfc3339("2015-01-23T23:50:07.0")
{:ok, ~Z[2015-01-23 23:50:07.0]}
iex> UTCDateTime.from_rfc3339("2015-01-23T23:50:07,0123456")
{:ok, ~Z[2015-01-23 23:50:07.012345]}
iex> UTCDateTime.from_rfc3339("2015-01-23T23:50:07.0123456")
{:ok, ~Z[2015-01-23 23:50:07.012345]}
iex> UTCDateTime.from_rfc3339("2015-01-23T23:50:07.123Z")
{:ok, ~Z[2015-01-23 23:50:07.123]}
iex> UTCDateTime.from_rfc3339("2016-02-29T23:50:07")
{:ok, ~Z[2016-02-29 23:50:07]}
iex> UTCDateTime.from_rfc3339("2015-01-23P23:50:07")
{:error, :invalid_format}
iex> UTCDateTime.from_rfc3339("2015:01:23 23-50-07")
{:error, :invalid_format}
iex> UTCDateTime.from_rfc3339("2015-01-23 23:50:07A")
{:error, :invalid_format}
iex> UTCDateTime.from_rfc3339("2015-01-23T24:50:07")
{:error, :invalid_hour}
iex> UTCDateTime.from_rfc3339("2015-01-23T23:61:07")
{:error, :invalid_minute}
iex> UTCDateTime.from_rfc3339("2015-01-23T23:50:61")
{:error, :invalid_second}
iex> UTCDateTime.from_rfc3339("2015-13-12T23:50:07")
{:error, :invalid_month}
iex> UTCDateTime.from_rfc3339("2015-01-32T23:50:07")
{:error, :invalid_day}
iex> UTCDateTime.from_rfc3339("2015-02-29T23:50:07")
{:error, :invalid_day}
iex> UTCDateTime.from_rfc3339("2015-01-23T23:50:07.123+02:30")
{:ok, ~Z[2015-01-23 21:20:07.123]}
iex> UTCDateTime.from_rfc3339("2015-01-23T23:50:07.123+00:00")
{:ok, ~Z[2015-01-23 23:50:07.123]}
iex> UTCDateTime.from_rfc3339("2015-01-23T23:50:07.123-02:30")
{:ok, ~Z[2015-01-24 02:20:07.123]}
iex> UTCDateTime.from_rfc3339("2015-01-23T23:50:07.123-00:00")
{:error, :invalid_format}
iex> UTCDateTime.from_rfc3339("2015-01-23T23:50:07.123-00:60")
{:error, :invalid_format}
iex> UTCDateTime.from_rfc3339("2015-01-23T23:50:07.123-24:00")
{:error, :invalid_format}
Link to this function

from_rfc3339!(datetime)

View Source
from_rfc3339!(String.t()) :: UTCDateTime.t() | no_return()

Parses the extended "Date and time of day" format described by RFC 3339.

Raises if the format is invalid.

For more examples see: from_rfc3339/1.

Examples

iex> UTCDateTime.from_rfc3339!("2015-01-23T23:50:07.123Z")
~Z[2015-01-23 23:50:07.123]
iex> UTCDateTime.from_rfc3339!("2015-01-23T23:50:07,123Z")
~Z[2015-01-23 23:50:07.123]
iex> UTCDateTime.from_rfc3339!("2015-01-23P23:50:07")
** (ArgumentError) cannot parse "2015-01-23P23:50:07" as UTC datetime, reason: :invalid_format
Link to this macro

sigil_Z(utc_datetime_string, modifiers)

View Source (macro)

Handles the sigil ~Z to create a UTCDateTime.

By default, this sigil requires UTC date times to be written in the ISO8601 format:

~Z[yyyy-mm-dd hh:mm:ssZ]
~Z[yyyy-mm-dd hh:mm:ss.ssssssZ]
~Z[yyyy-mm-ddThh:mm:ss.ssssss+00:00]

such as:

~Z[2015-01-13 13:00:07Z]
~Z[2015-01-13T13:00:07.123+00:00]

The given utc_datetime_string must include "Z" or "00:00" offset which marks it as UTC, otherwise an error is raised.

The lower case ~z variant does not exist as interpolation and escape characters are not useful for date time sigils. More information on date times can be found in the UTCDateTime module.

Examples

iex> ~Z[2015-01-13 13:00:07Z]
~Z[2015-01-13 13:00:07Z]
iex> ~Z[2015-01-13T13:00:07.001+00:00]
~Z[2015-01-13 13:00:07.001Z]
Link to this function

to_date(utc_datetime, calendar \\ Calendar.ISO)

View Source

Converts a UTCDateTime into a Date.

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

Because the given utc_datetime does not contain calendar information, a calendar can be given, but will default to Calendar.ISO.

Examples

iex> UTCDateTime.to_date(~Z[2002-01-13 23:00:07])
~D[2002-01-13]
Link to this function

to_datetime(utc_datetime, calendar \\ Calendar.ISO)

View Source
to_datetime(UTCDateTime.t(), Calendar.calendar()) :: DateTime.t()

Converts the given UTCDateTime to NaiveDateTime.

The given utc_datetime does not contain a calendar, so Calendar.ISO is set by default. It is possible to manually pass a different calendar.

Examples

iex> UTCDateTime.to_datetime(~Z[2016-05-24 13:26:08.003])
~U[2016-05-24 13:26:08.003Z]

Converts a UTCDateTime struct to an Erlang datetime tuple.

WARNING: Loss of precision may occur, as Erlang time tuples only store hour/minute/second and the given utc_datetime could contain microsecond precision time data.

Examples

iex> UTCDateTime.to_erl(~Z[2000-01-01 13:30:15])
{{2000, 1, 1}, {13, 30, 15}}
Link to this function

to_iso8601(utc_datetime)

View Source
to_iso8601(t()) :: String.t()

Converts the given utc_datetime to ISO 8601:2004.

Examples

iex> UTCDateTime.to_iso8601(~Z[2019-12-14 08:06:24.289659])
"2019-12-14T08:06:24.289659Z"
iex> UTCDateTime.to_iso8601(~Z[2019-12-14 08:06:24])
"2019-12-14T08:06:24Z"
Link to this function

to_naive(utc_datetime, calendar \\ Calendar.ISO)

View Source

Converts the given UTCDateTime into a NaiveDateTime.

The given utc_datetime does not contain a calendar, so Calendar.ISO is set by default. It is possible to manually pass a different calendar.

Examples

iex> dt = %UTCDateTime{year: 2016, month: 5, day: 24, ...> hour: 13, minute: 26, second: 8, ...> microsecond: {3000, 3}} iex> UTCDateTime.to_naive(dt) ~N[2016-05-24 13:26:08.003]

Link to this function

to_rfc3339(utc_datetime)

View Source
to_rfc3339(t()) :: String.t()

Converts the given utc_datetime to RFC3339.

Examples

iex> UTCDateTime.to_rfc3339(~Z[2019-12-14 08:06:24.289659])
"2019-12-14T08:06:24.289659Z"
iex> UTCDateTime.to_rfc3339(~Z[2019-12-14 08:06:24])
"2019-12-14T08:06:24Z"
Link to this function

to_string(utc_datetime)

View Source
to_string(UTCDateTime.t()) :: String.t()

Converts the given utc_datetime to a string using the format defined by RFC 3339.

For more examples see: to_rfc3339/1.

Examples

iex> UTCDateTime.to_string(~Z[2000-02-28 23:00:13])
"2000-02-28T23:00:13Z"
iex> UTCDateTime.to_string(~Z[2000-02-28 23:00:13.001])
"2000-02-28T23:00:13.001Z"
Link to this function

to_time(utc_datetime, calendar \\ Calendar.ISO)

View Source

Converts a UTCDateTime into Time.

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

Because the given utc_datetime does not contain calendar information, a calendar can be given, but will default to Calendar.ISO.

Examples

iex> UTCDateTime.to_time(~Z[2002-01-13 23:00:07])
~T[23:00:07]
Link to this function

utc_now()

View Source
utc_now() :: t()

Returns the current UTC datetime.

Examples

iex> utc_datetime = UTCDateTime.utc_now()
iex> utc_datetime.year >= 2016
true