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#
ZoneDataErrorfromZone.fromTzifandZone.fromPosixRuleif the data is not valid.LocalTimeErrorfromZone.resolveif the local time names no instant under the chosenDisambiguation.
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#
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#
pub enum DisambiguationHow Zone.resolve picks an instant when a local time does not name exactly one.
Compatible#
CompatibleFor 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#
EarlierFor 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#
LaterFor 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#
RejectFail with a LocalTimeError unless the time names exactly one instant.
LocalTimeError#
pub enum LocalTimeErrorWhy a local date and time names no instant in a zone.
Skipped#
SkippedThe local time does not exist, because clocks went forward over it.
Repeated#
RepeatedThe local time happens twice, because clocks went back over it.
OutOfRange#
OutOfRangeThe instant is outside the range of Instant.
OffsetMismatch#
OffsetMismatchA text states a UTC offset that the zone does not have at that local time.
Implementation Debug for LocalTimeError#
impl Debug for LocalTimeErrorOperation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterZoneDataReason#
pub enum ZoneDataReasonThe cause of a ZoneDataError.
NotTzif#
NotTzifThe data does not start with the TZif magic bytes.
Truncated#
TruncatedThe data ends before the tables that its header declares.
InvalidTable#
InvalidTableA 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#
LeapSecondsThe data has leap second records. This library does not count leap seconds.
InvalidRule#
InvalidRuleThe POSIX rule is not valid.
Implementation Debug for ZoneDataReason#
impl Debug for ZoneDataReasonOperation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterZoneDataError#
pub struct ZoneDataErrorThe error of Zone.fromTzif and Zone.fromPosixRule: the data is not a valid zone.
Field reason#
pub reason: ZoneDataReasonThe cause.
Implementation Copy for ZoneDataError#
impl Copy for ZoneDataErrorImplementation Debug for ZoneDataError#
impl Debug for ZoneDataErrorOperation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterLocalCandidates#
pub struct LocalCandidatesThe instants that a local date and time names in a zone, from Zone.candidates.
Field count#
pub count: u8The number of instants: 1 for most times, 0 for a time that clocks skipped, and 2 for a time that happens twice.
Field earlier#
pub earlier: InstantThe first instant. It has a meaning only when count is at least 1.
Field later#
pub later: InstantThe last instant. It is equal to earlier unless count is 2.
Field skipped#
pub skipped: booltrue 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#
pub transition: InstantThe instant at which the clocks went forward.
Field before#
pub before: UtcOffsetThe offset in effect before transition.
Field after#
pub after: UtcOffsetThe offset in effect from transition.
Implementation Copy for LocalCandidates#
impl Copy for LocalCandidatesZone#
pub struct ZoneThe 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#
impl ZoneAssociated function utc#
pub fn utc() -> ZoneReturns the zone UTC, which has the offset zero at every instant. It does not allocate.
Associated function fixed#
pub fn fixed(offset: UtcOffset) -> ZoneReturns 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#
pub effect fn fromTzif(name: string, data: &[u8]) -> Zone
! ZoneDataError | OutOfMemoryError
? &mut AllocatorReads 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#
ZoneDataErrorifdatais not a valid TZif file, or has leap second records.OutOfMemoryErrorif theAllocatorcannot supply the copy.
Associated function fromPosixRule#
pub effect fn fromPosixRule(rule: string) -> Zone
! ZoneDataError | OutOfMemoryError
? &mut AllocatorMakes 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#
ZoneDataErrorwith the reasonInvalidRuleifruledoes not have that form. A rule with daylight time and no dates is not accepted.OutOfMemoryErrorif theAllocatorcannot supply the copy.
Associated function fromPosixRuleNamed#
pub effect fn fromPosixRuleNamed(name: string, rule: string) -> Zone
! ZoneDataError | OutOfMemoryError
? &mut AllocatorMakes a zone from a POSIX TZ rule, as Zone.fromPosixRule does, and gives it the name
name.
Errors#
ZoneDataErrorandOutOfMemoryError, as forZone.fromPosixRule.
Method name#
pub fn name(self: &Self) -> stringReturns 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#
pub fn offsetAt(self: &Self, at: Instant) -> UtcOffsetReturns the UTC offset of the zone at the instant at.
Method isDaylightAt#
pub fn isDaylightAt(self: &Self, at: Instant) -> boolReturns 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#
pub fn abbreviationAt(self: &Self, at: Instant) -> stringReturns 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#
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#
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#
pub fn candidates(self: &Self, local: PlainDateTime) -> LocalCandidatesReturns 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#
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.SkippedorLocalTimeError.RepeatedifchoiceisDisambiguation.Rejectand the time names no instant or two.LocalTimeError.OutOfRangeif the instant is outside the range ofInstant.
Method startOfDay#
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#
impl Debug for ZoneWrites the name of the zone and a short description of its table.
Operation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterCategory: 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.