lostkobrakai / zoneinfo

Elixir time zone support for your OS-supplied zoneinfo files

Zoneinfo

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 and tz 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

Installation

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:

1. The :tzpath key in the application environment
2. The TZPATH environment variable
3. /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"

Notes and caveats

Caching

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.

Date ranges

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.

Unit tests

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.

Acknowledgments

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.

License

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.