impl TimeZoneDatabase

const fn none() -> TimeZoneDatabase

Returns a database for which all time zone lookups fail.

Example

use jiff::tz::TimeZoneDatabase;

let db = TimeZoneDatabase::none();
assert_eq!(db.available().count(), 0);

fn from_env() -> TimeZoneDatabase

Returns a time zone database initialized from the current environment.

This routine never fails, but it may not be able to find a copy of your Time Zone Database. When this happens, log messages (with some at least at the WARN level) will be emitted. They can be viewed by installing a log compatible logger such as env_logger.

Typically, one does not need to call this routine directly. Instead, it's done for you as part of jiff::tz::db. This does require Jiff's std feature to be enabled though. So for example, you might use this constructor when the features alloc and tzdb-bundle-always are enabled to get access to a bundled copy of the IANA time zone database. (Accessing the system copy at /usr/share/zoneinfo requires std.)

Beware that calling this constructor will create a new distinct handle from the one returned by jiff::tz::db with its own cache.

Platform behavior

When the TZDIR environment variable is set, this will attempt to open the Time Zone Database at the directory specified. Otherwise, this will search a list of predefined directories for a system installation of the Time Zone Database. Typically, it's found at /usr/share/zoneinfo.

On Windows systems, under the default crate configuration, this will return an embedded copy of the Time Zone Database since Windows does not have a canonical installation of the Time Zone Database.

fn from_dir<P: AsRef<Path>>(path: P) -> Result<TimeZoneDatabase, Error>

Returns a time zone database initialized from the given directory.

Unlike TimeZoneDatabase::from_env, this always attempts to look for a copy of the Time Zone Database at the directory given. And if it fails to find one at that directory, then an error is returned.

Basically, you should use this when you need to use a specific copy of the Time Zone Database, and use TimeZoneDatabase::from_env when you just want Jiff to try and "do the right thing for you."

Errors

This returns an error if the given directory does not contain a valid copy of the Time Zone Database. Generally, this means a directory with at least one valid TZif file.

fn from_concatenated_path<P: AsRef<Path>>(path: P) -> Result<TimeZoneDatabase, Error>

Returns a time zone database initialized from a path pointing to a concatenated tzdata file. This type of format is only known to be found on Android environments. The specific format for this file isn't defined formally anywhere, but Jiff parses the same format supported by the Android Platform.

Unlike TimeZoneDatabase::from_env, this always attempts to look for a copy of the Time Zone Database at the path given. And if it fails to find one at that path, then an error is returned.

Basically, you should use this when you need to use a specific copy of the Time Zone Database in its concatenated format, and use TimeZoneDatabase::from_env when you just want Jiff to try and "do the right thing for you." (TimeZoneDatabase::from_env will attempt to automatically detect the presence of a system concatenated tzdata file on Android.)

Errors

This returns an error if the given path does not contain a valid copy of the concatenated Time Zone Database.

fn bundled() -> TimeZoneDatabase

Returns a time zone database initialized from the bundled copy of the IANA Time Zone Database.

While this API is always available, in order to get a non-empty database back, this requires that one of the crate features tzdb-bundle-always or tzdb-bundle-platform is enabled. In the latter case, the bundled database is only available on platforms known to lack a system copy of the IANA Time Zone Database (i.e., non-Unix systems).

This routine is infallible, but it may return a database that is definitively empty if the bundled data is not available. To query whether the data is empty or not, use TimeZoneDatabase::is_definitively_empty.

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/zoneinfo on 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.

fn get(&self, name: &str) -> Result<TimeZone, Error>

Returns a TimeZone corresponding to the IANA time zone identifier given.

The lookup is performed without regard to ASCII case.

To see a list of all available time zone identifiers for this database, use TimeZoneDatabase::available.

It is guaranteed that if the given time zone name is case insensitively equivalent to UTC, then the time zone returned will be equivalent to TimeZone::UTC. Similarly for Etc/Unknown and TimeZone::unknown().

Example

use jiff::tz;

let tz = tz::db().get("america/NEW_YORK")?;
assert_eq!(tz.iana_name(), Some("America/New_York"));

# Ok::<(), Box<dyn std::error::Error>>(())

fn available<'d>(&'d self) -> TimeZoneNameIter<'d>

Returns a list of all available time zone identifiers from this database.

Note that time zone identifiers are more of a machine readable abstraction and not an end user level abstraction. Still, users comfortable with configuring their system's default time zone through IANA time zone identifiers are probably comfortable interacting with the identifiers returned here.

Example

use jiff::tz;

for tzid in tz::db().available() {
    println!("{tzid}");
}

fn reset(&self)

Resets the internal cache of this database.

Subsequent interactions with this database will need to re-read time zone data from disk.

It might be useful to call this if you know the time zone database has changed on disk and want to force Jiff to re-load it immediately without spawning a new process or waiting for Jiff's internal cache invalidation heuristics to kick in.

fn is_definitively_empty(&self) -> bool

Returns true if it is known that this time zone database is empty.

When this returns true, it is guaranteed that all TimeZoneDatabase::get calls will fail, and that TimeZoneDatabase::available will always return an empty iterator.

Note that if this returns false, it is still possible for this database to be empty.

Example

use jiff::tz::TimeZoneDatabase;

let db = TimeZoneDatabase::none();
assert!(db.is_definitively_empty());