silk.time.instant.

Points in time: the Instant type, a moment on the UTC timeline with nanosecond precision.

When to use#

Use Instant for when something happened or will happen, the same for every observer: a timestamp in a log, an expiry, the time a file changed. SystemClock.now in silk.system.system_clock reads the current one. To show an instant to a person, convert it with Instant.toUtc or Instant.toOffset.

Details#

An Instant counts seconds and nanoseconds from the Unix epoch, 1970-01-01T00:00:00Z, and ignores leap seconds, as Unix time does. The range is 100 million days in each direction, -271821-04-20T00:00:00Z to +275760-09-13T00:00:00Z, the range of ECMAScript Temporal.

instant + duration and instant - duration move along the timeline, and instant - instant gives the Duration between two points.

Examples#

Parse a timestamp, add a span, and print it#

silk
import silk.core.result { Result }
import silk.time.duration { Duration }
import silk.time.instant { Instant }
import silk.time.text { TimeParseError }

pub fn main() -> i32 {
  match Instant.parse("2026-11-19T18:36:22+01:00") {
    Result<Instant, TimeParseError>.Success { value } => {
      if value.unixSeconds() != 1795109782 {
        return 1
      }
      let later = value + Duration.fromHours(7)
      let reading = later.toUtc()
      if reading.date().day() != 20 || reading.time().hour() != 0 {
        return 2
      }
      if &(later - value) != &Duration.fromSeconds(25200) {
        return 3
      }
      return 0
    }
    Result<Instant, TimeParseError>.Failure { error: _ } => {
      return 4
    }
  }
}

Import as Instant with import silk.time.instant { Instant }.

Public declarations: 1.

Instant#

silk
pub struct Instant

A point on the UTC timeline with nanosecond precision.

Details#

The value is whole seconds since 1970-01-01T00:00:00Z, rounded toward negative infinity, and a nanosecond part from 0 to 999,999,999 that counts forward, also before 1970. Leap seconds are not counted, as in Unix time. The range is -271821-04-20T00:00:00Z to +275760-09-13T00:00:00Z.

==, !=, <, <=, >, and >= compare positions on the timeline. + and - with a Duration move the instant and trap when the result is outside the range. - between two instants gives a Duration. Display writes the reading in UTC with the suffix Z.

Implementation Copy for Instant#

silk
impl Copy for Instant

Implementation Instant#

silk
impl Instant

Associated function make#

silk
pub fn make(seconds: i64, nanoseconds: i64) -> Instant

Returns the instant seconds seconds plus nanoseconds nanoseconds after the Unix epoch.

Details#

Whole seconds in nanoseconds move into the seconds, and both arguments can be negative. So Instant.make(0, 5000000000) is five seconds after the epoch and Instant.make(0, -1) is one nanosecond before it.

Gotchas#

An instant outside the range traps. Instant.checkedMake returns None instead.

Associated function checkedMake#

silk
pub fn checkedMake(seconds: i64, nanoseconds: i64) -> Option<Instant>

Returns the instant seconds seconds plus nanoseconds nanoseconds after the Unix epoch, or None when it is outside -271821-04-20T00:00:00Z to +275760-09-13T00:00:00Z.

Details#

Whole seconds in nanoseconds move into the seconds, and both arguments can be negative.

Associated function epoch#

silk
pub fn epoch() -> Instant

Returns the Unix epoch, 1970-01-01T00:00:00Z.

Associated function min#

silk
pub fn min() -> Instant

Returns the first instant of the range, -271821-04-20T00:00:00Z.

Associated function max#

silk
pub fn max() -> Instant

Returns the last instant of the range, +275760-09-13T00:00:00Z.

Associated function fromUnixSeconds#

silk
pub fn fromUnixSeconds(seconds: i64) -> Instant

Returns the instant seconds seconds after the Unix epoch, or before it for a negative count.

Gotchas#

An instant outside the range traps. Instant.checkedMake returns None instead.

Associated function fromUnixMilliseconds#

silk
pub fn fromUnixMilliseconds(milliseconds: i64) -> Instant

Returns the instant milliseconds milliseconds after the Unix epoch, or before it for a negative count.

Gotchas#

An instant outside the range traps.

Associated function fromUnixMicroseconds#

silk
pub fn fromUnixMicroseconds(microseconds: i64) -> Instant

