.. _library_tzif:

tzif

The tzif library loads TZif v1, v2, and v3 files from the IANA time zone database into inspectable terms and answers UTC-based lookup queries over one or more zones.

Requires a backend Prolog compiler with unbounded integer arithmetic.

Current feature set:

• Loads sources given as file(Path, ZoneId), files(Root, Paths), directory(Root), stream(Stream, ZoneId), bytes(Bytes, ZoneId), or snapshot(File) using load/1 or load/2.
• Supports TZif v1, v2, and v3, including validated skipping of the v1 compatibility block in v2/v3 files.
• Parses POSIX footers, including signed-hour and signed-minute offsets.
• Exposes zone-aware lookup predicates over loaded tzif(...) terms, plus cached convenience variants for zone and single-zone queries.
• Exposes strict local civil-time lookup predicates that fail cleanly for ambiguous or nonexistent times.
• Exposes *_with_resolution local civil-time query predicates for explicit resolution modes (strict, first, second, and all).
• Exposes *_reified local civil-time query predicates that return unique(...), ambiguous(...), or nonexistent results.
• Caches successful load/1 calls automatically, while load/2 returns a loaded term without changing the cache.
• Provides cache/1 for making an already loaded tzif(...) term the active cached term.
• Saves and reloads tzif(...) terms as plain Prolog snapshot files, with save/1 providing a convenience predicate for saving the cached term.
• Returns the source term recorded in the active cached term via cache_source/1.
• Exposes the active cached term using cached_tzif/1.
• Exposes the cached zone list using zones/1.
• Accepts UTC queries as Unix seconds or date_time/6 terms.
• Validates zone identifiers against bundled IANA TZDB 2026a canonical names plus backward-compatible aliases.

API documentation

Open the `../../apis/library_index.html#tzif <../../apis/library_index.html#tzif>`__ link in a web browser.

Loading

To load all entities in this library, load the loader.lgt file:

::

| ?- logtalk_load(tzif(loader)).

Testing

To test this library predicates, load the tester.lgt file:

::

| ?- logtalk_load(tzif(tester)).

Representation

Loaded sources are returned by load/2 as lists of tzif(Zone, Source, ZoneData) terms, one term per loaded zone.

Each nested ZoneData term contains the parsed block data, leap-second records, and parsed footer for a single zone. These per-zone tzif(...) terms are stable enough to be serialized directly using save/2 and restored using load(snapshot(File), TZifs).

For directory and file-set loads, zone identifiers are the relative paths used to locate the TZif files inside the root directory, and each loaded term records its own file(File, ZoneId) source.

When loading a directory(Root), regular files whose relative paths are not recognized zone identifiers are ignored. This allows loading system zoneinfo trees that also contain metadata files such as leapseconds.

For single-zone file, stream, and byte-list loads, the caller must provide the zone identifier explicitly using file(Path, ZoneId), stream(Stream, ZoneId), or bytes(Bytes, ZoneId).

The cache stores one tzif(...) term per zone id. load/1 and cache/1 replace only cached entries whose zone ids match the newly loaded terms.

Zone identifier validation

The library validates zone identifiers using bundled data derived from the official IANA TZDB 2026a release. Accepted identifiers include both canonical zone names such as America/New_York and backward-compatible aliases such as US/Eastern.

The bundled data is generated from the IANA zone1970.tab and backward files and does not consult the host operating system's installed zoneinfo tree.

To refresh the bundled table for a newer IANA release, run:

::

$ ./update_zone_ids.sh 2026a

Local Queries

The library provides three sets of predicates for local civil-time queries.

Strict predicates:

• local_time_type/2-4
• local_offset/2-4
• local_daylight_saving_time/2-4
• local_abbreviation/2-4 These predicates are intended for local civil times with a unique interpretation. They fail for ambiguous fold times and nonexistent gap times.

  Explicit-resolution predicates:

• local_time_type_with_resolution/3-5
• local_offset_with_resolution/3-5
• local_daylight_saving_time_with_resolution/3-5
• local_abbreviation_with_resolution/3-5 These predicates accept an explicit resolution mode argument. Supported modes are strict, first, second, and all.
• strict: succeed only when the local civil time has a unique interpretation
• first: select the earliest valid interpretation
• second: select the latest valid interpretation
• all: enumerate all valid interpretations in chronological order Reified predicates:
• local_time_type_reified/2-4
• local_offset_reified/2-4
• local_daylight_saving_time_reified/2-4
• local_abbreviation_reified/2-4 These predicates never use failure to distinguish ambiguity from absence. Instead, they return one of the following results:
• unique(...)
• ambiguous(...)
• nonexistent

Examples

Load a single TZif payload without caching it:

::

| ?- tzif::load(bytes(Bytes, 'America/New_York'), TZifs).

Cache an already loaded term explicitly:

::

| ?- tzif::load(bytes(Bytes, 'America/New_York'), TZifs), tzif::cache(TZifs).

Load a directory tree of TZif files:

::

| ?- tzif::load(directory('/usr/share/zoneinfo'), TZifs).

Query a specific zone in a loaded term:

::

| ?- tzif::load(bytes(Bytes, 'America/New_York'), [TZif]). | ?- tzif::offset(TZif, 'America/New_York', date_time(2024, 7, 1, 12, 0, 0), Offset).

Query a specific zone in the cached term:

::

| ?- tzif::load(directory('/usr/share/zoneinfo')). | ?- tzif::offset('America/New_York', date_time(2024, 7, 1, 12, 0, 0), Offset).

Persist and reload a snapshot:

::

| ?- tzif::save(TZifs, 'snapshot.pl'). | ?- tzif::load(snapshot('snapshot.pl'), ReloadedTZifs).

Save the cached terms directly:

::

| ?- tzif::load(directory('/usr/share/zoneinfo')). | ?- tzif::save('snapshot.pl').

Load using a backward-compatible alias:

::

| ?- tzif::load(bytes(Bytes, 'US/Eastern'), TZifs).

Use the automatic cache populated by load/1:

::

| ?- tzif::load(snapshot('snapshot.pl')). | ?- tzif::abbreviation(date_time(2024, 7, 1, 12, 0, 0), Abbreviation).

Resolve an ambiguous local civil time explicitly:

::

| ?- tzif::local_offset_with_resolution('America/New_York', date_time(2024, 11, 3, 1, 30, 0), first, Offset).

Inspect whether a local civil time is unique, ambiguous, or nonexistent:

::

| ?- tzif::local_time_type_reified('America/New_York', date_time(2024, 11, 3, 1, 30, 0), Result).

List cached zones directly:

::

| ?- tzif::load(directory('/usr/share/zoneinfo')). | ?- tzif::zones(Zones).