TimeZoneInfo v0.5.4

TimeZoneInfo

Hex.pm CI Coverage Status License: MIT

Time zone support for Elixir by using the IANA Time Zone Database.

Installation

The package can be installed by adding time_zone_info to your list of dependencies in mix.exs:

def deps do
  [
    {:time_zone_info, "~> 0.5"}
  ]
end

Usage

After installation, TimeZoneInfo can be used as follows.

iex> TimeZoneInfo.iana_version
"2020f"
iex> TimeZoneInfo.time_zones() |> Enum.take(3)
["Africa/Abidjan", "Africa/Accra", "Africa/Addis_Ababa"]
iex> TimeZoneInfo.period_from_utc(~N[2020-03-29 01:30:00], "Europe/Berlin")
{:ok, {3600, 3600, "CEST"}}

In combination with DateTime and Calendar:

iex> {:ok, berlin} = DateTime.from_naive(
...>   ~N[2020-03-29 01:30:00],
...>   "Europe/Berlin",
...>    TimeZoneInfo.TimeZoneDatabase)
{:ok, #DateTime<2020-03-29 01:30:00+01:00 CET Europe/Berlin>}
iex> Calendar.put_time_zone_database(TimeZoneInfo.TimeZoneDatabase)
:ok
iex> DateTime.shift_zone(berlin, "America/New_York")
{:ok, #DateTime<2020-03-28 20:30:00-04:00 EDT America/New_York>}

Instead of the line Calendar.put_time_zone_database(TimeZoneInfo.TimeZoneDatabase) you can also specify the following entry in the configuration.

config :elixir, :time_zone_database, TimeZoneInfo.TimeZoneDatabase

For more information how to configure TimeZoneInfo see Config. The site shows how to enable automated updates, filter time zones, and add custom behaviours.

Default Time Zone Data

The default configuration of TimeZoneInfo is updater: :disabled. In this case, the IANA database in version 2020f with a lookahead of 15 years is in use.

If a time zone has continuation rules, the periods after the lookahead are calculating by these rules. Note, these calculations are much more expensive as the determination of periods inside the prepared time span.

Benchmarks

The benchmarks can be executed with mix bench.

Benchmarks:

  • A benchmark to compare TimeZoneInfo with Tzdata and Tz for the execution of TimeZoneDatabase.time_zone_periods_from_wall_datetime/2.

  • A benchmark to compare different TimeZoneInfo.DataStores.

  • A benchmark to measure the speed of the transformation of the raw IANA data to the required data in runtime.

Differences to Tzdata and Tz

There are some differences to Tzdata and Tz. The list shows differences to Tzdata and/or Tz.

  • Use of :persitent_term with an optional use of :ets.
  • Persisting data in External Term Format
  • The data persisting is customizable by the behaviour TimeZoneInfo.DataPersistence.
  • Optional download of time zone data in TimeZoneInfo format.
  • The download is customizable by the behaviour TimeZoneInfo.Downloader.
  • Filter time zones per config.
  • Optional listener that will be called on updates.
  • TimeZoneInfo calculates periods in the far future by continuation rules. Except for time zones that have daylight saving times for Ramadan.

References

The home of the IANA Time Zone Database: https://www.iana.org/time-zones

Links:

Other Elixir implementations:

  • tzdata - Tzdata is a parser and library for the tz database.
  • tz - Time zone support for Elixir

Other implementations: