TzExtra v0.24.0

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-1

 TzExtra.countries_time_zones/1

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.

You may pass the :prepend_utc option set to true, in order to add the UTC time zone to the list; the following map is then added:

%{
  coordinates: nil,
  country: nil,
  dst_offset: 0,
  dst_zone_abbr: "UTC",
  pretty_dst_offset: "+00:00",
  pretty_utc_offset: "+00:00",
  time_zone: "UTC",
  time_zone_links: [],
  utc_offset: 0,
  zone_abbr: "UTC"
}

tzextra-time_zone_identifiers-1

 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_alias (by default set to false). 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

 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_alias (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).
  • :prepend_utc (by default set to false) Add the UTC time zone as the first element of the time zone list.

tzextra-countries-0

 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

 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

 TzExtra.Changeset.validate_time_zone_identifier/3 

import TzExtra.Changeset

changeset
|> validate_time_zone(: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

 TzExtra.Changeset.validate_civil_time_zone_identifier/3 

import TzExtra.Changeset

changeset
|> validate_civil_time_zone(:time_zone)

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

tzextra-changeset-validate_iso_country_code-3

 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

 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.24.0"}
  ]
end

dump-json-data-for-javascript

 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

 Installation

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

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

hexdocs

 HexDocs

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