tzif - v1.1.2

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

Values

atomic_difference

</> 
pub fn atomic_difference(
  left: timestamp.Timestamp,
  right: timestamp.Timestamp,
  zone_name: String,
  db: database.TzDatabase,
) -> Result(duration.Duration, database.TzDatabaseError)

The actual difference between two timestamps. This includes intervening leap seconds into the calculation. A time zone which includes leap seconds should be given for the zone name. We recommend using “right/UTC” if it is installed on your system.

from_calendar

</> 
pub fn from_calendar(
  date: calendar.Date,
  time: calendar.TimeOfDay,
  zone_name: String,
  db: database.TzDatabase,
) -> Result(List(timestamp.Timestamp), database.TzDatabaseError)

Create a list of timestamps from a calendar date and time. This may produce zero, one or two timestamps in a list depending on if that time is possible in the given time zone or if it is ambiguous. This tends to happen every daylight saving period. When moving forward one hour, the calendar times during the skipped hour are not possible, so no timestamp values would be returned. When moving back one hour the overlap period is repeated, yielding two timestamps per wall clock time.

This returns a TzDatabaseError if there is an issue finding time zone information.

Example

import gleam/time/calendar
import tzif/database

let assert Ok(db) = database.load_from_os()

from_calendar(
  calendar.Date(2025, calendar.November, 2),
  calendar.TimeOfDay(1, 30, 0, 0),
  "America/New_York",
  db,
)
// Ok([Timestamp(1762061400, 0), Timestamp(1762065000, 0)])

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(TimeAndZone(
//   Date(2025, September, 18),
//   TimeOfDay(15, 21, 40, 0),
//   Duration(-14_400, 0),
//   "EDT",
//   True,
// ))
✨ Search Document