protocol

# `tzif_protocol`

Protocol for loading TZif data sets, persisting loaded terms, and answering zone-aware UTC-based offset, DST, and abbreviation queries.

Availability:
`logtalk_load(tzif(loader))`
Author: Paulo Moura
Version: 1:0:0
Date: 2026-04-07
Compilation flags:
`static`
Dependencies:
(none)
Remarks:
(none)
Inherited public predicates:
(none)

## Public predicates

### `load/1`

Loads a TZif source given as `file(Path, ZoneId)`, `files(Root, Paths)`, `directory(Root)`, `stream(Stream, ZoneId)`, `bytes(Bytes, ZoneId)`, or `snapshot(File)` and caches the resulting per-zone `tzif(...)` terms, replacing cached entries with matching zone identifiers. For `directory(Root)` sources, regular files whose relative paths are not recognized zone identifiers are ignored, allowing system zoneinfo trees that contain metadata files such as `leapseconds`. Zone identifiers are validated against bundled IANA TZDB 2026a canonical names plus backward-compatible aliases.

Compilation flags:
`static`
Template:
`load(Source)`
Mode and number of proofs:
`load(+compound)` - `zero_or_one`

### `load/2`

Loads a TZif source given as `file(Path, ZoneId)`, `files(Root, Paths)`, `directory(Root)`, `stream(Stream, ZoneId)`, `bytes(Bytes, ZoneId)`, or `snapshot(File)` into a list of per-zone `tzif(...)` compound terms without caching them. For `directory(Root)` sources, regular files whose relative paths are not recognized zone identifiers are ignored, allowing system zoneinfo trees that contain metadata files such as `leapseconds`. Zone identifiers are validated against bundled IANA TZDB 2026a canonical names plus backward-compatible aliases.

Compilation flags:
`static`
Template:
`load(Source,TZifs)`
Mode and number of proofs:
`load(+compound,-list(compound))` - `zero_or_one`

### `cache/1`

Caches one or more loaded per-zone `tzif(...)` compound terms, replacing cached entries with matching zone identifiers.

Compilation flags:
`static`
Template:
`cache(TZifs)`
Mode and number of proofs:
`cache(+list(compound))` - `one`

### `save/2`

Saves a list of per-zone `tzif(...)` terms to a plain Prolog snapshot file, writing one serialized term per line.

Compilation flags:
`static`
Template:
`save(TZifs,File)`
Mode and number of proofs:
`save(+list(compound),+atom)` - `one`

### `save/1`

Saves all cached `tzif(...)` terms to a plain Prolog snapshot file.

Compilation flags:
`static`
Template:
`save(File)`
Mode and number of proofs:
`save(+atom)` - `one_or_error`

### `clear_cache/0`

Clears all cached TZif terms.

Compilation flags:
`static`
Mode and number of proofs:
`clear_cache` - `one`

### `cache_source/1`

Enumerates the source terms recorded in the cached TZif terms.

Compilation flags:
`static`
Template:
`cache_source(Source)`
Mode and number of proofs:
`cache_source(-compound)` - `zero_or_more`

### `cached_tzif/1`

Enumerates the cached per-zone `tzif(...)` terms.

Compilation flags:
`static`
Template:
`cached_tzif(TZif)`
Mode and number of proofs:
`cached_tzif(-compound)` - `zero_or_more`

### `zone/3`

Returns the loaded zone identifier and its nested parsed zone-data term from a per-zone `tzif(...)` term.

Compilation flags:
`static`
Template:
`zone(TZif,Zone,ZoneData)`
Mode and number of proofs:
`zone(+compound,?atom,-compound)` - `zero_or_one`

### `zones/2`

Returns the list of zone identifiers loaded in a list of per-zone `tzif(...)` terms.

Compilation flags:
`static`
Template:
`zones(TZifs,Zones)`
Mode and number of proofs:
`zones(+list(compound),-list(atom))` - `one`

### `zones/1`

Returns the list of zone identifiers loaded in the cached `tzif(...)` terms.

Compilation flags:
`static`
Template:
`zones(Zones)`
Mode and number of proofs:
`zones(-list(atom))` - `one_or_error`