Returns the instant microseconds microseconds after the Unix epoch, or before it for a negative count.

Gotchas#

An instant outside the range traps.

Associated function fromUnixNanoseconds#

silk
pub fn fromUnixNanoseconds(nanoseconds: i64) -> Instant

Returns the instant nanoseconds nanoseconds after the Unix epoch, or before it for a negative count. Each i64 value is in range: it covers the years 1677 to 2262.

Method unixSeconds#

silk
pub fn unixSeconds(self: Self) -> i64

Returns the whole seconds since the Unix epoch, rounded toward negative infinity.

Details#

The instant is this value plus Instant.subsecondNanoseconds. Half a second before the epoch has -1 whole seconds and a nanosecond part of 500,000,000.

Method subsecondNanoseconds#

silk
pub fn subsecondNanoseconds(self: Self) -> u32

Returns the nanosecond part of the instant, from 0 to 999,999,999.

Details#

The part counts forward from Instant.unixSeconds, also before the epoch.

Method unixMilliseconds#

silk
pub fn unixMilliseconds(self: Self) -> i64

Returns the whole milliseconds since the Unix epoch, rounded toward negative infinity.

Method unixMicroseconds#

silk
pub fn unixMicroseconds(self: Self) -> i64

Returns the whole microseconds since the Unix epoch, rounded toward negative infinity.

Method unixNanoseconds#

silk
pub fn unixNanoseconds(self: Self) -> Option<i64>

Returns the nanoseconds since the Unix epoch, or None when the count does not fit an i64, which is the case before the year 1677 and after the year 2262.

Method checkedAdd#

silk
pub fn checkedAdd(self: Self, span: Duration) -> Option<Instant>

Returns the instant span later, or earlier for a negative span, or None when it is outside the range.

Method checkedSubtract#

silk
pub fn checkedSubtract(self: Self, span: Duration) -> Option<Instant>

Returns the instant span earlier, or later for a negative span, or None when it is outside the range.

Method round#

silk
pub fn round(self: Self, step: TimeIncrement, mode: RoundingMode) -> Instant

Returns the instant rounded to a multiple of step, counted from the Unix epoch.

Details#

The steps are those of the time of day in UTC. An instant is a point and not an amount, so "away from zero" means later in time, also before 1970: RoundingMode.Expand rounds as Ceil and HalfExpand as HalfCeil.

Gotchas#

A result outside the range traps. Instant.checkedRound returns None instead.

Examples#

silk
import silk.time.instant { Instant }
import silk.time.rounding { RoundingMode, TimeIncrement, TimeUnit }

pub fn main() -> i32 {
  let at = Instant.make(1795000000, 250000000)
  let second = at.round(TimeIncrement.one(TimeUnit.Second), RoundingMode.HalfExpand)
  if second.unixSeconds() != 1795000000 || second.subsecondNanoseconds() != 0 {
    return 1
  }
  let hour = at.round(TimeIncrement.one(TimeUnit.Hour), RoundingMode.Ceil)
  if hour.unixSeconds() != 1795003200 {
    return 2
  }
  return 0
}

Method checkedRound#

silk
pub fn checkedRound(self: Self, step: TimeIncrement, mode: RoundingMode) -> Option<Instant>

Returns the instant rounded to a multiple of step, counted from the Unix epoch, or None when the result is outside the range.

Method since#

silk
pub fn since(self: Self, earlier: Instant) -> Duration

Returns the span from earlier to this instant. It is negative when earlier is later.

Method until#

silk
pub fn until(self: Self, later: Instant) -> Duration

Returns the span from this instant to later. It is negative when later is earlier.

Method toUtc#

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

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

Method toOffset#

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

Returns the date and time that a clock offset ahead of UTC shows at this instant.

Associated function fromUtc#

silk
pub fn fromUtc(reading: PlainDateTime) -> Option<Instant>

Returns the instant at which a clock in UTC shows reading, or None when it is outside the range.

Associated function fromLocal#

silk
pub fn fromLocal(reading: PlainDateTime, offset: UtcOffset) -> Option<Instant>

Returns the instant at which a clock offset ahead of UTC shows reading, or None when it is outside the range.

Associated function fromUtcFields#

silk
pub fn fromUtcFields(year: i32, month: u8, day: u8, hour: u8, minute: u8, second: u8) -> Option<Instant>

