UTC DateTime v0.0.5 UTCDateTime View Source
A datetime implementation constraint to UTC.
Link to this section Summary
Functions
Compares two UTCDateTime
structs.
A UTCDateTime
representing the given epoch
.
Converts a Date
into UTCDateTime
.
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.
Converts the given NaiveDateTime
to UTCDateTime
.
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
into a Date
.
Converts the given UTCDateTime
to NaiveDateTime
.
Converts a UTCDateTime
struct to an Erlang datetime tuple.
Converts the given utc_datetime
to
ISO 8601:2004.
Converts the given UTCDateTime
into a NaiveDateTime
.
Converts the given utc_datetime
to
RFC3339.
Converts the given utc_datetime
to a string using the format
defined by RFC 3339.
Converts a UTCDateTime
into Time
.
Returns the current UTC datetime.
Link to this section Types
epoch()
View Sourceepoch() :: :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
Epoch | Date | Aliases |
---|---|---|
:go | 0001-01-01 | :dotnet , :rata_die , :rexx |
:uuid | 1582-10-15 | |
:win | 1601-01-01 | :win_nt , :win32 , :cobol , :ntfs |
:mumps | 1840-12-31 | |
:vms | 1858-11-17 | :vms , :usno , :dvb , :mjd |
:pascal | 1899-12-30 | :ms_com , :libre_office_calc , :google_sheets |
:ms_c | 1899-12-31 | :dyalog_alp |
:ms_excel | 1900-01-00 | :ms_excel , :lotus |
:unix | 1970-01-01 | :posix |
t()
View Sourcet() :: %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
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
A UTCDateTime
representing the given epoch
.
Epochs
Epoch | Date | Aliases |
---|---|---|
:go | 0001-01-01 | :dotnet , :rata_die , :rexx |
:uuid | 1582-10-15 | |
:win | 1601-01-01 | :win_nt , :win32 , :cobol , :ntfs |
:mumps | 1840-12-31 | |
:vms | 1858-11-17 | :vms , :usno , :dvb , :mjd |
:pascal | 1899-12-30 | :ms_com , :libre_office_calc , :google_sheets |
:ms_c | 1899-12-31 | :dyalog_alp |
:ms_excel | 1900-01-00 | :ms_excel , :lotus |
:unix | 1970-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]
from_date(date, time \\ ~T"00:00:00")
View Sourcefrom_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]
from_datetime(datetime)
View Sourcefrom_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]
from_erl(erl_datetime, microsecond \\ {0, 0})
View Sourcefrom_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}
from_erl!(erl_datetime, microsecond \\ {0, 0})
View Sourcefrom_erl!(:calendar.datetime(), Calendar.microsecond()) :: UTCDateTime.t()
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
from_iso8601(datetime)
View Sourcefrom_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}
from_iso8601!(datetime)
View Sourcefrom_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
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]
from_rfc3339(datetime)
View Sourcefrom_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}
from_rfc3339!(datetime)
View Sourcefrom_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
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]
to_date(utc_datetime, calendar \\ Calendar.ISO)
View Sourceto_date(UTCDateTime.t(), Calendar.calendar()) :: Date.t()
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]
to_datetime(utc_datetime, calendar \\ Calendar.ISO)
View Sourceto_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]
to_erl(utc_datetime)
View Sourceto_erl(UTCDateTime.t()) :: :calendar.datetime()
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}}
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"
to_naive(utc_datetime, calendar \\ Calendar.ISO)
View Sourceto_naive(UTCDateTime.t(), Calendar.calendar()) :: NaiveDateTime.t()
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]
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"
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"
to_time(utc_datetime, calendar \\ Calendar.ISO)
View Sourceto_time(UTCDateTime.t(), Calendar.calendar()) :: Time.t()
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]
Returns the current UTC datetime.
Examples
iex> utc_datetime = UTCDateTime.utc_now()
iex> utc_datetime.year >= 2016
true