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#
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#
pub struct InstantA 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#
impl Copy for InstantImplementation Instant#
impl InstantAssociated function make#
pub fn make(seconds: i64, nanoseconds: i64) -> InstantReturns 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#
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#
pub fn epoch() -> InstantReturns the Unix epoch, 1970-01-01T00:00:00Z.
Associated function min#
pub fn min() -> InstantReturns the first instant of the range, -271821-04-20T00:00:00Z.
Associated function max#
pub fn max() -> InstantReturns the last instant of the range, +275760-09-13T00:00:00Z.
Associated function fromUnixSeconds#
pub fn fromUnixSeconds(seconds: i64) -> InstantReturns 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#
pub fn fromUnixMilliseconds(milliseconds: i64) -> InstantReturns 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#
pub fn fromUnixMicroseconds(microseconds: i64) -> InstantReturns 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#
pub fn fromUnixNanoseconds(nanoseconds: i64) -> InstantReturns 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#
pub fn unixSeconds(self: Self) -> i64Returns 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#
pub fn subsecondNanoseconds(self: Self) -> u32Returns 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#
pub fn unixMilliseconds(self: Self) -> i64Returns the whole milliseconds since the Unix epoch, rounded toward negative infinity.
Method unixMicroseconds#
pub fn unixMicroseconds(self: Self) -> i64Returns the whole microseconds since the Unix epoch, rounded toward negative infinity.
Method unixNanoseconds#
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#
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#
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#
pub fn round(self: Self, step: TimeIncrement, mode: RoundingMode) -> InstantReturns 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#
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#
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#
pub fn since(self: Self, earlier: Instant) -> DurationReturns the span from earlier to this instant. It is negative when earlier is later.
Method until#
pub fn until(self: Self, later: Instant) -> DurationReturns the span from this instant to later. It is negative when later is earlier.
Method toUtc#
pub fn toUtc(self: Self) -> PlainDateTimeReturns the date and time that a clock in UTC shows at this instant.
Method toOffset#
pub fn toOffset(self: Self, offset: UtcOffset) -> PlainDateTimeReturns the date and time that a clock offset ahead of UTC shows at this instant.
Associated function fromUtc#
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#
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#
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#
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.UnexpectedEndorUnexpectedCharacterif the text does not have that form.TimeParseReason.OutOfRangeif a field names no real value, such as month 13 or hour 24, or the instant is outside the range.TimeParseReason.MissingTimeif the text has no time of day.TimeParseReason.MissingOffsetif the text has neitherZnor a numeric offset.TimeParseReason.UnsupportedCalendarif a calendar annotation is not[u-ca=iso8601].TimeParseReason.UnknownCriticalAnnotationif an annotation with an unknown key starts with!.
Associated function parseBytes#
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.UnexpectedEndorUnexpectedCharacterif the text does not have that form.TimeParseReason.OutOfRangeif a field names no real value, such as month 13 or hour 24, or the instant is outside the range.TimeParseReason.MissingTimeif the text has no time of day.TimeParseReason.MissingOffsetif the text has neitherZnor a numeric offset.TimeParseReason.UnsupportedCalendarif a calendar annotation is not[u-ca=iso8601].TimeParseReason.UnknownCriticalAnnotationif an annotation with an unknown key starts with!.
Method writeUtc#
pub fn writeUtc(self: Self, output: &mut [u8], at: usize) -> usizeWrites 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#
pub fn writeWithOffset(self: Self, offset: UtcOffset, output: &mut [u8], at: usize) -> usizeWrites 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#
impl Equal for InstantOperation equals#
equals: Instant.sameImplementation Order for Instant#
impl Order for InstantOperation compare#
compare: Instant.compareImplementation Add<Duration, Instant> for Instant#
impl Add<Duration, Instant> for InstantOperation add#
add: Instant.addOperatorImplementation Subtract<Duration, Instant> for Instant#
impl Subtract<Duration, Instant> for InstantOperation subtract#
subtract: Instant.subtractOperatorImplementation Subtract<Instant, Duration> for Instant#
impl Subtract<Instant, Duration> for InstantOperation subtract#
subtract: Instant.differenceOperatorImplementation Display for Instant#
impl Display for InstantWrites 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#
effect fn display(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterImplementation Debug for Instant#
impl Debug for InstantWrites the same text as Display: the reading in UTC with the suffix Z.
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.