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#

  • ZoneLookupError from TimeZones, with a reason: the zone is not known, the name is not valid, or the data cannot be read or is damaged.

  • NoLocalZoneError from LocalZone if the machine does not say which zone it is in. The caller decides what to use then; no provider answers UTC in silence.

Examples#

Provide fixed zones in a test#

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.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#

silk
pub enum ZoneLookupReason

The cause of a ZoneLookupError.

UnknownZone#

silk
UnknownZone

The provider has no zone with that name.

InvalidName#

silk
InvalidName

The 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#

silk
Unreadable

The provider could not read its data.

InvalidData#

silk
InvalidData

The data of the zone is damaged.

Implementation Debug for ZoneLookupReason#

silk
impl Debug for ZoneLookupReason

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

ZoneLookupError#

silk
pub struct ZoneLookupError

The error of the TimeZones effect: why the provider cannot answer.

Field reason#

silk
pub reason: ZoneLookupReason

The cause.

Implementation Copy for ZoneLookupError#

silk
impl Copy for ZoneLookupError

Implementation Debug for ZoneLookupError#

silk
impl Debug for ZoneLookupError

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

NoLocalZoneError#

silk
pub struct NoLocalZoneError

The error of the LocalZone effect: the machine does not say which zone it is in.

Implementation Copy for NoLocalZoneError#

silk
impl Copy for NoLocalZoneError

Implementation Debug for NoLocalZoneError#

silk
impl Debug for NoLocalZoneError

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

TimeZones#

silk
pub service TimeZones

The 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#

silk
effect fn zoneBytes(
    name: &[u8]
  ) -> Zone ! ZoneLookupError | OutOfMemoryError ? &mut TimeZones | &mut Allocator

Returns the zone named by the bytes name.

Errors#

  • ZoneLookupError with the reason UnknownZone if the provider has no such zone, InvalidName if name cannot be a zone name, Unreadable if the provider cannot read its data, or InvalidData if the data of the zone is damaged.

  • OutOfMemoryError if the Allocator cannot supply the zone.

Operation names#

silk
effect fn names() -> List<Bytes> ! ZoneLookupError | OutOfMemoryError ? &mut TimeZones | &mut Allocator

Returns 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#

  • ZoneLookupError with the reason Unreadable if the provider cannot list its zones.

  • OutOfMemoryError if the Allocator cannot supply the copies.

Operation version#

silk
effect fn version() -> Bytes ! OutOfMemoryError ? &mut TimeZones | &mut Allocator

Returns 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#

  • OutOfMemoryError if the Allocator cannot supply the copy.

Implementation TimeZones#

silk
impl TimeZones

Associated function zone#

silk
pub effect fn zone(
    name: string
  ) -> Zone ! ZoneLookupError | OutOfMemoryError ? &mut TimeZones | &mut Allocator

Returns the zone named name, such as America/Sao_Paulo.

Errors#

Associated function fixedZone#

silk
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#

silk
pub fn isValidName(name: &[u8]) -> bool

Returns 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#

silk
pub fn sameName(left: &[u8], right: &[u8]) -> bool

Returns true if left and right are the same zone name, without letter case.

Associated function lookupFailure#

silk
pub fn lookupFailure(reason: ZoneLookupReason) -> ZoneLookupError

Returns a ZoneLookupError with the reason reason. Providers use it.

LocalZone#

silk
pub service LocalZone

The 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#

silk
effect fn name() -> Bytes ! NoLocalZoneError | OutOfMemoryError ? &mut LocalZone | &mut Allocator

Returns a copy of the name of the zone that this machine is set to.

Errors#

  • NoLocalZoneError if the machine does not say which zone it is in.

  • OutOfMemoryError if the Allocator cannot supply the copy.

Implementation LocalZone#

silk
impl LocalZone

Associated function unknown#

silk
pub fn unknown() -> NoLocalZoneError

Returns a NoLocalZoneError. Providers use it.

FixedTimeZones#

silk
pub struct FixedTimeZones

A 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#

silk
impl FixedTimeZones

Associated function make#

silk
pub fn make() -> FixedTimeZones

Returns a provider with no zones. It does not allocate.

Method setVersion#

silk
pub effect fn setVersion(self: &mut Self, version: string) -> () ! OutOfMemoryError ? &mut Allocator

Sets the database version that TimeZones.version returns, such as 2026b.

Errors#

  • OutOfMemoryError if the Allocator cannot supply the copy.

Method addTzif#

silk
pub effect fn addTzif(self: &mut Self, name: string, data: &[u8]) -> ()
    ! ZoneDataError | OutOfMemoryError
    ? &mut Allocator

Adds the zone name with the bytes of a TZif file, the format of the files under /usr/share/zoneinfo.

Errors#

  • ZoneDataError if data is not a valid TZif file.

  • OutOfMemoryError if the Allocator cannot supply the copy.

Method addPosixRule#

silk
pub effect fn addPosixRule(self: &mut Self, name: string, rule: string) -> ()
    ! ZoneDataError | OutOfMemoryError
    ? &mut Allocator

Adds 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#

  • ZoneDataError if rule is not a valid rule.

  • OutOfMemoryError if the Allocator cannot supply the copy.

Implementation TimeZones for FixedTimeZones#

silk
impl TimeZones for FixedTimeZones

Operation zoneBytes#

silk
zoneBytes: FixedTimeZones.zoneBytes

Operation names#

silk
names: FixedTimeZones.names

Operation version#

silk
version: FixedTimeZones.version

sortedNames#

silk
pub effect fn sortedNames(names: List<Bytes>) -> List<Bytes> ! OutOfMemoryError ? &mut Allocator

Returns names sorted by their bytes. Providers use it for TimeZones.names.

Errors#

  • OutOfMemoryError if the Allocator cannot supply the sorted list.

FixedLocalZone#

silk
pub struct FixedLocalZone

A LocalZone provider that always answers with one name, for tests.

Implementation FixedLocalZone#

silk
impl FixedLocalZone

Associated function make#

silk
pub effect fn make(name: string) -> FixedLocalZone ! OutOfMemoryError ? &mut Allocator

Returns a provider that answers name.

Errors#

  • OutOfMemoryError if the Allocator cannot supply the copy.

Implementation LocalZone for FixedLocalZone#

silk
impl LocalZone for FixedLocalZone

Operation name#

silk
name: FixedLocalZone.name

Category: 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.

View the source of this page