### `time_type/4`

Returns the applicable local time type for a loaded zone and a UTC instant given either as Unix seconds or as a `date_time/6` term.

Compilation flags:
`static`
Template:
`time_type(TZif,Zone,UTC,TimeType)`
Mode and number of proofs:
`time_type(+compound,+atom,+types([integer,compound]),-compound)` - `zero_or_one`

### `time_type/3`

Returns the applicable local time type for a zone in the cached TZif terms.

Compilation flags:
`static`
Template:
`time_type(Zone,UTC,TimeType)`
Mode and number of proofs:
`time_type(+atom,+types([integer,compound]),-compound)` - `one_or_error`

### `time_type/2`

Cached single-zone convenience variant of `time_type/3` using the cached TZif terms; requires exactly one cached zone.

Compilation flags:
`static`
Template:
`time_type(UTC,TimeType)`
Mode and number of proofs:
`time_type(+types([integer,compound]),-compound)` - `one_or_error`

### `offset/4`

Returns the UTC offset in seconds for a loaded zone and a UTC instant.

Compilation flags:
`static`
Template:
`offset(TZif,Zone,UTC,OffsetSeconds)`
Mode and number of proofs:
`offset(+compound,+atom,+types([integer,compound]),-integer)` - `zero_or_one`

### `offset/3`

Returns the UTC offset in seconds for a zone in the cached TZif terms.

Compilation flags:
`static`
Template:
`offset(Zone,UTC,OffsetSeconds)`
Mode and number of proofs:
`offset(+atom,+types([integer,compound]),-integer)` - `one_or_error`

### `offset/2`

Cached single-zone convenience variant of `offset/3` using the cached TZif terms; requires exactly one cached zone.

Compilation flags:
`static`
Template:
`offset(UTC,OffsetSeconds)`
Mode and number of proofs:
`offset(+types([integer,compound]),-integer)` - `one_or_error`

### `daylight_saving_time/4`

Returns `true` or `false` according to whether daylight saving time is active for a loaded zone and a UTC instant.

Compilation flags:
`static`
Template:
`daylight_saving_time(TZif,Zone,UTC,IsDST)`
Mode and number of proofs:
`daylight_saving_time(+compound,+atom,+types([integer,compound]),-atom)` - `zero_or_one`

### `daylight_saving_time/3`

Returns daylight-saving information for a zone in the cached TZif terms.

Compilation flags:
`static`
Template:
`daylight_saving_time(Zone,UTC,IsDST)`
Mode and number of proofs:
`daylight_saving_time(+atom,+types([integer,compound]),-atom)` - `one_or_error`

### `daylight_saving_time/2`

Cached single-zone convenience variant of `daylight_saving_time/3` using the cached TZif terms; requires exactly one cached zone.

Compilation flags:
`static`
Template:
`daylight_saving_time(UTC,IsDST)`
Mode and number of proofs:
`daylight_saving_time(+types([integer,compound]),-atom)` - `one_or_error`

### `abbreviation/4`

Returns the time-zone abbreviation for a loaded zone and a UTC instant.

Compilation flags:
`static`
Template:
`abbreviation(TZif,Zone,UTC,Abbreviation)`
Mode and number of proofs:
`abbreviation(+compound,+atom,+types([integer,compound]),-atom)` - `zero_or_one`

### `abbreviation/3`

Returns the time-zone abbreviation for a zone in the cached TZif terms.

Compilation flags:
`static`
Template:
`abbreviation(Zone,UTC,Abbreviation)`
Mode and number of proofs:
`abbreviation(+atom,+types([integer,compound]),-atom)` - `one_or_error`

### `abbreviation/2`

Cached single-zone convenience variant of `abbreviation/3` using the cached TZif terms; requires exactly one cached zone.

Compilation flags:
`static`
Template:
`abbreviation(UTC,Abbreviation)`
Mode and number of proofs:
`abbreviation(+types([integer,compound]),-atom)` - `one_or_error`

### `local_time_type/4`

