Elixir time zone support for your OS-supplied zoneinfo files
Why Zoneinfo?
- Reuse your OS-maintained time zone database (usually in
/usr/share/zoneinfo
) - Reduce your OTP release size by not bundling time zone data
- Load other TZif files
Why not Zoneinfo?
tzdata
andtz
work fine for you- You can't rely on your OS to update time zone files and don't want to implement this yourself
- You're running on Windows (the zoneinfo database can still be installed, but this is not a typical configuration)
- You need to extrapolate time zone conversions far in the future or past. Zoneinfo currently is limited to the ranges in TZif files which typically go to 2038.
- Speed is of utmost importance. Zoneinfo loads time zones on demand and caches
them, but it does not focus on performance like
tz
.
Zoneinfo is tested for consistency against the tz
library. It's possible to
test against tzdata
by modifying @truth
in the unit tests. All libraries
source their information from the IANA Time Zone
Database
First, add :zoneinfo
to your list of dependencies in mix.exs
:
def deps do
[
{:zoneinfo, "~> 0.1.0"}
]
end
Next, decide whether you want to configure Elixir to use Zoneinfo as the default
time zone lookup. If you do, add the following line to your config.exs
:
config :elixir, time_zone_database: Zoneinfo.TimeZoneDatabase
or call Calendar.put_time_zone_database/1
:
Calendar.put_time_zone_database(Zoneinfo.TimeZoneDatabase)
It's also possible to pass Zoneinfo.TimeZoneDatabase
to DateTime
functions to
avoid the global configuration.
The final step is to specify the location of the time zone files. Zoneinfo looks at the following locations:
- The
:tzpath
key in the application environment - The
TZDIR
environment variable /usr/share/zoneinfo
Since /usr/share/zoneinfo
is the default on Linux and OSX, you may not need to
do anything.
To set :tzpath
in the application environment, add this line to your
config.exs
:
config :zoneinfo, tzpath: "/custom/location"
While Zoneinfo does not contain a database and therefore has no logic to pull updates, it does cache data in memory for better performance. It flushes the cache daily so that it's possible to pick up changes to the system timezone data.
Zoneinfo uses the date ranges stored in the TZif data for determining time zone information. While TZif files support extrapolation of dates beyond what's stored, Zoneinfo currently does not use it. This means that dates far enough in the future won't be calculated correctly.
The default end date from the time zone compiler, zic(8), is 2038. This could, of course, could change and one would hope that it would be pushed farther out rather than reduced since the files are already pretty small.
If you're looking at creating the smallest possible time zone database for and
embedded system, using zic
's -r
flag helps significantly, but make sure that
you have enough buffer to avoid extrapolation.
The tests currently take a long time to run since they're checking a LOT of
dates and times. If you're working on a patch, you may want to limit the date
range in time_zone_database_test.exs
to 10 years or less.
Both tz
and
tzdata
were both extremely helpful in
answering time zone questions. Code in this library will almost certainly look
like it was influenced from the two libraries. Additionally, being able to
compare the output of Zoneinfo to the output of those libraries caught a few
subtle time zone handling bugs that could easily have gone unnoticed. The IANA
time zone rules database comments and
timeanddate.com were also extremely
helpful to resolve discrepancies.
Copyright (C) 2021 SmartRent.com, LLC
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.