UTC DateTime v0.0.3 UTCDateTime View Source
A datetime implementation constraint to UTC.
Link to this section Summary
Functions
A UTCDateTime
representing the given epoch
.
Converts the given datetime
into a 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 the given UTCDateTime
to NaiveDateTime
.
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.
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
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_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_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_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]
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"
Returns the current UTC datetime.
Examples
iex> utc_datetime = UTCDateTime.utc_now()
iex> utc_datetime.year >= 2016
true