silk.time.zone.

Time zone rules: the Zone type, which tells the UTC offset of a place at each instant and turns a local date and time into an instant.

When to use#

Use a Zone to show an instant as the local time of a place, or to find the instant that a local time names. Get a zone by name from the TimeZones service of silk.time.zones, or make one from the bytes of a TZif file with Zone.fromTzif. Zone.utc and Zone.fixed need no data. silk.time.zoned joins an instant and a zone into one value.

Details#

A zone holds the content of one TZif file of the IANA time zone database: a sorted table of the instants at which the offset changed, and the POSIX rule that continues after the last entry. Because the rule is kept, a zone answers for any year, not only for the years in the table.

A local time is not always one instant. When clocks go forward, some local times do not exist. When clocks go back, some local times happen twice. Zone.candidates returns every instant, and Zone.resolve picks one with a Disambiguation.

Errors#

Gotchas#

Leap seconds are not counted, as in Unix time. A TZif file with leap second records (the right/ files of some systems) is rejected.

Examples#

Find the offset and resolve a local time#

silk
import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.core.effect { Effect }
import silk.core.result { Result }
import silk.time.instant { Instant }
import silk.time.plain_date_time { PlainDateTime }
import silk.time.zone { Disambiguation, LocalTimeError, Zone, ZoneDataError }

effect fn check() -> i32 ! ZoneDataError | OutOfMemoryError ? &mut Allocator {
  // Central European time: one hour ahead, two in summer.
  let rome = run Zone.fromPosixRule("CET-1CEST,M3.5.0,M10.5.0/3")
  let winter = Instant.fromUnixSeconds(1795109782)
  if rome.offsetAt(winter).totalSeconds() != 3600 {
    return 1
  }
  // 02:30 on the last Sunday of March does not exist: clocks go from 02:00 to 03:00.
  let skipped = PlainDateTime.fromFields(2027, 3, 28, 2, 30, 0)
  if rome.candidates(skipped).count != 0 {
    return 2
  }
  match rome.resolve(skipped, Disambiguation.Compatible) {
    Result<Instant, LocalTimeError>.Success { value } => {
      // The compatible choice moves the time forward by the hour that was skipped.
      if value.toOffset(rome.offsetAt(value)).time().hour() != 3 {
        return 3
      }
    }
    Result<Instant, LocalTimeError>.Failure { error: _ } => {
      return 4
    }
  }
  return 0
}

effect fn failed(error: ZoneDataError | OutOfMemoryError) -> i32 {
  return 9
}

pub effect fn main() -> i32 {
  let mut allocator = Allocator.systemAllocatorProvider()
  return run Effect.catchAll(check(), failed) |> Effect.provideMut<Allocator>(&mut allocator)
}

Import as Zone with import silk.time.zone { Zone }.

Public declarations: 6.

Disambiguation#

silk
pub enum Disambiguation

How Zone.resolve picks an instant when a local time does not name exactly one.

Compatible#

silk
Compatible

For a time that happens twice, the earlier instant. For a time that does not exist, the time moved forward by the length of the gap. This is the choice of RFC 5545 and of ECMAScript Temporal.

Earlier#

silk
Earlier

For a time that happens twice, the earlier instant. For a time that does not exist, the time moved back by the length of the gap.

Later#

silk
Later

For a time that happens twice, the later instant. For a time that does not exist, the time moved forward by the length of the gap.

Reject#

silk
Reject

Fail with a LocalTimeError unless the time names exactly one instant.

LocalTimeError#

silk
pub enum LocalTimeError

Why a local date and time names no instant in a zone.

Skipped#

silk
Skipped

The local time does not exist, because clocks went forward over it.

Repeated#

silk
Repeated

The local time happens twice, because clocks went back over it.

OutOfRange#

silk
OutOfRange

The instant is outside the range of Instant.

OffsetMismatch#

silk
OffsetMismatch

A text states a UTC offset that the zone does not have at that local time.

Implementation Debug for LocalTimeError#

silk
impl Debug for LocalTimeError

Operation debug#

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

ZoneDataReason#

silk
pub enum ZoneDataReason

The cause of a ZoneDataError.

NotTzif#

silk
NotTzif

The data does not start with the TZif magic bytes.

Truncated#

silk
Truncated

The data ends before the tables that its header declares.

InvalidTable#

silk
InvalidTable

A table has a value that is not allowed: a transition out of order, an index past the end of a table, an offset of 24 hours or more, or a name that is not ASCII.

LeapSeconds#

silk
LeapSeconds

The data has leap second records. This library does not count leap seconds.

InvalidRule#

silk
InvalidRule

The POSIX rule is not valid.

Implementation Debug for ZoneDataReason#

silk
impl Debug for ZoneDataReason

Operation debug#

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

ZoneDataError#

silk
pub struct ZoneDataError

The error of Zone.fromTzif and Zone.fromPosixRule: the data is not a valid zone.

Field reason#

silk
pub reason: ZoneDataReason

The cause.

Implementation Copy for ZoneDataError#

silk
impl Copy for ZoneDataError

Implementation Debug for ZoneDataError#

silk
impl Debug for ZoneDataError

Operation debug#

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

LocalCandidates#

silk
pub struct LocalCandidates

The instants that a local date and time names in a zone, from Zone.candidates.

Field count#

silk
pub count: u8

The number of instants: 1 for most times, 0 for a time that clocks skipped, and 2 for a time that happens twice.

Field earlier#

silk
pub earlier: Instant

The first instant. It has a meaning only when count is at least 1.

Field later#

silk
pub later: Instant

The last instant. It is equal to earlier unless count is 2.

Field skipped#

silk
pub skipped: bool

true if the time is inside a gap, where clocks went forward. Then count is 0, and transition, before, and after describe the gap.