Returns the applicable local time type for a loaded zone and a local civil time given as a `date_time/6` term. This strict variant fails unless the local civil time has a unique interpretation.

Compilation flags:
`static`
Template:
`local_time_type(TZif,Zone,LocalDateTime,TimeType)`
Mode and number of proofs:
`local_time_type(+compound,+atom,+compound,-compound)` - `zero_or_one`

### `local_time_type/3`

Returns the applicable local time type for a zone in the cached TZif terms. This strict variant fails unless the local civil time has a unique interpretation.

Compilation flags:
`static`
Template:
`local_time_type(Zone,LocalDateTime,TimeType)`
Mode and number of proofs:
`local_time_type(+atom,+compound,-compound)` - `one_or_error`

### `local_time_type/2`

Cached single-zone convenience variant of strict local civil-time lookup; requires exactly one cached zone and fails unless the local civil time has a unique interpretation.

Compilation flags:
`static`
Template:
`local_time_type(LocalDateTime,TimeType)`
Mode and number of proofs:
`local_time_type(+compound,-compound)` - `one_or_error`

### `local_time_type_with_resolution/5`

Returns the applicable local time type for a loaded zone and a local civil time using the explicit resolution mode: `strict` (fail unless exactly one interpretation exists), `first` (prefer the earliest valid interpretation), `second` (prefer the latest valid interpretation), and `all` (enumerate all valid interpretations in chronological order).

Compilation flags:
`static`
Template:
`local_time_type_with_resolution(TZif,Zone,LocalDateTime,ResolutionMode,TimeType)`
Mode and number of proofs:
`local_time_type_with_resolution(+compound,+atom,+compound,+atom,-compound)` - `zero_or_more`

### `local_time_type_with_resolution/4`

Returns the applicable local time type for a zone in the cached TZif terms using the explicit resolution mode: `strict` (fail unless exactly one interpretation exists), `first` (prefer the earliest valid interpretation), `second` (prefer the latest valid interpretation), and `all` (enumerate all valid interpretations in chronological order).

Compilation flags:
`static`
Template:
`local_time_type_with_resolution(Zone,LocalDateTime,ResolutionMode,TimeType)`
Mode and number of proofs:
`local_time_type_with_resolution(+atom,+compound,+atom,-compound)` - `zero_or_more`

### `local_time_type_with_resolution/3`

Cached single-zone convenience variant of local civil-time lookup using the explicit resolution mode: `strict` (fail unless exactly one interpretation exists), `first` (prefer the earliest valid interpretation), `second` (prefer the latest valid interpretation), and `all` (enumerate all valid interpretations in chronological order). Requires exactly one cached zone.

Compilation flags:
`static`
Template:
`local_time_type_with_resolution(LocalDateTime,ResolutionMode,TimeType)`
Mode and number of proofs:
`local_time_type_with_resolution(+compound,+atom,-compound)` - `zero_or_more`

### `local_offset/4`

Returns the UTC offset in seconds for a loaded zone and a local civil time. This strict variant fails unless the local civil time has a unique interpretation.

Compilation flags:
`static`
Template:
`local_offset(TZif,Zone,LocalDateTime,OffsetSeconds)`
Mode and number of proofs:
`local_offset(+compound,+atom,+compound,-integer)` - `zero_or_one`

### `local_offset/3`

Returns the UTC offset in seconds for a zone in the cached TZif terms. This strict variant fails unless the local civil time has a unique interpretation.

Compilation flags:
`static`
Template:
`local_offset(Zone,LocalDateTime,OffsetSeconds)`
Mode and number of proofs:
`local_offset(+atom,+compound,-integer)` - `one_or_error`

### `local_offset/2`

Cached single-zone convenience variant of strict local civil-time offset lookup.

Compilation flags:
`static`
Template:
`local_offset(LocalDateTime,OffsetSeconds)`
Mode and number of proofs:
`local_offset(+compound,-integer)` - `one_or_error`

### `local_offset_with_resolution/5`

Returns the UTC offset in seconds for a loaded zone and a local civil time using the explicit resolution mode: `strict` (fail unless exactly one interpretation exists), `first` (prefer the earliest valid interpretation), `second` (prefer the latest valid interpretation), and `all` (enumerate all valid interpretations in chronological order).

