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#

Examples#

Show an instant in a zone, and read 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 }
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#

silk
pub enum OffsetConflict

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

silk
Use

Keep the instant that the offset in the text gives. The local time can change.

Ignore#

silk
Ignore

Do not read the offset. Keep the local time and find the instant in the zone.

Prefer#

silk
Prefer

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

silk
Reject

Fail with LocalTimeError.OffsetMismatch if the zone does not have the offset at that local time.

ZonedDateTime#

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

silk
impl<'z> Copy for ZonedDateTime<'z>

Implementation ZonedDateTime<'z>#

silk
impl<'z> ZonedDateTime<'z>

Associated function make#

silk
pub fn make(instant: Instant, zone: &'z Zone) -> ZonedDateTime<'z>

Returns the instant instant as seen in zone.

Associated function fromLocal#

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

Associated function fromText#

silk
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.OffsetMismatch if conflict is OffsetConflict.Reject and the zone does not have the offset of the text at that local time.

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

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

Method instant#

silk
pub fn instant(self: Self) -> Instant

Returns the instant.

Method zone#

silk
pub fn zone(self: Self) -> &'z Zone

Returns the zone.

Method offset#

silk
pub fn offset(self: Self) -> UtcOffset

Returns the UTC offset of the zone at this instant.

Method toPlainDateTime#

silk
pub fn toPlainDateTime(self: Self) -> PlainDateTime

Returns the date and time that a clock in the zone shows at this instant.

Method date#

silk
pub fn date(self: Self) -> PlainDate

Returns the date that a calendar in the zone shows at this instant.

Method time#

silk
pub fn time(self: Self) -> PlainTime

Returns the time of day that a clock in the zone shows at this instant.

Method abbreviation#

silk
pub fn abbreviation(self: Self) -> string

Returns the abbreviation of the zone at this instant, such as CET or -03.

Method isDaylight#

silk
pub fn isDaylight(self: Self) -> bool

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

Method withZone#

silk
pub fn withZone<'other>(self: Self, zone: &'other Zone) -> ZonedDateTime<'other>

Returns the same instant as seen in zone.

Method withLocal#

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

Method startOfDay#

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

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

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

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

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

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

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

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

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

silk
pub fn periodUntil<'other>(self: Self, other: ZonedDateTime<'other>, largest: DateUnit) -> Period

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

silk
pub fn since<'other>(self: Self, earlier: ZonedDateTime<'other>) -> Duration

Returns the exact time from earlier to this value. It is negative if earlier is later. The zones do not matter.

Method until#

silk
pub fn until<'other>(self: Self, later: ZonedDateTime<'other>) -> Duration

Returns the exact time from this value to later. It is negative if later is earlier. The zones do not matter.

Method write#

silk
pub fn write(self: Self, output: &mut [u8], at: usize) -> usize

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

silk
impl<'z> Equal for ZonedDateTime<'z>

Operation equals#

silk
equals: ZonedDateTime.same

Implementation Add<Duration, ZonedDateTime<'z>> for ZonedDateTime<'z>#

silk
impl<'z> Add<Duration, ZonedDateTime<'z>> for ZonedDateTime<'z>

Operation add#

silk
add: ZonedDateTime.addOperator

Implementation Subtract<Duration, ZonedDateTime<'z>> for ZonedDateTime<'z>#

silk
impl<'z> Subtract<Duration, ZonedDateTime<'z>> for ZonedDateTime<'z>

Operation subtract#

silk
subtract: ZonedDateTime.subtractOperator

Implementation Subtract<ZonedDateTime<'z>, Duration> for ZonedDateTime<'z>#

silk
impl<'z> Subtract<ZonedDateTime<'z>, Duration> for ZonedDateTime<'z>

Operation subtract#

silk
subtract: ZonedDateTime.differenceOperator

Implementation Display for ZonedDateTime<'z>#

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

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

Implementation Debug for ZonedDateTime<'z>#

silk
impl<'z> Debug for ZonedDateTime<'z>

Writes the same text as Display.

Operation debug#

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

ZonedText#

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

silk
impl<'text> Copy for ZonedText<'text>

Implementation ZonedText<'text>#

silk
impl<'text> ZonedText<'text>

Associated function parse#

silk
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.MissingZone if the text has no time zone annotation.

  • TimeParseReason.UnexpectedCharacter if 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#

silk
pub fn parseBytes(bytes: &'text [u8]) -> Result<ZonedText<'text>, TimeParseError>

Reads the parts of RFC 9557 text from bytes. See ZonedText.parse.

Errors#

Method zoneName#

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

silk
pub fn dateTime(self: Self) -> PlainDateTime

Returns the local date and time of the text. The time is midnight when the text has none.

Method hasTime#

silk
pub fn hasTime(self: Self) -> bool

Returns true if the text has a time of day.

Method isUtc#

silk
pub fn isUtc(self: Self) -> bool

Returns true if the text has the UTC designator Z.

Method offset#

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

View the source of this page