tzif/database

These types and functions are designed to let you retrieve information from TZif formatted data you provide, or timezone data loaded from the operating system.

Types

TzDatabase

opaque </>

Time Zone Database record. This is typically created by loading from the operating system with the load_from_os function. This record stores all the data required to get time zone information using the functions in this package.

pub opaque type TzDatabase

TzDatabaseError

</>

TzDatabase error types

pub type TzDatabaseError {
  ZoneNameNotFound
  InfoNotFound
}

Constructors

```
ZoneNameNotFound
```
The zone was not found in the database
```
InfoNotFound
```
Information, including UTC offset, zone designation, or leap second information was not found for this time zone.

ZoneParameters

</>

Time zone parameters record.

offset is the offset from UTC using gleam_time Duration.
is_dst indicates if it is daylight savings time
designation is the time zone designation

pub type ZoneParameters {
  ZoneParameters(
    offset: duration.Duration,
    is_dst: Bool,
    designation: String,
  )
}

Constructors

ZoneParameters(
  offset: duration.Duration,
  is_dst: Bool,
  designation: String,
)

Values

add_tzfile

</>

pub fn add_tzfile(
  db: TzDatabase,
  zone_name: String,
  tzfile: parser.TzFile,
) -> TzDatabase

Add new time zone definition to TzDatabase. This can add TZif data which has been parsed and loaded into a parser.TzFile record. Each zone must be given a zone_name which can be used to retrieve that time zone’s data.

get_available_timezones

</>

pub fn get_available_timezones(db: TzDatabase) -> List(String)

Get all list of all time zone names within the time zone database.

get_zone_parameters

</>

pub fn get_zone_parameters(
  ts: timestamp.Timestamp,
  zone_name: String,
  db: TzDatabase,
) -> Result(ZoneParameters, TzDatabaseError)

Retrieve the time zone parameters for a zone at a particular time. The time is given as a gleam/time/timestamp.Timestamp, the zone name and a time zone database. Because of daylight savings time as well as other historical shifts in how time has been measured, time zone information for a location shifts over time, therefore the offset or designation you get from the database is time dependant. Do not assume that the time zone parameters will be the same at any other time.

Example

import gleam/time/timestamp

let ts = timestamp.from_unix_seconds(1_758_223_300)
let assert Ok(db) = database.load_from_os()

get_zone_parameters(ts, "America/New_York", db)
// Ok(ZoneParameters(
//   Duration(-144_40, 0),
//   True,
//   "EDT",
// ))

has_leap_second_data

</>

pub fn has_leap_second_data(
  zone_name: String,
  db: TzDatabase,
) -> Result(Bool, TzDatabaseError)

Check if a time zone within the database has leap second data. For some reason not all time zone files seem to have leap second data. The “right/UTC” zone generally does have leap second information, but is not always available.

leap_seconds

</>

pub fn leap_seconds(
  ts: timestamp.Timestamp,
  zone_name: String,
  db: TzDatabase,
) -> Result(Int, TzDatabaseError)

Find the number of leap seconds at a given Timestamp ts using the given time zone. Not all time zones have leap second data, and if there is no data present, this function will return Error(InfoNotFound). Typically the “right/UTC” time zone will have leap second data.

load_from_os

</>

pub fn load_from_os() -> Result(TzDatabase, Nil)

Load time zone database from default operating system location which is typically “/usr/share/zoneinfo”. If no parsable TZif files were found, returns Error(Nil).

load_from_path

</>

pub fn load_from_path(path: String) -> Result(TzDatabase, Nil)

Load time zone database from provided directory. This is useful if you have compiled your own version of the IANA time zone database or they are not stored in the standard location. If no parsable TZif files were found, returns Error(Nil).

new

</>

pub fn new() -> TzDatabase

Create new empty TzDatabase. This can be useful if you will be loading TZif files using a different method, for example over the internet, and wish to load them up into a TzDatabase record.