Compilation flags:
`static`
Template:
`local_offset_with_resolution(TZif,Zone,LocalDateTime,ResolutionMode,OffsetSeconds)`
Mode and number of proofs:
`local_offset_with_resolution(+compound,+atom,+compound,+atom,-integer)` - `zero_or_more`

### `local_offset_with_resolution/4`

Returns the UTC offset in seconds for a zone in the cached TZif terms using the explicit resolution mode: `strict` (fail unless exactly one interpretation exists), `first` (prefer the earliest valid interpretation), `second` (prefer the latest valid interpretation), and `all` (enumerate all valid interpretations in chronological order).

Compilation flags:
`static`
Template:
`local_offset_with_resolution(Zone,LocalDateTime,ResolutionMode,OffsetSeconds)`
Mode and number of proofs:
`local_offset_with_resolution(+atom,+compound,+atom,-integer)` - `zero_or_more`

### `local_offset_with_resolution/3`

Cached single-zone convenience variant of local civil-time offset lookup using the explicit resolution mode; requires exactly one cached zone.

Compilation flags:
`static`
Template:
`local_offset_with_resolution(LocalDateTime,ResolutionMode,OffsetSeconds)`
Mode and number of proofs:
`local_offset_with_resolution(+compound,+atom,-integer)` - `zero_or_more`

### `local_daylight_saving_time/4`

Returns daylight-saving information for a loaded zone and a local civil time. This strict variant fails unless the local civil time has a unique interpretation.

Compilation flags:
`static`
Template:
`local_daylight_saving_time(TZif,Zone,LocalDateTime,IsDST)`
Mode and number of proofs:
`local_daylight_saving_time(+compound,+atom,+compound,-atom)` - `zero_or_one`

### `local_daylight_saving_time/3`

Returns daylight-saving information for a zone in the cached TZif terms. This strict variant fails unless the local civil time has a unique interpretation.

Compilation flags:
`static`
Template:
`local_daylight_saving_time(Zone,LocalDateTime,IsDST)`
Mode and number of proofs:
`local_daylight_saving_time(+atom,+compound,-atom)` - `one_or_error`

### `local_daylight_saving_time/2`

Cached single-zone convenience variant of strict local daylight-saving lookup.

Compilation flags:
`static`
Template:
`local_daylight_saving_time(LocalDateTime,IsDST)`
Mode and number of proofs:
`local_daylight_saving_time(+compound,-atom)` - `one_or_error`

### `local_daylight_saving_time_with_resolution/5`

Returns daylight-saving information for a loaded zone and a local civil time using the explicit resolution mode: `strict` (fail unless exactly one interpretation exists), `first` (prefer the earliest valid interpretation), `second` (prefer the latest valid interpretation), and `all` (enumerate all valid interpretations in chronological order).

Compilation flags:
`static`
Template:
`local_daylight_saving_time_with_resolution(TZif,Zone,LocalDateTime,ResolutionMode,IsDST)`
Mode and number of proofs:
`local_daylight_saving_time_with_resolution(+compound,+atom,+compound,+atom,-atom)` - `zero_or_more`

### `local_daylight_saving_time_with_resolution/4`

Returns daylight-saving information for a zone in the cached TZif terms using the explicit resolution mode: `strict` (fail unless exactly one interpretation exists), `first` (prefer the earliest valid interpretation), `second` (prefer the latest valid interpretation), and `all` (enumerate all valid interpretations in chronological order).

Compilation flags:
`static`
Template:
`local_daylight_saving_time_with_resolution(Zone,LocalDateTime,ResolutionMode,IsDST)`
Mode and number of proofs:
`local_daylight_saving_time_with_resolution(+atom,+compound,+atom,-atom)` - `zero_or_more`

### `local_daylight_saving_time_with_resolution/3`

Cached single-zone convenience variant of local civil-time daylight-saving lookup using the explicit resolution mode; requires exactly one cached zone.

