A datetime implementation with a time zone.
This datetime can be seen as an ephemeral snapshot of a datetime at a given timezone. For such purposes, it also includes both UTC and Standard offsets, as well as the zone abbreviation field used exclusively for formatting purposes.
Developers should avoid creating the DateTime struct directly and instead rely on the functions provided by this module as well as the ones in 3rd party calendar libraries.
You will notice this module only contains conversion functions as well as functions that work on UTC. This is because a proper DateTime implementation requires a TimeZone database which currently is not provided as part of Elixir.
Such may be addressed in upcoming versions, meanwhile, use 3rd party packages to provide DateTime building and similar functionality with time zone backing.
Converts the given Unix time to DateTime
Converts the given Unix time to DateTime
Converts the given date time to ISO8601
Converts a DateTime
into a NaiveDateTime
Converts the given date time to a string according to its calendar
Converts the given DateTime to Unix time
Returns the current datetime in UTC
t() :: %DateTime{calendar: Calendar.calendar, day: Calendar.day, hour: Calendar.hour, microsecond: Calendar.microsecond, minute: Calendar.minute, month: Calendar.month, second: Calendar.second, std_offset: Calendar.std_offset, time_zone: Calendar.time_zone, utc_offset: Calendar.utc_offset, year: Calendar.year, zone_abbr: Calendar.zone_abbr}
from_unix(integer, :native | System.time_unit) :: {:ok, DateTime.t}
Converts the given Unix time to DateTime.
The integer can be given in different unit according to System.convert_time_unit/3
and it will be converted to microseconds internally.
Unix times are always in UTC and therefore the DateTime will be returned in UTC.
iex> DateTime.from_unix(1464096368)
{:ok, %DateTime{calendar: Calendar.ISO, day: 24, hour: 13, microsecond: {0, 0}, minute: 26,
month: 5, second: 8, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0,
year: 2016, zone_abbr: "UTC"}}
iex> DateTime.from_unix(1432560368868569, :microseconds)
{:ok, %DateTime{calendar: Calendar.ISO, day: 25, hour: 13, microsecond: {868569, 6}, minute: 26,
month: 5, second: 8, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0,
year: 2015, zone_abbr: "UTC"}}
The unit can also be an integer as in System.time_unit
:
iex> DateTime.from_unix(1432560368868569, 1024)
{:ok, %DateTime{calendar: Calendar.ISO, day: 23, hour: 22, microsecond: {211914, 3}, minute: 53,
month: 1, second: 43, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0,
year: 46302, zone_abbr: "UTC"}}
Negative Unix times are supported, up to -62167219200 seconds, which is equivalent to “0000-01-01T00:00:00Z” or 0 gregorian seconds.
iex> DateTime.from_unix(-12345678910)
{:ok, %DateTime{calendar: Calendar.ISO, day: 13, hour: 4, microsecond: {0, 0}, minute: 44,
month: 10, second: 50, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0,
year: 1578, zone_abbr: "UTC"}}
When a Unix time before that moment is passed to from_unix/2
, :error
will be returned.
from_unix!(non_neg_integer, :native | System.time_unit) :: DateTime.t
Converts the given Unix time to DateTime.
The integer can be given in different unit according to System.convert_time_unit/3
and it will be converted to microseconds internally.
Unix times are always in UTC and therefore the DateTime will be returned in UTC.
iex> DateTime.from_unix!(1464096368)
%DateTime{calendar: Calendar.ISO, day: 24, hour: 13, microsecond: {0, 0}, minute: 26,
month: 5, second: 8, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0,
year: 2016, zone_abbr: "UTC"}
iex> DateTime.from_unix!(1432560368868569, :microseconds)
%DateTime{calendar: Calendar.ISO, day: 25, hour: 13, microsecond: {868569, 6}, minute: 26,
month: 5, second: 8, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0,
year: 2015, zone_abbr: "UTC"}
Negative Unix times are supported, up to -62167219200 seconds, which is equivalent to “0000-01-01T00:00:00Z” or 0 gregorian seconds.
iex> DateTime.from_unix(-12345678910)
{:ok, %DateTime{calendar: Calendar.ISO, day: 13, hour: 4, microsecond: {0, 0}, minute: 44,
month: 10, second: 50, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0,
year: 1578, zone_abbr: "UTC"}}
When a Unix time before that moment is passed to from_unix!/2
, an ArgumentError will be raised.
Converts a DateTime
into a Date
.
Because Date
does not hold time nor timezone information, data will be lost during the conversion.
iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...> hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...> utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> DateTime.to_date(dt)
~D[2000-02-29]
to_iso8601(DateTime.t) :: String.t
Converts the given date time to ISO8601.
Only supports converting date times which are in the ISO calendar, attempting to convert date times from other calendars will raise.
WARNING: the ISO8601 does not contain the time zone nor its abbreviation, which means information is lost when converting to such format. This is also why this module does not provide a from_iso8601/1
function, as it is impossible to build a proper DateTime
from only the information in the ISO8601 string.
iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...> hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...> utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> DateTime.to_iso8601(dt)
"2000-02-29T23:00:07+01:00"
iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "UTC",
...> hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...> utc_offset: 0, std_offset: 0, time_zone: "Etc/UTC"}
iex> DateTime.to_iso8601(dt)
"2000-02-29T23:00:07Z"
iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "AMT",
...> hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...> utc_offset: -14400, std_offset: 0, time_zone: "America/Manaus"}
iex> DateTime.to_iso8601(dt)
"2000-02-29T23:00:07-04:00"
Converts a DateTime
into a NaiveDateTime
.
Because NaiveDateTime
does not hold timezone information, any timezone related data will be lost during the conversion.
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> DateTime.to_naive(dt)
~N[2000-02-29 23:00:07.0]
to_string(DateTime.t) :: String.t
Converts the given date time to a string according to its calendar.
iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...> hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...> utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> DateTime.to_string(dt)
"2000-02-29 23:00:07+01:00 CET Europe/Warsaw"
iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "UTC",
...> hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...> utc_offset: 0, std_offset: 0, time_zone: "Etc/UTC"}
iex> DateTime.to_string(dt)
"2000-02-29 23:00:07Z"
iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "AMT",
...> hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...> utc_offset: -14400, std_offset: 0, time_zone: "America/Manaus"}
iex> DateTime.to_string(dt)
"2000-02-29 23:00:07-04:00 AMT America/Manaus"
Converts a DateTime
into Time
.
Because Time
does not hold date nor timezone information, data will be lost during the conversion.
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> DateTime.to_time(dt)
~T[23:00:07.0]
to_unix(DateTime.t, System.time_unit) :: non_neg_integer
Converts the given DateTime to Unix time.
The DateTime is expected to be using the ISO calendar with a year greater than or equal to 0.
It will return the integer with the given unit, according to System.convert_time_unit/3
.
iex> 1464096368 |> DateTime.from_unix!() |> DateTime.to_unix()
1464096368
iex> dt = %DateTime{calendar: Calendar.ISO, day: 20, hour: 18, microsecond: {273806, 6},
...> minute: 58, month: 11, second: 19, time_zone: "America/Montevideo",
...> utc_offset: -10800, std_offset: 3600, year: 2014, zone_abbr: "UYST"}
iex> DateTime.to_unix(dt)
1416517099
iex> flamel = %DateTime{calendar: Calendar.ISO, day: 22, hour: 8, microsecond: {527771, 6},
...> minute: 2, month: 3, second: 25, std_offset: 0, time_zone: "Etc/UTC",
...> utc_offset: 0, year: 1418, zone_abbr: "UTC"}
iex> DateTime.to_unix(flamel)
-17412508655
utc_now() :: DateTime.t
Returns the current datetime in UTC.
iex> datetime = DateTime.utc_now()
iex> datetime.time_zone
"Etc/UTC"
© 2012–2017 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.3.3/DateTime.html