Packages
tz_extra
0.15.0
0.45.0
0.44.0
0.43.0
0.42.0
0.41.0
0.40.0
0.39.0
0.38.0
0.37.0
0.36.0
0.35.0
0.34.0
0.33.0
0.32.0
0.31.0
0.30.0
0.29.0
0.28.0
0.27.0
0.26.0
0.25.0
0.24.0
0.23.0
0.22.1
0.22.0
0.21.1
0.21.0
0.20.1
0.20.0
0.17.0
0.16.7
0.16.6
0.16.5
0.16.3
0.16.2
0.16.1
0.16.0
0.15.1
0.15.0
0.8.0
0.7.0
0.6.0
0.5.0
0.4.0
0.3.0
0.2.0
0.1.0
Time zone-related utilities
Current section
Files
Jump to
Current section
Files
README.md
# TzExtra
`tz_extra` provides a few utilities to work with time zones.
### `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 `:with_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`
```
iex> TzExtra.time_zone_identifiers() |> Enum.take(5)
```
```
[
"Africa/Abidjan",
"Africa/Accra",
"Africa/Algiers",
"Africa/Bissau",
"Africa/Cairo"
]
```
This function takes two options:
* `:exclude_non_civil` (by default `true`)
By default, only time zones attached to countries are returned. Set this option to `false` to include time zones that aren't not tied to a particular country.
* `:exclude_alias` (by default `true`)
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"}
]
```
### 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, []}
```
`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, add the http client `mint` and ssl certificate store `castore` into your `mix.exs` file:
```
defp deps do
[
{:castore, "~> 0.1.10"},
{:mint, "~> 1.2"},
{:tz_extra, "~> 0.15.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:
```elixir
def deps do
[
{:tz_extra, "~> 0.15.0"}
]
end
```
## HexDocs
HexDocs documentation can be found at [https://hexdocs.pm/tz_extra](https://hexdocs.pm/tz_extra).