Compilation flags:
`static`
Template:
`local_daylight_saving_time_with_resolution(LocalDateTime,ResolutionMode,IsDST)`
Mode and number of proofs:
`local_daylight_saving_time_with_resolution(+compound,+atom,-atom)` - `zero_or_more`

### `local_abbreviation/4`

Returns the time-zone abbreviation for a loaded zone and a local civil time. This strict variant fails unless the local civil time has a unique interpretation.

Compilation flags:
`static`
Template:
`local_abbreviation(TZif,Zone,LocalDateTime,Abbreviation)`
Mode and number of proofs:
`local_abbreviation(+compound,+atom,+compound,-atom)` - `zero_or_one`

### `local_abbreviation/3`

Returns the time-zone abbreviation for a zone in the cached TZif terms. This strict variant fails unless the local civil time has a unique interpretation.

Compilation flags:
`static`
Template:
`local_abbreviation(Zone,LocalDateTime,Abbreviation)`
Mode and number of proofs:
`local_abbreviation(+atom,+compound,-atom)` - `one_or_error`

### `local_abbreviation/2`

Cached single-zone convenience variant of strict local abbreviation lookup.

Compilation flags:
`static`
Template:
`local_abbreviation(LocalDateTime,Abbreviation)`
Mode and number of proofs:
`local_abbreviation(+compound,-atom)` - `one_or_error`

### `local_abbreviation_with_resolution/5`

Returns the time-zone abbreviation for a loaded zone and a local civil time using the explicit resolution mode: `strict` (fail unless exactly one interpretation exists), `first` (prefer the earliest valid interpretation), `second` (prefer the latest valid interpretation), and `all` (enumerate all valid interpretations in chronological order).

Compilation flags:
`static`
Template:
`local_abbreviation_with_resolution(TZif,Zone,LocalDateTime,ResolutionMode,Abbreviation)`
Mode and number of proofs:
`local_abbreviation_with_resolution(+compound,+atom,+compound,+atom,-atom)` - `zero_or_more`

### `local_abbreviation_with_resolution/4`

Returns the time-zone abbreviation for a zone in the cached TZif terms using the explicit resolution mode: `strict` (fail unless exactly one interpretation exists), `first` (prefer the earliest valid interpretation), `second` (prefer the latest valid interpretation), and `all` (enumerate all valid interpretations in chronological order).

Compilation flags:
`static`
Template:
`local_abbreviation_with_resolution(Zone,LocalDateTime,ResolutionMode,Abbreviation)`
Mode and number of proofs:
`local_abbreviation_with_resolution(+atom,+compound,+atom,-atom)` - `zero_or_more`

### `local_abbreviation_with_resolution/3`

Cached single-zone convenience variant of local civil-time abbreviation lookup using the explicit resolution mode; requires exactly one cached zone.

Compilation flags:
`static`
Template:
`local_abbreviation_with_resolution(LocalDateTime,ResolutionMode,Abbreviation)`
Mode and number of proofs:
`local_abbreviation_with_resolution(+compound,+atom,-atom)` - `zero_or_more`

### `local_time_type_reified/4`

Returns a reified local civil-time lookup result for a loaded zone as one of `unique(TimeType)`, `ambiguous(TimeTypes)`, or `nonexistent`.

Compilation flags:
`static`
Template:
`local_time_type_reified(TZif,Zone,LocalDateTime,Result)`
Mode and number of proofs:
`local_time_type_reified(+compound,+atom,+compound,-compound)` - `one`

### `local_time_type_reified/3`

Returns a reified local civil-time lookup result for a zone in the cached TZif terms as one of `unique(TimeType)`, `ambiguous(TimeTypes)`, or `nonexistent`.

Compilation flags:
`static`
Template:
`local_time_type_reified(Zone,LocalDateTime,Result)`
Mode and number of proofs:
`local_time_type_reified(+atom,+compound,-compound)` - `one_or_error`

### `local_time_type_reified/2`

Cached single-zone convenience variant of reified local civil-time lookup; returns `unique(TimeType)`, `ambiguous(TimeTypes)`, or `nonexistent`.

