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
TZDIRnames, then/usr/share/zoneinfoand the other usual places. The local zone is the variableTZ, 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-zonegives, which the host reads fromIntl.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
OsTimeZonesfails with the reasonUnknownZone, except forUTCand fixed offsets, which need no data.PreferSystemTimeZonesstill 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.
OsLocalZonecan return aTZvalue that is a POSIX rule, such asEST5EDT,M3.2.0,M11.1.0, and not a zone name. On Linux and macOS,OsTimeZonesgives the zone for such a rule too.A program that names
OsTimeZoneson Windows or WebAssembly, orPreferSystemTimeZoneson any target, holds the database, about 60 KB.
Examples#
Show an instant in the zone of this machine#
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#
pub struct OsTimeZonesThe 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 forUTCand fixed offsets.
Implementation OsTimeZones#
impl OsTimeZonesAssociated function make#
pub fn make() -> OsTimeZonesReturns a provider. It does not read any file.
Implementation TimeZones for OsTimeZones#
impl TimeZones for OsTimeZonesOperation zoneBytes#
zoneBytes: OsTimeZones.zoneBytesOperation names#
names: OsTimeZones.namesOperation version#
version: OsTimeZones.versionOsLocalZone#
pub struct OsLocalZoneThe 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#
impl OsLocalZoneAssociated function make#
pub fn make() -> OsLocalZoneReturns a provider. It does not read the setting.
Implementation LocalZone for OsLocalZone#
impl LocalZone for OsLocalZoneOperation name#
name: OsLocalZone.namePreferSystemTimeZones#
pub struct PreferSystemTimeZonesA 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#
impl PreferSystemTimeZonesAssociated function make#
pub fn make() -> PreferSystemTimeZonesReturns a provider. It does no work until the first lookup.
Implementation TimeZones for PreferSystemTimeZones#
impl TimeZones for PreferSystemTimeZonesOperation zoneBytes#
zoneBytes: PreferSystemTimeZones.zoneBytesOperation names#
names: PreferSystemTimeZones.namesOperation version#
version: PreferSystemTimeZones.versionCategory: Time.
Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, x86_64-unknown-linux-gnu.