tzif - v1.0.0

tzif

Package Version Hex Docs

Time zone support for Gleam time using the IANA Time Zone Database. This package loads the time zone database from the standard location (/usr/share/zoneinfo) on MacOS and Linux computers. It 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.

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

— Louis Pilfold

Add to your project with the command:

gleam add tzif@1

Using the Package

There are three modules in the tzif package:

The most straightforward use would be to load the database from the default location on the operating system, and then obtain a timestamp using the gleam_time package, and convert that timestamp into a time of day in a time zone using the IANA time zone name. An example of that is shown in the code below.

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

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

    // Load the database from the operating system
    case database.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.")
}

If you are on windows and have installed the IANA Time Zone Database, or want to use a custom version you can use the database.load_from_path function instead of the database.load_from_os function to specify a path to your database files.

Installing the zoneinfo data files

Time zone information is frequently updated, therefore it makes sense to use the package manager for your operating system to keep the time zone database up to date. All common unix variants have time zone database packages and install the time zone database files into the /usr/share/zoneinfo directory by default.

MacOS

The files should be included in your operating system by default. Check the /usr/share/zoneinfo directory and see if they are present.

Ubuntu/Debian Linux Systems

The APT package manager can be used to install the compiled TZif files with the following command:

sudo apt install tzdata

Debian based docker containers

Installing and configuring the time zone database on a Debian or Ubuntu based docker container can be done by adding the following to your Dockerfile:

# Use an ARG for the timezone, with a default of UTC
ARG TIMEZONE=Etc/UTC

# Set the TZ environment variable and install tzdata
RUN apt-get update && \
    export DEBIAN_FRONTEND=noninteractive && \
    ln -fs /usr/share/zoneinfo/${TIMEZONE} /etc/localtime && \
    apt-get install -y tzdata && \
    dpkg-reconfigure --frontend noninteractive tzdata

Alpine Linux Systems

The Alpine Package Keeper can install the time zone database using the command:

sudo apk add tzdata

Alpine based docker containers

Installing and configuring the time zone database on an Alpine based docker container can be done by adding the following to your Dockerfile:

# Use an ARG for the timezone, with a default of UTC
ARG TIMEZONE=Etc/UTC

# 1. Install the tzdata package
# 2. Copy the correct timezone file to /etc/localtime
# 3. Set the TZ environment variable to be used by applications
RUN apk add --no-cache tzdata && \
    cp /usr/share/zoneinfo/${TIMEZONE} /etc/localtime && \
    echo "${TIMEZONE}" > /etc/timezone

Red Hat/Rocky/Alma Linux Systems

You can use the YUM package manager or DNF to install the time zone database on Red Hat variants. To use YUM run the command:

sudo yum install tzdata

Similarly, using DNF:

sudo dnf install tzdata

Windows

Microsoft Windows has a different mechanism for handling time zones, however you can install the IANA Time Zone Database by downloading the latest version and compiling the zone files using the directions in the repository.

✨ Search Document