tzif/tzcalendar

This module is for working with time zones and converting timestamps from the gleam/time library into dates and times of day in a time zone.

This library makes use of the IANA tz database which is generally already installed on computers. This library will search for timezone data in the TZif or tzfile file format. These are generally located in the /usr/share/zoneinfo directory on posix systems, however if they are installed elsewhere the then they can be loaded ysung the full path of the directory containing the tz database files.

Time zone identifiers are generally of the form “Continent/City” for example America/New_York, Europe/Amsterdam, or Asia/Tokyo. A list of time zone identifiers is in the list of tz database time zones article on Wikipedia. The time zone identifiers are passed to many of the functions of this library as the zone_name parameter.

Types

TimeAndZone

</>

Representation of a date and time of day in a particular time zone along with the offset from UTC, the zone designation (i.e. “UTC”, “EST”, “CEDT”) and a boolean indicating if it is daylight savings time.

pub type TimeAndZone {
  TimeAndZone(
    date: calendar.Date,
    time_of_day: calendar.TimeOfDay,
    offset: duration.Duration,
    designation: String,
    is_dst: Bool,
  )
}

Constructors

TimeAndZone(
  date: calendar.Date,
  time_of_day: calendar.TimeOfDay,
  offset: duration.Duration,
  designation: String,
  is_dst: Bool,
)

Values

to_calendar

</>

pub fn to_calendar(
  ts: timestamp.Timestamp,
  zone_name: String,
  db: database.TzDatabase,
) -> Result(
  #(calendar.Date, calendar.TimeOfDay),
  database.TzDatabaseError,
)

Given a timestamp, IANA time zone name, and a TzDatabase record, get the date and time of day as a tuple in the format of the gleam/time/timestamp.to_calendar function.

Example

import gleam/time/timestamp
import tzif/database

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

to_calendar(ts, "America/New_York", db)
// Ok(#(
//   Date(2025, September, 18),
//   TimeOfDay(15, 21, 40, 0),
// ))

to_time_and_zone

</>

pub fn to_time_and_zone(
  ts: timestamp.Timestamp,
  zone_name: String,
  db: database.TzDatabase,
) -> Result(TimeAndZone, database.TzDatabaseError)

Given a timestamp, IANA time zone name, and a TzDatabase record, get the date and time of the timestamp along with information about the timezone, such as its offset from UTC, designation, and if it is daylight savings time in that zone.

Example

import gleam/time/timestamp
import tzif/database

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

to_time_and_zone(ts, "America/New_York", db)
// Ok(TimeInZone(
//   Date(2025, September, 18),
//   TimeOfDay(15, 21, 40, 0),
//   Duration(-14_400, 0),
//   "EDT",
//   True,
// ))