Expand description
A crate that embeds data from the IANA Time Zone Database.
This crate is meant to be a “raw data” library. That is, it primarily exposes
one routine that permits looking up the raw TZif data given a time zone name.
The data returned is embedded into the compiled library. In order to actually
use the data, you’ll need a TZif parser, such as the one found in Jiff via
TimeZone::tzif.
This crate also exposes another routine, available, for iterating over the
names of all time zones embedded into this crate.
§Should I use this crate?
In general, no. It’s first and foremost an implementation detail of Jiff, but if you 1) need raw access to the TZif data and 2) need to bundle it in your binary, then it’s plausible that using this crate is appropriate.
With that said, the preferred way to read TZif data is from your system’s
copy of the Time Zone Database. On macOS and most Linux installations, a copy
of this data can be found at /usr/share/zoneinfo. Indeed, Jiff will use this
system copy whenever possible, and not use this crate at all. The system copy
is preferred because the Time Zone Database is occasionally updated (perhaps a
few times per year), and it is usually better to rely on your system updates
for such things than some random Rust library.
However, some popular environments, like Windows, do not have a standard system copy of the Time Zone Database. In those circumstances, Jiff will depend on this crate and bundle the time zone data into the binary. This is not an ideal solution, but it makes Most Things Just Work Most of the Time on all major platforms.
§Data generation
The data in this crate comes from the IANA Time Zone Database “data only”
distribution. jiff-cli is used to first compile the release into binary
TZif data using the zic compiler, and secondly, converts the binary data into
a flattened and de-duplicated representation that is embedded into this crate’s
source code.
The conversion into the TZif binary data uses the following settings:
- The “rearguard” data is used (see below).
- The binary data itself is compiled using the “slim” format. Which
effectively means that the TZif data primarily only uses explicit
time zone transitions for historical data and POSIX time zones for
current time zone transition rules. This doesn’t have any impact
on the actual results. The reason that there are “slim” and “fat”
formats is to support legacy applications that can’t deal with
POSIX time zones. For example,
/usr/share/zoneinfoon my modern Archlinux installation (2025-02-27) is in the “fat” format.
The reason that rearguard data is used is a bit more subtle and has to do with
a difference in how the IANA Time Zone Database treats its internal “daylight
saving time” flag and what people in the “real world” consider “daylight
saving time.” For example, in the standard distribution of the IANA Time Zone
Database, Europe/Dublin has its daylight saving time flag set to true
during Winter and set to false during Summer. The actual time shifts are the
same as, e.g., Europe/London, but which one is actually labeled “daylight
saving time” is not.
The IANA Time Zone Database does this for Europe/Dublin, presumably, because
legally, time during the Summer in Ireland is called Irish Standard Time,
and time during the Winter is called Greenwich Mean Time. These legal names
are reversed from what is typically the case, where “standard” time is during
the Winter and daylight saving time is during the Summer. The IANA Time Zone
Database implements this tweak in legal language via a “negative daylight
saving time offset.” This is somewhat odd, and some consumers of the IANA Time
Zone Database cannot handle it. Thus, the rearguard format was born for,
seemingly, legacy programs.
Jiff can handle negative daylight saving time offsets just fine, but we use the
rearguard format anyway so that the underlying data more accurately reflects
on-the-ground reality for humans living in Europe/Dublin. In particular,
using the rearguard data enables localization of time zone names to be done
correctly.
Structs§
- Time
Zone Name Iter - An iterator over all time zone names embedded into this crate.
Statics§
- VERSION
- The version of the IANA Time Zone Database that was bundled.