Tz
Time zone support for Elixir.
The Elixir standard library does not ship with a time zone database. As a result, the functions in the DateTime
module can, by default, only operate on datetimes in the UTC time zone. Alternatively (and
deliberately), the standard library relies on
third-party libraries, such as tz
, to bring in time zone support and deal with datetimes in other time zones than UTC.
The tz
library relies on the time zone database maintained by
IANA. As of version 0.5.0, tz
uses version tzdata2019c of the IANA time zone database.
Features
Battle-tested
The tz
library is tested against nearly 10 million past dates, which includes most of all possible imaginable
edge cases.
Pre-compiled time zone data into maps
Time zone periods are deducted from the IANA time zone data. A period is a period of time where a certain offset is observed. Example: in Belgium, from 31 March 2019 until 27 October 2019, clock went forward by 1 hour; this means that during this period, Belgium observed a total offset of 2 hours from UTC time.
The time zone periods are computed and made available in Elixir maps during compilation time, to be consumed by the DateTime module.
Usage
To use the tz
database, either configure it via configuration:
config :elixir, :time_zone_database, Tz.TimeZoneDatabase
or by calling Calendar.put_time_zone_database/1
:
Calendar.put_time_zone_database(Tz.TimeZoneDatabase)
or by passing the module name Tz.TimeZoneDatabase
directly to the functions that need a time zone database:
DateTime.now("America/Sao_Paulo", Tz.TimeZoneDatabase)
Refer to the DateTime API for more details about handling datetimes with time zones.
Installation
Add tz
for Elixir as a dependency in your mix.exs
file:
def deps do
[
{:tz, "~> 0.5.0"}
]
end
HexDocs
HexDocs documentation can be found at https://hexdocs.pm/tz.