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)

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

tzif_protocol

`tzif_protocol`