silk.time.zones.
Where time zones come from: the TimeZones effect, which gives a Zone for a name, and the
LocalZone effect, which names the zone of this machine.
When to use#
Require &mut TimeZones in code that needs the rules of a named zone, such as
America/Sao_Paulo. Require &mut LocalZone in code that needs to know which zone the
machine is set to. A program provides both with silk.time.zones_native, which has one
implementation for each operating system. A test provides FixedTimeZones and
FixedLocalZone, so its result does not depend on the machine.
Details#
The two effects are separate because they come from different places. On some systems the name of the local zone comes from the operating system, and the rules of all zones come from data inside the program.
TimeZones.zone returns an owned Zone. Load a zone one time and keep it; a
ZonedDateTime of silk.time.zoned borrows it. Every provider gives the zone UTC and
fixed offsets such as +05:30 without any data.
There is no default zone. Code that wants the local time shows &mut LocalZone in its
signature.
Errors#
ZoneLookupErrorfromTimeZones, with a reason: the zone is not known, the name is not valid, or the data cannot be read or is damaged.NoLocalZoneErrorfromLocalZoneif the machine does not say which zone it is in. The caller decides what to use then; no provider answersUTCin silence.
Examples#
Provide fixed zones in a test#
import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.collections.bytes { Bytes }
import silk.core.effect { Effect }
import silk.time.instant { Instant }
import silk.time.zone { ZoneDataError }
import silk.time.zoned { ZonedDateTime }
import silk.time.zones { FixedLocalZone, FixedTimeZones, LocalZone, NoLocalZoneError, TimeZones, ZoneLookupError }
// The hour that the local clock shows at `at`.
effect fn localHour(at: Instant) -> u8
! 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).time().hour()
}
effect fn check() -> i32
! ZoneDataError | ZoneLookupError | NoLocalZoneError | OutOfMemoryError
? &mut Allocator {
let mut zones = FixedTimeZones.make()
run zones.addPosixRule("Europe/Rome", "CET-1CEST,M3.5.0,M10.5.0/3")
let mut here = run FixedLocalZone.make("Europe/Rome")
let hour = run localHour(Instant.fromUnixSeconds(1795109782))
|> Effect.provideMut<TimeZones>(&mut zones)
|> Effect.provideMut<LocalZone>(&mut here)
if hour != 18 {
return 1
}
return 0
}
effect fn failed(error: ZoneDataError | ZoneLookupError | NoLocalZoneError | OutOfMemoryError) -> i32 {
return 2
}
pub effect fn main() -> i32 {
let mut allocator = Allocator.systemAllocatorProvider()
return run Effect.catchAll(check(), failed) |> Effect.provideMut<Allocator>(&mut allocator)
}Import as TimeZones with import silk.time.zones { TimeZones }.
Public declarations: 8.
ZoneLookupReason#
pub enum ZoneLookupReasonThe cause of a ZoneLookupError.
UnknownZone#
UnknownZoneThe provider has no zone with that name.
InvalidName#
InvalidNameThe name cannot be a zone name: it is empty or too long, or it has a character other than
ASCII letters, digits, /, _, -, +, and ., or a part that is empty, ., or ...
Unreadable#
UnreadableThe provider could not read its data.
InvalidData#
InvalidDataThe data of the zone is damaged.
Implementation Debug for ZoneLookupReason#
impl Debug for ZoneLookupReasonOperation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterZoneLookupError#
pub struct ZoneLookupErrorThe error of the TimeZones effect: why the provider cannot answer.
Field reason#
pub reason: ZoneLookupReasonThe cause.
Implementation Copy for ZoneLookupError#
impl Copy for ZoneLookupErrorImplementation Debug for ZoneLookupError#
impl Debug for ZoneLookupErrorOperation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterNoLocalZoneError#
pub struct NoLocalZoneErrorThe error of the LocalZone effect: the machine does not say which zone it is in.
Implementation Copy for NoLocalZoneError#
impl Copy for NoLocalZoneErrorImplementation Debug for NoLocalZoneError#
impl Debug for NoLocalZoneErrorOperation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterTimeZones#
pub service TimeZonesThe effect that gives the rules of a time zone for its name.
Details#
A name is an identifier of the IANA time zone database, such as America/Sao_Paulo. Names
are compared without letter case, and a link such as Asia/Calcutta is accepted. The zone
has the name as the provider spells it, so america/sao_paulo gives a zone named
America/Sao_Paulo, and a link keeps its own name. UTC and an offset such as +05:30 or
-03 give a zone with that fixed offset from every provider.
A provider is the choice of where the rules come from: the files of the operating system
(OsTimeZones of silk.time.zones_native), or zones that the program supplies
(FixedTimeZones).
Operation zoneBytes#
effect fn zoneBytes(
name: &[u8]
) -> Zone ! ZoneLookupError | OutOfMemoryError ? &mut TimeZones | &mut AllocatorReturns the zone named by the bytes name.
Errors#
ZoneLookupErrorwith the reasonUnknownZoneif the provider has no such zone,InvalidNameifnamecannot be a zone name,Unreadableif the provider cannot read its data, orInvalidDataif the data of the zone is damaged.OutOfMemoryErrorif theAllocatorcannot supply the zone.
Operation names#
effect fn names() -> List<Bytes> ! ZoneLookupError | OutOfMemoryError ? &mut TimeZones | &mut AllocatorReturns copies of the names of all zones of the provider, sorted by their bytes. UTC and
the fixed offsets are not in the list.
Errors#
ZoneLookupErrorwith the reasonUnreadableif the provider cannot list its zones.OutOfMemoryErrorif theAllocatorcannot supply the copies.
Operation version#
effect fn version() -> Bytes ! OutOfMemoryError ? &mut TimeZones | &mut AllocatorReturns the version of the time zone database that the provider uses, such as 2026b, or
empty bytes if the provider does not know it.
Errors#
OutOfMemoryErrorif theAllocatorcannot supply the copy.
Implementation TimeZones#
impl TimeZonesAssociated function zone#
pub effect fn zone(
name: string
) -> Zone ! ZoneLookupError | OutOfMemoryError ? &mut TimeZones | &mut AllocatorReturns the zone named name, such as America/Sao_Paulo.
Errors#
ZoneLookupErrorandOutOfMemoryError, as forTimeZones.zoneBytes.
Associated function fixedZone#
pub fn fixedZone(name: &[u8]) -> Option<Zone>Returns the zone for a name that needs no data: UTC in any letter case, or an offset
such as +05:30, -0300, or +01. Returns None for other names. Providers call it
first.
Associated function isValidName#
pub fn isValidName(name: &[u8]) -> boolReturns true if name has the form of a zone name: 1 to 255 bytes of ASCII letters,
digits, /, _, -, +, and ., in parts separated by /, where no part is empty, .,
or ...
When to use#
A provider that turns a name into a file path calls it first, so that a name cannot leave the directory of the zones.
Associated function sameName#
pub fn sameName(left: &[u8], right: &[u8]) -> boolReturns true if left and right are the same zone name, without letter case.
Associated function lookupFailure#
pub fn lookupFailure(reason: ZoneLookupReason) -> ZoneLookupErrorReturns a ZoneLookupError with the reason reason. Providers use it.
LocalZone#
pub service LocalZoneThe effect that names the time zone of this machine.
Details#
The answer is a zone name to give to TimeZones.zoneBytes, such as America/Sao_Paulo. It
is read at each call, so a program sees a change of the setting.
Operation name#
effect fn name() -> Bytes ! NoLocalZoneError | OutOfMemoryError ? &mut LocalZone | &mut AllocatorReturns a copy of the name of the zone that this machine is set to.
Errors#
NoLocalZoneErrorif the machine does not say which zone it is in.OutOfMemoryErrorif theAllocatorcannot supply the copy.
Implementation LocalZone#
impl LocalZoneAssociated function unknown#
pub fn unknown() -> NoLocalZoneErrorReturns a NoLocalZoneError. Providers use it.
FixedTimeZones#
pub struct FixedTimeZonesA TimeZones provider with the zones that the program gives it, for tests and for programs
that carry their own zone data.
Details#
Add each zone with FixedTimeZones.addTzif or FixedTimeZones.addPosixRule. The
provider keeps a copy of the data and makes the zone at each lookup. A name that is added
again replaces the earlier one.
Implementation FixedTimeZones#
impl FixedTimeZonesAssociated function make#
pub fn make() -> FixedTimeZonesReturns a provider with no zones. It does not allocate.
Method setVersion#
pub effect fn setVersion(self: &mut Self, version: string) -> () ! OutOfMemoryError ? &mut AllocatorSets the database version that TimeZones.version returns, such as 2026b.
Errors#
OutOfMemoryErrorif theAllocatorcannot supply the copy.
Method addTzif#
pub effect fn addTzif(self: &mut Self, name: string, data: &[u8]) -> ()
! ZoneDataError | OutOfMemoryError
? &mut AllocatorAdds the zone name with the bytes of a TZif file, the format of the files under
/usr/share/zoneinfo.
Errors#
ZoneDataErrorifdatais not a valid TZif file.OutOfMemoryErrorif theAllocatorcannot supply the copy.
Method addPosixRule#
pub effect fn addPosixRule(self: &mut Self, name: string, rule: string) -> ()
! ZoneDataError | OutOfMemoryError
? &mut AllocatorAdds the zone name with a POSIX TZ rule such as CET-1CEST,M3.5.0,M10.5.0/3. See
Zone.fromPosixRule for the form of a rule.
Errors#
ZoneDataErrorifruleis not a valid rule.OutOfMemoryErrorif theAllocatorcannot supply the copy.
Implementation TimeZones for FixedTimeZones#
impl TimeZones for FixedTimeZonesOperation zoneBytes#
zoneBytes: FixedTimeZones.zoneBytesOperation names#
names: FixedTimeZones.namesOperation version#
version: FixedTimeZones.versionsortedNames#
pub effect fn sortedNames(names: List<Bytes>) -> List<Bytes> ! OutOfMemoryError ? &mut AllocatorReturns names sorted by their bytes. Providers use it for TimeZones.names.
Errors#
OutOfMemoryErrorif theAllocatorcannot supply the sorted list.
FixedLocalZone#
pub struct FixedLocalZoneA LocalZone provider that always answers with one name, for tests.
Implementation FixedLocalZone#
impl FixedLocalZoneAssociated function make#
pub effect fn make(name: string) -> FixedLocalZone ! OutOfMemoryError ? &mut AllocatorReturns a provider that answers name.
Errors#
OutOfMemoryErrorif theAllocatorcannot supply the copy.
Implementation LocalZone for FixedLocalZone#
impl LocalZone for FixedLocalZoneOperation name#
name: FixedLocalZone.nameCategory: Time.
Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.