UTC DateTime v1.0.0 UTCDateTime 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

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()

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

add(utc_datetime, amount_to_add, unit \\ :second)

add(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]

compare(utc_datetime1, utc_datetime2)

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

diff(utc_datetime1, utc_datetime2, unit \\ :second)

diff(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

epoch(epoch)

epoch(epoch :: epoch()) :: t() | no_return()

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])

from_date(Date.t(), Time.t()) :: 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)

from_datetime(DateTime.t()) :: 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})

from_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})

from_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

from_iso8601(datetime)

from_iso8601(String.t()) ::
  {:ok, 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)

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.

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

from_naive(naive_datetime)

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]

from_rfc3339(datetime)

from_rfc3339(String.t()) ::
  {:ok, 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+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}

from_rfc3339!(datetime)

from_rfc3339!(String.t()) :: 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

from_unix(unix, unit \\ :second)

from_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)

from_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

sigil_Z(utc_datetime_string, modifiers)

(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]

to_date(utc_datetime, calendar \\ Calendar.ISO)

to_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)

to_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)

to_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

to_erl(utc_datetime)

to_erl(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}}

to_iso8601(utc_datetime)

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"

to_naive(utc_datetime, calendar \\ Calendar.ISO)

to_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)

to_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

to_rfc3339(utc_datetime)

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"

to_string(utc_datetime)

to_string(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"

to_time(utc_datetime, calendar \\ Calendar.ISO)

to_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)

to_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

truncate(utc_datetime, precision)

truncate(t(), :microsecond | :millisecond | :second) :: t()

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]

utc_now()

utc_now() :: t()

Returns the current UTC datetime.

Examples

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