Compilation flags:
`static`
Template:
`local_time_type_reified(LocalDateTime,Result)`
Mode and number of proofs:
`local_time_type_reified(+compound,-compound)` - `one_or_error`

### `local_offset_reified/4`

Returns a reified local offset lookup result for a loaded zone as one of `unique(OffsetSeconds)`, `ambiguous(OffsetSecondsList)`, or `nonexistent`.

Compilation flags:
`static`
Template:
`local_offset_reified(TZif,Zone,LocalDateTime,Result)`
Mode and number of proofs:
`local_offset_reified(+compound,+atom,+compound,-compound)` - `one`

### `local_offset_reified/3`

Returns a reified local offset lookup result for a zone in the cached TZif terms as one of `unique(OffsetSeconds)`, `ambiguous(OffsetSecondsList)`, or `nonexistent`.

Compilation flags:
`static`
Template:
`local_offset_reified(Zone,LocalDateTime,Result)`
Mode and number of proofs:
`local_offset_reified(+atom,+compound,-compound)` - `one_or_error`

### `local_offset_reified/2`

Cached single-zone convenience variant of reified local offset lookup; returns `unique(OffsetSeconds)`, `ambiguous(OffsetSecondsList)`, or `nonexistent`.

Compilation flags:
`static`
Template:
`local_offset_reified(LocalDateTime,Result)`
Mode and number of proofs:
`local_offset_reified(+compound,-compound)` - `one_or_error`

### `local_daylight_saving_time_reified/4`

Returns a reified local daylight-saving lookup result for a loaded zone as one of `unique(IsDST)`, `ambiguous(IsDSTList)`, or `nonexistent`.

Compilation flags:
`static`
Template:
`local_daylight_saving_time_reified(TZif,Zone,LocalDateTime,Result)`
Mode and number of proofs:
`local_daylight_saving_time_reified(+compound,+atom,+compound,-compound)` - `one`

### `local_daylight_saving_time_reified/3`

Returns a reified local daylight-saving lookup result for a zone in the cached TZif terms as one of `unique(IsDST)`, `ambiguous(IsDSTList)`, or `nonexistent`.

Compilation flags:
`static`
Template:
`local_daylight_saving_time_reified(Zone,LocalDateTime,Result)`
Mode and number of proofs:
`local_daylight_saving_time_reified(+atom,+compound,-compound)` - `one_or_error`

### `local_daylight_saving_time_reified/2`

Cached single-zone convenience variant of reified local daylight-saving lookup; returns `unique(IsDST)`, `ambiguous(IsDSTList)`, or `nonexistent`.

Compilation flags:
`static`
Template:
`local_daylight_saving_time_reified(LocalDateTime,Result)`
Mode and number of proofs:
`local_daylight_saving_time_reified(+compound,-compound)` - `one_or_error`

### `local_abbreviation_reified/4`

Returns a reified local abbreviation lookup result for a loaded zone as one of `unique(Abbreviation)`, `ambiguous(Abbreviations)`, or `nonexistent`.

Compilation flags:
`static`
Template:
`local_abbreviation_reified(TZif,Zone,LocalDateTime,Result)`
Mode and number of proofs:
`local_abbreviation_reified(+compound,+atom,+compound,-compound)` - `one`

### `local_abbreviation_reified/3`

Returns a reified local abbreviation lookup result for a zone in the cached TZif terms as one of `unique(Abbreviation)`, `ambiguous(Abbreviations)`, or `nonexistent`.

Compilation flags:
`static`
Template:
`local_abbreviation_reified(Zone,LocalDateTime,Result)`
Mode and number of proofs:
`local_abbreviation_reified(+atom,+compound,-compound)` - `one_or_error`

### `local_abbreviation_reified/2`

Cached single-zone convenience variant of reified local abbreviation lookup; returns `unique(Abbreviation)`, `ambiguous(Abbreviations)`, or `nonexistent`.

Compilation flags:
`static`
Template:
`local_abbreviation_reified(LocalDateTime,Result)`
Mode and number of proofs:
`local_abbreviation_reified(+compound,-compound)` - `one_or_error`

## Protected predicates

(none)

## Private predicates

(none)

## Operators

(none)