silk.time.zones_native.

The system providers of the TimeZones and LocalZone effects: the time zone database and the zone setting of the operating system.

When to use#

Provide OsTimeZones for TimeZones and OsLocalZone for LocalZone in a program that shows local times. In a test, provide FixedTimeZones and FixedLocalZone of silk.time.zones, so the result does not depend on the machine.

Details#

Each operating system has its own implementation behind these two providers, and a program names no path and no system call.

  • Linux and macOS: the zones are the TZif files of the system, in the directory that the variable TZDIR names, then /usr/share/zoneinfo and the other usual places. The local zone is the variable TZ, then the link /etc/localtime, then the file /etc/timezone. A zone is read from its file at each lookup.

  • Windows: the system has no IANA zone files, so the zones are the database inside the program, BundledTimeZones. The local zone is the zone setting of Windows, mapped to its IANA name by the table of the Unicode CLDR project.

  • WASI: the zones are the database inside the program, and the local zone is the variable TZ.

  • Browsers and other JavaScript hosts: the zones are the database inside the program, and the local zone is the one that the host import silk#time-zone gives, which the host reads from Intl.DateTimeFormat.

PreferSystemTimeZones reads the system first and the database inside the program for a zone that the system does not have. Load a zone one time and keep it.

Gotchas#

  • A minimal Linux container image often has no zone files. Then each lookup of OsTimeZones fails with the reason UnknownZone, except for UTC and fixed offsets, which need no data. PreferSystemTimeZones still finds the zone.

  • The zones of the system change when the operating system updates its database, so two machines can disagree about a future date.

  • OsLocalZone can return a TZ value that is a POSIX rule, such as EST5EDT,M3.2.0,M11.1.0, and not a zone name. On Linux and macOS, OsTimeZones gives the zone for such a rule too.

  • A program that names OsTimeZones on Windows or WebAssembly, or PreferSystemTimeZones on any target, holds the database, about 60 KB.

Examples#

Show an instant in the zone of this machine#

silk
import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.collections.bytes { Bytes }
import silk.core.effect { Effect }
import silk.time.instant { Instant }
import silk.time.zoned { ZonedDateTime }
import silk.time.zones { LocalZone, NoLocalZoneError, TimeZones, ZoneLookupError }
import silk.time.zones_native { OsLocalZone, OsTimeZones }

effect fn localYear(at: Instant) -> i32
  ! ZoneLookupError | NoLocalZoneError | OutOfMemoryError
  ? &mut TimeZones | &mut LocalZone | &mut Allocator {
  let name = run LocalZone.name()
  let zone = run TimeZones.zoneBytes(Bytes.asSlice(&name))
  return ZonedDateTime.make(at, &zone).date().year()
}

// A machine without a zone setting or without zone files is not an error of this example.
effect fn missing(error: ZoneLookupError | NoLocalZoneError | OutOfMemoryError) -> i32 {
  return 2026
}

pub effect fn main() -> i32 {
  let mut allocator = Allocator.systemAllocatorProvider()
  let mut zones = OsTimeZones.make()
  let mut here = OsLocalZone.make()
  let year = run Effect.catchAll(localYear(Instant.fromUnixSeconds(1795109782)), missing)
    |> Effect.provideMut<TimeZones>(&mut zones)
    |> Effect.provideMut<LocalZone>(&mut here)
    |> Effect.provideMut<Allocator>(&mut allocator)
  if year != 2026 {
    return 1
  }
  return 0
}

Import as OsTimeZones with import silk.time.zones_native { OsTimeZones }.

Public declarations: 3.

OsTimeZones#

silk
pub struct OsTimeZones

The system TimeZones provider: the time zone database of the operating system. It has no state.

Gotchas#

  • A machine without zone files fails each lookup with the reason UnknownZone, except for UTC and fixed offsets.

Implementation OsTimeZones#

silk
impl OsTimeZones

Associated function make#

silk
pub fn make() -> OsTimeZones

Returns a provider. It does not read any file.

Implementation TimeZones for OsTimeZones#

silk
impl TimeZones for OsTimeZones

Operation zoneBytes#

silk
zoneBytes: OsTimeZones.zoneBytes

Operation names#

silk
names: OsTimeZones.names

Operation version#

silk
version: OsTimeZones.version

OsLocalZone#

silk
pub struct OsLocalZone

The system LocalZone provider: the zone that this machine is set to. It has no state.

Gotchas#

  • The answer can be a POSIX rule from the variable TZ, not a zone name.

Implementation OsLocalZone#

silk
impl OsLocalZone

Associated function make#

silk
pub fn make() -> OsLocalZone

Returns a provider. It does not read the setting.

Implementation LocalZone for OsLocalZone#

silk
impl LocalZone for OsLocalZone

Operation name#

silk
name: OsLocalZone.name

PreferSystemTimeZones#

silk
pub struct PreferSystemTimeZones

A TimeZones provider that asks the operating system first and uses the zones inside the program for what the system does not have.

When to use#

It is the provider for a program that must work on every machine: it follows the zone updates of the operating system where there are zone files, and it still knows every zone in a container without them.

Details#

A lookup asks OsTimeZones. If that fails for a reason other than an invalid name, the lookup asks BundledTimeZones. TimeZones.names and TimeZones.version are the ones of the system, or the ones of the bundle if the system has no list or no version.

Gotchas#

  • The program always holds the bundle, about 60 KB.

  • Two zones of one program can come from two releases of the database: one from the system and one from the bundle.

Implementation PreferSystemTimeZones#

silk
impl PreferSystemTimeZones

Associated function make#

silk
pub fn make() -> PreferSystemTimeZones

Returns a provider. It does no work until the first lookup.

Implementation TimeZones for PreferSystemTimeZones#

silk
impl TimeZones for PreferSystemTimeZones

Operation zoneBytes#

silk
zoneBytes: PreferSystemTimeZones.zoneBytes

Operation names#

silk
names: PreferSystemTimeZones.names

Operation version#

silk
version: PreferSystemTimeZones.version

Category: Time.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, x86_64-unknown-linux-gnu.

View the source of this page