UTC DateTime v1.0.0 UTCDateTime View Source
A datetime implementation constraint to UTC.
Link to this section Summary
Functions
Adds a specified amount of time to a UTCDateTime
.
Compares two UTCDateTime
structs.
Subtracts utc_datetime1
from utc_datetime2
.
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.
Converts the given Unix time to UTCDateTime
.
Converts the given Unix time to UTCDateTime
.
Handles the sigil ~Z
to create a UTCDateTime
.
Converts a UTCDateTime
into a Date
.
Converts the given UTCDateTime
to DateTime
.
Converts the given utc_datetime
to the given epoch time.
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 the given NTFS or Windows time.
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
.
Converts the given utc_datetime
to Unix time.
Returns the given utc_datetime
with the microsecond field truncated to the
given precision (:microsecond
, :millisecond
or :second
).
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
add(utc_datetime, amount_to_add, unit \\ :second)
View Sourceadd(t(), integer(), System.time_unit()) :: t()
Adds a specified amount of time to a UTCDateTime
.
Accepts an amount_to_add
in any unit
available from System.time_unit/0
.
Negative values will move the utc_datetime
backwards in time.
Examples
# adds seconds by default
iex> UTCDateTime.add(~Z[2014-10-02 00:29:10], 2)
~Z[2014-10-02 00:29:12]
# accepts negative offsets
iex> UTCDateTime.add(~Z[2014-10-02 00:29:10], -2)
~Z[2014-10-02 00:29:08]
# can work with other units
iex> UTCDateTime.add(~Z[2014-10-02 00:29:10], 2_000, :millisecond)
~Z[2014-10-02 00:29:12]
# keeps the same precision
iex> UTCDateTime.add(~Z[2014-10-02 00:29:10.021], 21, :second)
~Z[2014-10-02 00:29:31.021]
# changes below the precision will not be visible
iex> hidden = UTCDateTime.add(~Z[2014-10-02 00:29:10], 21, :millisecond)
iex> hidden.microsecond # ~Z[2014-10-02 00:29:10]
{21000, 0}
# from Gregorian seconds
iex> UTCDateTime.add(~Z[0000-01-01 00:00:00], 63_579_428_950)
~Z[2014-10-02 00:29:10]
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
diff(utc_datetime1, utc_datetime2, unit \\ :second)
View Sourcediff(t(), t(), System.time_unit()) :: integer()
Subtracts utc_datetime1
from utc_datetime2
.
The answer can be returned in any unit
available from System.time_unit/0
.
This function returns the difference in seconds where seconds are measured
according to Calendar.ISO
.
Examples
iex> UTCDateTime.diff(~Z[2014-10-02 00:29:12], ~Z[2014-10-02 00:29:10])
2
iex> UTCDateTime.diff(~Z[2014-10-02 00:29:12], ~Z[2014-10-02 00:29:10], :microsecond)
2_000_000
iex> UTCDateTime.diff(~Z[2014-10-02 00:29:10.042], ~Z[2014-10-02 00:29:10.021], :millisecond)
21
iex> UTCDateTime.diff(~Z[2014-10-02 00:29:10], ~Z[2014-10-02 00:29:12])
-2
iex> UTCDateTime.diff(~Z[-0001-10-02 00:29:10], ~Z[-0001-10-02 00:29:12])
-2
# to Gregorian seconds
iex> UTCDateTime.diff(~Z[2014-10-02 00:29:10], ~Z[0000-01-01 00:00:00])
63579428950
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]
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]
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, 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()) :: 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
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}
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]
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+0230")
{:ok, ~Z[2015-01-23 21:20:07.123]}
iex> UTCDateTime.from_rfc3339("2015-01-23T23:50:07.123-0230")
{:ok, ~Z[2015-01-24 02:20:07.123]}
iex> UTCDateTime.from_rfc3339("2015-01-23T23:50:07.123+02")
{:ok, ~Z[2015-01-23 21:50:07.123]}
iex> UTCDateTime.from_rfc3339("2015-01-23T23:50:07.123-02")
{:ok, ~Z[2015-01-24 01:50: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}
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
from_unix(unix, unit \\ :second)
View Sourcefrom_unix(integer(), :native | System.time_unit()) :: {:ok, t()} | {:error, atom()}
Converts the given Unix time to UTCDateTime
.
The integer can be given in different unit
according to System.convert_time_unit/3
and it will
be converted to microseconds internally.
Examples
iex> UTCDateTime.from_unix(1_464_096_368)
{:ok, ~Z[2016-05-24 13:26:08]}
iex> UTCDateTime.from_unix(1_432_560_368_868_569, :microsecond)
{:ok, ~Z[2015-05-25 13:26:08.868569]}
The unit can also be an integer as in System.time_unit/0
:
iex> UTCDateTime.from_unix(143_256_036_886_856, 1024)
{:ok, ~Z[6403-03-17 07:05:22.320312]}
Negative Unix times are supported, up to -62167219200 seconds, which is equivalent to "0000-01-01T00:00:00Z" or 0 Gregorian seconds.
from_unix!(unix, unit \\ :second)
View Sourcefrom_unix!(integer(), :native | System.time_unit()) :: t() | no_return()
Converts the given Unix time to UTCDateTime
.
The integer can be given in different unit
according to System.convert_time_unit/3
and it will
be converted to microseconds internally.
Examples
# An easy way to get the Unix epoch is passing 0 to this function
iex> UTCDateTime.from_unix!(0)
~Z[1970-01-01 00:00:00Z]
iex> UTCDateTime.from_unix!(1_464_096_368)
~Z[2016-05-24 13:26:08]
iex> UTCDateTime.from_unix!(1_432_560_368_868_569, :microsecond)
~Z[2015-05-25 13:26:08.868569]
iex> UTCDateTime.from_unix!(143_256_036_886_856, 1024)
~Z[6403-03-17 07:05:22.320312]
Negative Unix times are supported, up to -62167219200 seconds, which is equivalent to "0000-01-01T00:00:00Z" or 0 Gregorian seconds.
iex> UTCDateTime.from_unix!(-12_063_167_219_280)
** (ArgumentError) invalid Unix time -12063167219280
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(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(t(), Calendar.calendar()) :: DateTime.t()
Converts the given UTCDateTime
to DateTime
.
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_epoch(utc_datetime, epoch, unit \\ :second)
View Sourceto_epoch(t(), epoch(), System.time_unit()) :: integer()
Converts the given utc_datetime
to the given epoch time.
It will return the integer with the given unit,
according to System.convert_time_unit/3
.
Examples
iex> UTCDateTime.to_epoch(~Z[2019-12-20 23:20:52], :unix)
1576884052
iex> UTCDateTime.to_epoch(~Z[2019-12-20 23:20:52], :ntfs)
13221357652
iex> UTCDateTime.to_epoch(~Z[2019-12-20 23:20:52], :go)
63712480852
iex> UTCDateTime.to_epoch(~Z[2019-12-20 23:20:52.832399], :unix)
1576884052
iex> UTCDateTime.to_epoch(~Z[2019-12-20 23:20:52.832399], :unix, :millisecond)
1576884052832
iex> UTCDateTime.to_epoch(~Z[2019-12-20 23:20:52.832399], :unix, :microsecond)
1576884052832399
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(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]
to_ntfs(utc_datetime, unit \\ 10000000)
View Sourceto_ntfs(t(), System.time_unit()) :: integer()
Converts the given utc_datetime
to the given NTFS or Windows time.
It will return the integer with the given unit,
according to System.convert_time_unit/3
,
but defaults to the stand 100 nanosecond intervals.
For reference: support.microsoft.com
Examples
iex> UTCDateTime.to_ntfs(~Z[2019-12-20 23:20:52.832399])
132213576528323990
iex> UTCDateTime.to_ntfs(~Z[2019-12-20 23:20:52.832399], :millisecond)
13221357652832
iex> UTCDateTime.to_ntfs(~Z[2019-12-20 23:20:52.832399], :microsecond)
13221357652832399
iex> UTCDateTime.to_ntfs(~Z[1219-12-20 23:20:52.832399])
-120242039471676010
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(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]
to_unix(utc_datetime, unit \\ :second)
View Sourceto_unix(t(), System.time_unit()) :: integer()
Converts the given utc_datetime
to Unix time.
It will return the integer with the given unit,
according to System.convert_time_unit/3
.
Examples
iex> 1_464_096_368 |> UTCDateTime.from_unix!() |> UTCDateTime.to_unix()
1464096368
iex> UTCDateTime.to_unix(~Z[2019-12-20 23:20:52.832399])
1576884052
iex> UTCDateTime.to_unix(~Z[2019-12-20 23:20:52.832399], :millisecond)
1576884052832
iex> UTCDateTime.to_unix(~Z[2019-12-20 23:20:52.832399], :microsecond)
1576884052832399
iex> UTCDateTime.to_unix(~Z[1219-12-20 23:20:52.832399])
-23668677548
Returns the given utc_datetime
with the microsecond field truncated to the
given precision (:microsecond
, :millisecond
or :second
).
The given naive datetime is returned unchanged if it already has lower precision than the given precision.
Examples
iex> UTCDateTime.truncate(~Z[2017-11-06 00:23:51.123456], :microsecond)
~Z[2017-11-06 00:23:51.123456]
iex> UTCDateTime.truncate(~Z[2017-11-06 00:23:51.123456], :millisecond)
~Z[2017-11-06 00:23:51.123]
iex> UTCDateTime.truncate(~Z[2017-11-06 00:23:51.123456], :second)
~Z[2017-11-06 00:23:51]
Returns the current UTC datetime.
Examples
iex> utc_datetime = UTCDateTime.utc_now()
iex> utc_datetime.year >= 2016
true