tempo/time_zone

Functions to provide time zone support for datetimes.

A tempo.TimeZoneProvider value is constructed with these functions, and then handed to functions like datetime.to_timezone to convert datetimes between zones. Note that the datetime conversion does not store the time zone data in the datetime value itself, so after converting a datetime, adding or subtracting time from it may invalidate its correctness in the converted time zone.

On the Erlang target running on macOS and other Unix systems, the operating system’s TZif database is read from /usr/share/zoneinfo via the tzif package. It is parsed once on first use and then memoized in a persistent term. A host with no readable database there has no valid zones, so new returns an error for every name. In this case, use the from_database function to supply your own tzif.TzDatabase database instead.

On the JavaScript target the runtime’s native Intl API answers both which zone names are valid and what offset a zone was at, so any zone the JavaScript engine knows about is available with no filesystem access. You can also provide your own tzif.TzDatabase database to from_database to supply your own zone data to the JavaScript runtime if you would like.

Values

from_database

</>

pub fn from_database(
  db: database.TzDatabase,
  name: String,
) -> Result(tempo.TimeZoneProvider, Nil)

Constructs a TimeZoneProvider backed by a supplied TZif database. Returns an error if db does not contain name.

This is useful for loading a database from a non-standard host location.

Examples

import tempo/datetime
import tempo/time_zone
import tzif/database

// Provided by the host at a non-standard location
let assert Ok(db) = database.load_from_path("/custom/path/to/zoneinfo")
let assert Ok(tz) = time_zone.from_database(db, "America/New_York")

datetime.literal("2024-06-21T06:30:02.334Z")
|> datetime.to_timezone(tz)
|> datetime.to_string
// -> "2024-06-21T02:30:02.334000-04:00"

import tempo/datetime
import tempo/time_zone
import zones

// Self-provided tzif database from the `zones` package
let db = zones.database()
let assert Ok(tz) = time_zone.from_database(db, "America/New_York")

datetime.literal("2024-06-21T06:30:02.334Z")
|> datetime.to_timezone(tz)
|> datetime.to_string
// -> "2024-06-21T02:30:02.334000-04:00"

local_name

</>

pub fn local_name() -> String

Returns the name of the host system’s time zone.

Examples

time_zone.local_name()
// -> "Europe/London"

On the Erlang target the zone is read from the operating system, in order: the TZ environment variable, the symlink target of /etc/localtime, then /etc/timezone or /etc/sysconfig/clock. If none of those yield an IANA zone name, "UTC" is returned. On JavaScript the host’s Intl API is used.

new

</>

pub fn new(name: String) -> Result(tempo.TimeZoneProvider, Nil)

Constructs a TimeZoneProvider type to be used with the rest of this package. Returns an error if the time zone is not valid.

Which names are valid, and the offsets they resolve to, come from the host: the operating system’s TZif database in /usr/share/zoneinfo on Erlang (macOS and other Unix systems), and the native Intl API on JavaScript.

Examples

import tempo/datetime
import tempo/time_zone

let assert Ok(tz) = time_zone.new("America/New_York")

datetime.literal("2024-06-21T06:30:02.334Z")
|> datetime.to_timezone(tz)
|> datetime.to_string
// -> "2024-01-03T02:30:02.334-04:00"