View Source TzExtra

tz_extra provides a few utilities to work with time zones. It uses Tz under the hood, which brings time zone support for Elixir.

TzExtra.countries_time_zones/0

Returns a list of time zone data by country. The data includes:

  • the country and time zone;
  • the current UTC and DST offsets observed;
  • the links (other city names) linking to the time zone;
  • the zone abbreviation;
  • the coordinates.

Example

iex> TzExtra.countries_time_zones() |> Enum.at(5)
%{
  coordinates: "+0627+00324",
  country: %{code: "AO", name: "Angola"},
  dst_offset: 3600,
  dst_zone_abbr: "WAT",
  pretty_dst_offset: "+01:00",
  pretty_utc_offset: "+01:00",
  time_zone: "Africa/Lagos",
  time_zone_links: [
    "Africa/Bangui", "Africa/Brazzaville", "Africa/Douala",
    "Africa/Kinshasa", "Africa/Libreville", "Africa/Luanda",
    "Africa/Malabo", "Africa/Niamey", "Africa/Porto-Novo"
  ],
  utc_offset: 3600,
  zone_abbr: "WAT"
}

Note that a time zone may be observed by multiple countries. For example, the tz database version 2019c lists 10 countries observing the time zone Africa/Lagos; this will result in 10 map entries for that time zone.

TzExtra.CountryTimeZone.for_country_code/1

Returns a list of time zone data for the given country code (string or atom).

TzExtra.CountryTimeZone.for_time_zone/1

Returns a list of time zone data for the given time zone.

TzExtra.time_zone_identifiers/1

iex> TzExtra.time_zone_identifiers() |> Enum.take(5)
[
  "Africa/Abidjan",
  "Africa/Accra",
  "Africa/Algiers",
  "Africa/Bissau",
  "Africa/Cairo"
]

This function can take an option :include_aliases (by default set to false) to include time zone aliases. By default, only canonical time zones are returned. Set this option to true to include time zone aliases (also called links).

TzExtra.civil_time_zone_identifiers/1

iex> TzExtra.civil_time_zone_identifiers()

This function returns only the time zone identifiers attached to a country. It takes two options:

  • :include_aliases (by default set to false) By default, only canonical time zones are returned. Set this option to false to include time zone aliases (also called links).

TzExtra.countries/0

iex> TzExtra.countries() |> Enum.take(5)
[
  %{code: "AF", name: "Afghanistan"},
  %{code: "AL", name: "Albania"},
  %{code: "DZ", name: "Algeria"},
  %{code: "AD", name: "Andorra"},
  %{code: "AO", name: "Angola"}
]

TzExtra.get_canonical_time_zone_identifier/1

Returns the canonical time zone identifier for the given time zone identifier.

If you pass a canonical time zone identifier, the same identifier will be returned.

iex> TzExtra.get_canonical_time_zone_identifier("Asia/Phnom_Penh")
"Asia/Bangkok"
iex> TzExtra.get_canonical_time_zone_identifier("Asia/Bangkok")
"Asia/Bangkok"

TzExtra.Changeset.validate_time_zone_identifier/3

import TzExtra.Changeset

changeset
|> validate_time_zone_identifier(:time_zone)

You may pass the option :allow_alias to allow time zone aliases, as well as the :message option to customize the error message.

TzExtra.Changeset.validate_civil_time_zone_identifier/3

import TzExtra.Changeset

changeset
|> validate_civil_time_zone_identifier(:time_zone)

You may pass the option :allow_alias to allow time zone aliases, as well as the :message option to customize the error message.

TzExtra.Changeset.validate_iso_country_code/3

import TzExtra.Changeset

changeset
|> validate_iso_country_code(:country_code)

You may pass the :message option to customize the error message.

Automatic time zone data updates

tz_extra can watch for IANA time zone database updates and automatically recompile the time zone data.

To enable automatic updates, add TzExtra.UpdatePeriodically as a child in your supervisor:

{TzExtra.UpdatePeriodically, []}

You may pass the option :interval_in_days in order to configure the frequency of the task.

{TzExtra.UpdatePeriodically, [interval_in_days: 5]}

TzExtra.UpdatePeriodically also triggers tz's time zone recompilation; so you don't need to add Tz.UpdatePeriodically if you added TzExtra.UpdatePeriodically in your supervisor.

Lastly, if you did not configure a custom http client for tz, add the default http client mint and ssl certificate store castore into your mix.exs file:

defp deps do
  [
    {:castore, "~> 0.1.18"},
    {:mint, "~> 1.4"},
    {:tz_extra, "~> 0.27.0"}
  ]
end

Dump JSON data for JavaScript

Dump time zone data into JSON files for JavaScript clients. The JSON files are written into tz_extra's priv folder.

iex> TzExtra.JsonDumper.dump_countries_time_zones()
iex> TzExtra.JsonDumper.dump_countries()

Installation

Add tz_extra for Elixir as a dependency in your mix.exs file:

def deps do
  [
    {:tz_extra, "~> 0.27.0"}
  ]
end

HexDocs

HexDocs documentation can be found at https://hexdocs.pm/tz_extra.