Field transition#

silk
pub transition: Instant

The instant at which the clocks went forward.

Field before#

silk
pub before: UtcOffset

The offset in effect before transition.

Field after#

silk
pub after: UtcOffset

The offset in effect from transition.

Implementation Copy for LocalCandidates#

silk
impl Copy for LocalCandidates

Zone#

silk
pub struct Zone

The rules of one time zone: its UTC offset at every instant.

Details#

A zone owns its table. It is not Copy; share it by reference. ZonedDateTime of silk.time.zoned borrows a zone. All operations are plain functions, without effects.

Implementation Zone#

silk
impl Zone

Associated function utc#

silk
pub fn utc() -> Zone

Returns the zone UTC, which has the offset zero at every instant. It does not allocate.

Associated function fixed#

silk
pub fn fixed(offset: UtcOffset) -> Zone

Returns a zone that has the offset offset at every instant. It does not allocate.

Details#

The name of the zone is the offset as text, such as +05:30.

Associated function fromTzif#

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

Reads a zone from the bytes of a TZif file, the format of the files under /usr/share/zoneinfo, and gives it the name name.

Details#

All versions of the format are read (RFC 9636). For version 2 and later, the 64-bit table and the POSIX rule in the footer are used. A version 1 file has a 32-bit table and no rule, so after its last transition the offset stays as it is. The zone keeps a copy of the tables; data is not borrowed.

Errors#

  • ZoneDataError if data is not a valid TZif file, or has leap second records.

  • OutOfMemoryError if the Allocator cannot supply the copy.

Associated function fromPosixRule#

silk
pub effect fn fromPosixRule(rule: string) -> Zone
    ! ZoneDataError | OutOfMemoryError
    ? &mut Allocator

Makes a zone from a POSIX TZ rule such as EST5EDT,M3.2.0,M11.1.0 or <-03>3. The name of the zone is the rule.

Details#

The rule is a name and an offset for standard time, then optionally a name and an offset for daylight time and the two dates on which daylight time starts and ends. An offset is hours west of UTC, so EST5 is five hours behind UTC. A name is three or more letters, or text in < and >. A date is Mm.w.d (month, week 1 to 5, day 0 to 6 from Sunday), Jn (day 1 to 365, without February 29), or n (day 0 to 365), with an optional /time from -167 to 167 hours. Without a time the change is at 02:00.

Errors#

  • ZoneDataError with the reason InvalidRule if rule does not have that form. A rule with daylight time and no dates is not accepted.

  • OutOfMemoryError if the Allocator cannot supply the copy.

Associated function fromPosixRuleNamed#

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

Makes a zone from a POSIX TZ rule, as Zone.fromPosixRule does, and gives it the name name.

Errors#

Method name#

silk
pub fn name(self: &Self) -> string

Returns the name of the zone, as it was given: an IANA name such as Europe/Rome, UTC, an offset such as +05:30, or a POSIX rule.

Method offsetAt#

silk
pub fn offsetAt(self: &Self, at: Instant) -> UtcOffset

Returns the UTC offset of the zone at the instant at.

Method isDaylightAt#

silk
pub fn isDaylightAt(self: &Self, at: Instant) -> bool

Returns true if daylight saving time is in effect in the zone at the instant at.

Gotchas#

This is the flag of the time zone database, and its meaning differs by place. In Europe/Dublin the flag is set in winter. To find the offset, use Zone.offsetAt.

Method abbreviationAt#

silk
pub fn abbreviationAt(self: &Self, at: Instant) -> string

Returns the abbreviation of the zone at the instant at, such as CET or CEST.

Details#

Many zones have no letters and use the offset, such as -03. A zone from Zone.utc or Zone.fixed returns its name.

Gotchas#

An abbreviation does not identify a zone: CST is used in North America, China, and Cuba.

Method nextTransition#

silk
pub fn nextTransition(self: &Self, at: Instant) -> Option<Instant>

Returns the first instant after at at which the UTC offset of the zone changes, or None if it never changes again.

Details#

A change of only the abbreviation or the daylight flag is not counted. The result can be in any year: after the end of the table, the changes come from the POSIX rule of the zone.

Method previousTransition#

silk
pub fn previousTransition(self: &Self, at: Instant) -> Option<Instant>

Returns the last instant before at at which the UTC offset of the zone changed, or None if it did not change before.

Details#

A change of only the abbreviation or the daylight flag is not counted. When at is itself an instant of change, the result is the change before it.

Method candidates#

silk
pub fn candidates(self: &Self, local: PlainDateTime) -> LocalCandidates

Returns the instants at which a clock in the zone shows the date and time local.

Details#

Most times give one instant. A time in a gap, where clocks went forward, gives none: the result has skipped set, with the instant of the change and the offsets on both sides. A time in an overlap, where clocks went back, gives two.

Method resolve#

silk
pub fn resolve(self: &Self, local: PlainDateTime, choice: Disambiguation) -> Result<Instant, LocalTimeError>

Returns the instant at which a clock in the zone shows the date and time local, and uses choice when the time does not name exactly one instant.

Errors#

  • LocalTimeError.Skipped or LocalTimeError.Repeated if choice is Disambiguation.Reject and the time names no instant or two.

  • LocalTimeError.OutOfRange if the instant is outside the range of Instant.

Method startOfDay#

silk
pub fn startOfDay(self: &Self, date: PlainDate) -> Option<Instant>

Returns the first instant of the day date in the zone, or None if it is outside the range of Instant.

Details#

This is midnight on most days. On a day when clocks go forward over midnight, the day starts at the instant of the change, when the clock shows a later time.

Implementation Debug for Zone#

silk
impl Debug for Zone

Writes the name of the zone and a short description of its table.

Operation debug#

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

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