Returns the instant at which a clock in UTC shows the given date and time, or None when a field does not exist, such as month 13, February 30, or hour 24, or when the instant is outside the range.

Associated function parse#

silk
pub fn parse(text: string) -> Result<Instant, TimeParseError>

Reads an instant from RFC 3339 or ISO 8601 text such as 2026-11-19T17:36:22.5Z.

Details#

The text is a date, YYYY-MM-DD or YYYYMMDD, then T, t, or a space, then a time: HH, HH:MM, HH:MM:SS, HHMM, or HHMMSS, with an optional fraction of one to nine digits, then Z or a numeric offset such as +01:00. Second 60 reads as 59. Bracketed annotations can follow, as in 2026-11-19T18:36:22+01:00[Europe/Rome]. They are checked and then ignored: the offset alone decides the instant.

Errors#

  • TimeParseReason.UnexpectedEnd or UnexpectedCharacter if the text does not have that form.

  • TimeParseReason.OutOfRange if a field names no real value, such as month 13 or hour 24, or the instant is outside the range.

  • TimeParseReason.MissingTime if the text has no time of day.

  • TimeParseReason.MissingOffset if the text has neither Z nor a numeric offset.

  • TimeParseReason.UnsupportedCalendar if a calendar annotation is not [u-ca=iso8601].

  • TimeParseReason.UnknownCriticalAnnotation if an annotation with an unknown key starts with !.

Associated function parseBytes#

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

Reads an instant from the bytes of RFC 3339 or ISO 8601 text such as 2026-11-19T17:36:22.5Z.

Details#

The text is a date, YYYY-MM-DD or YYYYMMDD, then T, t, or a space, then a time: HH, HH:MM, HH:MM:SS, HHMM, or HHMMSS, with an optional fraction of one to nine digits, then Z or a numeric offset such as +01:00. Second 60 reads as 59. Bracketed annotations can follow. They are checked and then ignored: the offset alone decides the instant.

Errors#

  • TimeParseReason.UnexpectedEnd or UnexpectedCharacter if the text does not have that form.

  • TimeParseReason.OutOfRange if a field names no real value, such as month 13 or hour 24, or the instant is outside the range.

  • TimeParseReason.MissingTime if the text has no time of day.

  • TimeParseReason.MissingOffset if the text has neither Z nor a numeric offset.

  • TimeParseReason.UnsupportedCalendar if a calendar annotation is not [u-ca=iso8601].

  • TimeParseReason.UnknownCriticalAnnotation if an annotation with an unknown key starts with !.

Method writeUtc#

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

Writes the instant as the reading in UTC with the suffix Z, as in 2026-11-19T17:36:22Z, at output[at], and returns the offset after it.

Details#

The text is valid RFC 3339 for the years 0 to 9999. It has a fraction, without zeros at the end, when the nanosecond part is not zero. It is at most 33 bytes.

Method writeWithOffset#

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

Writes the instant as the reading of a clock offset ahead of UTC, followed by that offset, as in 2026-11-19T18:36:22+01:00, at output[at], and returns the offset after it.

Details#

The text is valid RFC 3339 for the years 0 to 9999 when the offset has no seconds part. The zero offset is written +00:00. The text is at most 41 bytes.

Implementation Equal for Instant#

silk
impl Equal for Instant

Operation equals#

silk
equals: Instant.same

Implementation Order for Instant#

silk
impl Order for Instant

Operation compare#

silk
compare: Instant.compare

Implementation Add<Duration, Instant> for Instant#

silk
impl Add<Duration, Instant> for Instant

Operation add#

silk
add: Instant.addOperator

Implementation Subtract<Duration, Instant> for Instant#

silk
impl Subtract<Duration, Instant> for Instant

Operation subtract#

silk
subtract: Instant.subtractOperator

Implementation Subtract<Instant, Duration> for Instant#

silk
impl Subtract<Instant, Duration> for Instant

Operation subtract#

silk
subtract: Instant.differenceOperator

Implementation Display for Instant#

silk
impl Display for Instant

Writes the instant as the reading in UTC with the suffix Z, as in 2026-11-19T17:36:22Z or 2026-11-19T17:36:22.5Z.

Operation display#

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

Implementation Debug for Instant#

silk
impl Debug for Instant

Writes the same text as Display: the reading in UTC with the suffix Z.

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