README.md

tzif

Time zone support for Gleam time using the IANA Time Zone Database format. This package includes a parser for the Time Zone Information Format (TZif) or tzfile format, as well as utility functions to convert a timestamp from the gleam_time library into a date and time of day in the given time zone.

There are two ways to obtain the timezone data:

• The zones package maintains up to date time zone data in a native gleam package format. This is the recommended method for code running in the browser, docker containers, and the Windows operating system.

  Add to your project with the command:

  gleam add tzif@2 zones
  

• The tzif_loader package will load the operating system default time zone files from their standard location in Linux and MacOS operating systems.

  Add to your project with the command:

  gleam add tzif@2 tzif_loader
  

We could really do with a timezone database package with a fn(Timestamp, Zone) -> #(Date, TimeOfDay) function

--- Louis Pilfold

Using the Package

There are three modules in the tzif package:

• tzif/database has utilities for managing the IANA Time Zone database.
• tzif/tzcalendar has utilities for converting a gleam_time timestamp into date and time of day in a time zone.
• tzif/parser has functions and records for parsing TZif formatted data.

Below is an example of code which loads the native time zone data from the operating system using tzif_loader and converts the system time to a time of day in the America/New_York time zone.

import gleam/int
import gleam/io
import gleam/string
import gleam/time/timestamp
import tzif/database
import tzif/loader
import tzif/tzcalendar

pub fn main() {
    let now = timestamp.system_time()

    // Load the database from the operating system
    case loader.load_from_os() {
        Ok(db) -> {
            case tzcalendar.to_time_and_zone(now, "America/New_York", db) {
                Ok(time_and_zone) -> {
                    // Successfully converted time to the requested time zone
                    io.println(
                        int.to_string(time_and_zone.time_of_day.hours)
                        |> string.pad_start(2, "0")
                        <> ":"
                        <> int.to_string(time_and_zone.time_of_day.minutes)
                        |> string.pad_start(2, "0")
                        <> ":"
                        <> int.to_string(time_and_zone.time_of_day.seconds)
                        |> string.pad_start(2, "0")
                        <> " "
                        <> time_and_zone.designation
                    )
                }
                Error(database.ZoneNotFound) -> io.println("Time zone not found")
                Error(database.ProcessingError) ->
                    io.println("Error processing time zone conversion")
            }
        }
        Error(Nil) -> io.println("No parsable TZif files found.")
}