silk.time.zoned.
Instants seen in a time zone: the ZonedDateTime type, and ZonedText for its RFC 9557
text such as 2026-11-19T15:36:22-03:00[America/Sao_Paulo].
When to use#
Use a ZonedDateTime when a point in time must keep the place it belongs to: a meeting, a
departure, a time shown to a person. It gives the local date and time, and it finds the
instant of a local time with the daylight saving rules of the zone. For a point in time
without a place, use Instant. For a date and time on no timeline, use PlainDateTime.
Details#
A ZonedDateTime is an Instant and a borrowed Zone, so it is Copy, and it cannot
outlive the zone. Get the zone from the TimeZones service of silk.time.zones.
To read text, first parse it with ZonedText.parse, which needs no zone. Then load the
zone that the text names, and call ZonedDateTime.fromText. The two steps are separate
because loading a zone is an effect and parsing is not.
Errors#
TimeParseErrorfromZonedText.parse.LocalTimeErrorfromZonedDateTime.fromLocalandZonedDateTime.fromText.
Examples#
Show an instant in a zone, and read 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 }
import silk.time.zoned { ZonedDateTime }
effect fn check() -> i32 ! ZoneDataError | OutOfMemoryError ? &mut Allocator {
let rome = run Zone.fromPosixRule("CET-1CEST,M3.5.0,M10.5.0/3")
let seen = ZonedDateTime.make(Instant.fromUnixSeconds(1795109782), &rome)
if seen.time().hour() != 18 || seen.offset().totalSeconds() != 3600 {
return 1
}
let noon = PlainDateTime.fromFields(2027, 7, 1, 12, 0, 0)
match ZonedDateTime.fromLocal(noon, &rome, Disambiguation.Compatible) {
Result<ZonedDateTime, LocalTimeError>.Success { value } => {
// Summer time is two hours ahead of UTC.
if value.instant().toUtc().time().hour() != 10 {
return 2
}
}
Result<ZonedDateTime, LocalTimeError>.Failure { error: _ } => {
return 3
}
}
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 ZonedDateTime with import silk.time.zoned { ZonedDateTime }.
Public declarations: 3.
OffsetConflict#
pub enum OffsetConflictWhat ZonedDateTime.fromText does when a text states a UTC offset that its zone does not
have at that local time, which happens when the rules of a zone change after the text was
written.
Use#
UseKeep the instant that the offset in the text gives. The local time can change.
Ignore#
IgnoreDo not read the offset. Keep the local time and find the instant in the zone.
Prefer#
PreferUse the offset if the zone has it at that local time. If not, keep the local time and find the instant in the zone.
Reject#
RejectFail with LocalTimeError.OffsetMismatch if the zone does not have the offset at that
local time.
ZonedDateTime#
pub struct ZonedDateTime<'z>An instant seen in a time zone.
Details#
The value is an Instant, a borrowed Zone, and the UTC offset of the zone at that instant.
== is true for the same instant in zones with the same name. + and - with a Duration
move along the timeline, and trap when the result is outside the range of Instant. -
between two values gives the Duration between their instants. Display writes RFC 9557
text such as 2026-11-19T15:36:22-03:00[America/Sao_Paulo].
Implementation Copy for ZonedDateTime<'z>#
impl<'z> Copy for ZonedDateTime<'z>Implementation ZonedDateTime<'z>#
impl<'z> ZonedDateTime<'z>Associated function make#
pub fn make(instant: Instant, zone: &'z Zone) -> ZonedDateTime<'z>Returns the instant instant as seen in zone.
Associated function fromLocal#
pub fn fromLocal(
local: PlainDateTime,
zone: &'z Zone,
choice: Disambiguation
) -> Result<ZonedDateTime<'z>, LocalTimeError>Returns the instant at which a clock in 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.
Associated function fromText#
pub fn fromText(
text: &ZonedText<'_>,
zone: &'z Zone,
conflict: OffsetConflict,
choice: Disambiguation
) -> Result<ZonedDateTime<'z>, LocalTimeError>Returns the value that the parsed text text names in zone.
Details#
zone must be the zone that ZonedText.zoneName names; this function does not compare
the names. A text with Z gives that instant. A text with a numeric offset is read as
conflict says. An offset without seconds also matches a zone offset that rounds to it,
because the text of a ZonedDateTime rounds its offset to the minute. A text without an
offset gives the local time, with choice for a time that does not name exactly one
instant. A text without a time gives the start of the day.
Errors#
LocalTimeError.OffsetMismatchifconflictisOffsetConflict.Rejectand the zone does not have the offset of the text at that local time.LocalTimeError.SkippedorLocalTimeError.RepeatedifchoiceisDisambiguation.Rejectand the local time names no instant or two.LocalTimeError.OutOfRangeif the instant is outside the range ofInstant.
Method instant#
pub fn instant(self: Self) -> InstantReturns the instant.
Method zone#
pub fn zone(self: Self) -> &'z ZoneReturns the zone.
Method offset#
pub fn offset(self: Self) -> UtcOffsetReturns the UTC offset of the zone at this instant.
Method toPlainDateTime#
pub fn toPlainDateTime(self: Self) -> PlainDateTimeReturns the date and time that a clock in the zone shows at this instant.
Method date#
pub fn date(self: Self) -> PlainDateReturns the date that a calendar in the zone shows at this instant.
Method time#
pub fn time(self: Self) -> PlainTimeReturns the time of day that a clock in the zone shows at this instant.
Method abbreviation#
pub fn abbreviation(self: Self) -> stringReturns the abbreviation of the zone at this instant, such as CET or -03.
Method isDaylight#
pub fn isDaylight(self: Self) -> boolReturns true if daylight saving time is in effect in the zone at this instant.
Method withZone#
pub fn withZone<'other>(self: Self, zone: &'other Zone) -> ZonedDateTime<'other>Returns the same instant as seen in zone.
Method withLocal#
pub fn withLocal(self: Self, local: PlainDateTime, choice: Disambiguation) -> Result<ZonedDateTime<'z>, LocalTimeError>Returns the value in the same zone whose clock shows local, and uses choice when the
time does not name exactly one instant.
Errors#
LocalTimeError, as forZonedDateTime.fromLocal.
Method startOfDay#
pub fn startOfDay(self: Self) -> Option<ZonedDateTime<'z>>Returns the first instant of this local day 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 when the clock shows a later time.
Method checkedAdd#
pub fn checkedAdd(self: Self, span: Duration) -> Option<ZonedDateTime<'z>>Returns the value span later on the timeline, or earlier for a negative span, or None
when it is outside the range of Instant.
Details#
The span is exact elapsed time. Across a change of offset, the local time moves by a different amount: one hour after 01:30 on a day when clocks go forward at 02:00 is 03:30.
Method checkedSubtract#
pub fn checkedSubtract(self: Self, span: Duration) -> Option<ZonedDateTime<'z>>Returns the value span earlier on the timeline, or later for a negative span, or None
when it is outside the range of Instant.
Method checkedRound#
pub fn checkedRound(self: Self, step: TimeIncrement, mode: RoundingMode) -> Option<ZonedDateTime<'z>>Returns the value with its local time rounded to a multiple of step from midnight, or
None when the result is outside the range.
Details#
The local date and time are rounded as PlainDateTime.round does, and the result keeps
the UTC offset of this value when the zone has that offset at the rounded time. So a time
in the repeated hour of an autumn change stays on its side of the change. A rounded time
that a change skips moves forward by the length of the gap.
TimeIncrement.one(TimeUnit.Day) rounds to the start of this day or of the next day in
the zone, by the real length of the day, which is 23 or 25 hours on the day of a change.
Examples#
import silk.core.result { Result }
import silk.time.plain_date_time { PlainDateTime }
import silk.time.rounding { RoundingMode, TimeIncrement, TimeUnit }
import silk.time.zone { Disambiguation, LocalTimeError, Zone }
import silk.time.zoned { ZonedDateTime }
pub fn main() -> i32 {
let zone = Zone.utc()
let local = PlainDateTime.fromFields(2026, 11, 19, 15, 36, 22)
match ZonedDateTime.fromLocal(local, &zone, Disambiguation.Compatible) {
Result<ZonedDateTime, LocalTimeError>.Success { value } => {
let hour = value.round(TimeIncrement.one(TimeUnit.Hour), RoundingMode.HalfExpand)
if &hour.toPlainDateTime() != &PlainDateTime.fromFields(2026, 11, 19, 16, 0, 0) {
return 1
}
return 0
}
Result<ZonedDateTime, LocalTimeError>.Failure { error: _ } => {
return 2
}
}
}Method round#
pub fn round(self: Self, step: TimeIncrement, mode: RoundingMode) -> ZonedDateTime<'z>Returns the value with its local time rounded to a multiple of step from midnight.
Gotchas#
A result outside the range traps. ZonedDateTime.checkedRound returns None instead,
and describes the rounding.
Method checkedAddPeriod#
pub fn checkedAddPeriod(self: Self, period: Period, overflow: Overflow) -> Option<ZonedDateTime<'z>>Returns the value period later, or earlier for a negative period, or None when the
result is outside the range or overflow rejects a day of the month.
Details#
The years, months, weeks, and days move the local date and keep the local time, so one day later is the same time on the clock on the next day, also over a daylight saving change. A local time that a change skips moves forward by the length of the gap, and a repeated one is the earlier of the two. The time part of the period is then added as an exact span.
A period with only a time part moves along the timeline, as + with a Duration does.
Method addPeriod#
pub fn addPeriod(self: Self, period: Period) -> ZonedDateTime<'z>Returns the value period later, or earlier for a negative period. A day of the month that
the reached month does not have becomes its last day.
Gotchas#
A result outside the range traps. ZonedDateTime.checkedAddPeriod returns None
instead, and describes the arithmetic.
Examples#
import silk.core.result { Result }
import silk.time.period { Period }
import silk.time.plain_date_time { PlainDateTime }
import silk.time.zone { Disambiguation, LocalTimeError, Zone }
import silk.time.zoned { ZonedDateTime }
pub fn main() -> i32 {
let zone = Zone.utc()
let local = PlainDateTime.fromFields(2027, 1, 31, 9, 0, 0)
match ZonedDateTime.fromLocal(local, &zone, Disambiguation.Compatible) {
Result<ZonedDateTime, LocalTimeError>.Success { value } => {
let later = value.addPeriod(Period.ofMonths(1))
if &later.toPlainDateTime() != &PlainDateTime.fromFields(2027, 2, 28, 9, 0, 0) {
return 1
}
return 0
}
Result<ZonedDateTime, LocalTimeError>.Failure { error: _ } => {
return 2
}
}
}Method periodUntil#
pub fn periodUntil<'other>(self: Self, other: ZonedDateTime<'other>, largest: DateUnit) -> PeriodReturns the period from this value to other, with largest as its largest unit. The
period is negative when other is earlier.
Details#
Both values are read in the zone of this value. The date part counts whole years, months,
weeks, or days on the calendar of the zone, and the time part is the exact span that
remains. So from noon on the day before a daylight saving change to noon on the day after
is two days, and ZonedDateTime.until gives the 47 or 49 hours between the instants.
self.addPeriod(self.periodUntil(other, largest)) is other. Two values on the same local
date have a period with only a time part.
Method since#
pub fn since<'other>(self: Self, earlier: ZonedDateTime<'other>) -> DurationReturns the exact time from earlier to this value. It is negative if earlier is later.
The zones do not matter.
Method until#
pub fn until<'other>(self: Self, later: ZonedDateTime<'other>) -> DurationReturns the exact time from this value to later. It is negative if later is earlier.
The zones do not matter.
Method write#
pub fn write(self: Self, output: &mut [u8], at: usize) -> usizeWrites the value as RFC 9557 text, as in 2026-11-19T15:36:22-03:00[America/Sao_Paulo],
at output[at], and returns the offset after it.
Details#
The offset is rounded to the minute, as ECMAScript Temporal writes it. The text has a fraction, without zeros at the end, when the nanosecond part is not zero. It is at most 40 bytes plus the length of the zone name.
Gotchas#
Traps if output is too short.
Implementation Equal for ZonedDateTime<'z>#
impl<'z> Equal for ZonedDateTime<'z>Operation equals#
equals: ZonedDateTime.sameImplementation Add<Duration, ZonedDateTime<'z>> for ZonedDateTime<'z>#
impl<'z> Add<Duration, ZonedDateTime<'z>> for ZonedDateTime<'z>Operation add#
add: ZonedDateTime.addOperatorImplementation Subtract<Duration, ZonedDateTime<'z>> for ZonedDateTime<'z>#
impl<'z> Subtract<Duration, ZonedDateTime<'z>> for ZonedDateTime<'z>Operation subtract#
subtract: ZonedDateTime.subtractOperatorImplementation Subtract<ZonedDateTime<'z>, Duration> for ZonedDateTime<'z>#
impl<'z> Subtract<ZonedDateTime<'z>, Duration> for ZonedDateTime<'z>Operation subtract#
subtract: ZonedDateTime.differenceOperatorImplementation Display for ZonedDateTime<'z>#
impl<'z> Display for ZonedDateTime<'z>Writes RFC 9557 text: the local date and time, the UTC offset rounded to the minute, and the
name of the zone in brackets, as in 2026-11-19T15:36:22-03:00[America/Sao_Paulo].
Operation display#
effect fn display(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterImplementation Debug for ZonedDateTime<'z>#
impl<'z> Debug for ZonedDateTime<'z>Writes the same text as Display.
Operation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterZonedText#
pub struct ZonedText<'text>The parts of RFC 9557 text such as 2026-11-19T15:36:22-03:00[America/Sao_Paulo], read
without a zone. ZonedDateTime.fromText turns it into a value.
Details#
The value borrows the text for the name of the zone.
Implementation Copy for ZonedText<'text>#
impl<'text> Copy for ZonedText<'text>Implementation ZonedText<'text>#
impl<'text> ZonedText<'text>Associated function parse#
pub fn parse(text: string<'text>) -> Result<ZonedText<'text>, TimeParseError>Reads the parts of RFC 9557 text such as 2026-11-19T15:36:22-03:00[America/Sao_Paulo].
Details#
The text is a date, optionally a time, optionally Z or a numeric offset after the time,
and a time zone annotation in brackets. The annotation is required. Its content is not
checked against any list of zones. More annotations can follow, as for the other parsers.
Errors#
TimeParseReason.MissingZoneif the text has no time zone annotation.TimeParseReason.UnexpectedCharacterif the name of the zone has a byte that is not an ASCII letter, a digit, or one of/,_,-,+,., and:.The other reasons, as for
PlainDateTime.parse.
Associated function parseBytes#
pub fn parseBytes(bytes: &'text [u8]) -> Result<ZonedText<'text>, TimeParseError>Reads the parts of RFC 9557 text from bytes. See ZonedText.parse.
Errors#
TimeParseError, as forZonedText.parse.
Method zoneName#
pub fn zoneName(self: Self) -> string<'text>Returns the name in the time zone annotation, such as America/Sao_Paulo or +05:30.
Method dateTime#
pub fn dateTime(self: Self) -> PlainDateTimeReturns the local date and time of the text. The time is midnight when the text has none.
Method hasTime#
pub fn hasTime(self: Self) -> boolReturns true if the text has a time of day.
Method isUtc#
pub fn isUtc(self: Self) -> boolReturns true if the text has the UTC designator Z.
Method offset#
pub fn offset(self: Self) -> Option<UtcOffset>Returns the numeric UTC offset of the text, or None if it has Z or no offset.
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.