std::instant
Import with import std::instant.
Exports
Section titled “Exports”Types
type Instant
Section titled “type Instant”type Instant Int
opaque — construction surface is private to its defining module
A point in time: a count of nanoseconds from the Unix epoch, 1970-01-01
00:00:00 UTC. Instant.now reads the clock. Instant.from_seconds and
Instant.from_nanos make an Instant from a count, and
Instant.to_seconds and Instant.as_nanos read the count back.
+ and - move an Instant by a Duration, and - between two
Instants is the Duration from the right one to the left one.
Instant.is_before compares two, and == tells whether they are the
same nanosecond.
The count is an Int of any size, as a Duration’s is, so every one
of these functions returns for every value and none can fail. Go
counts a time in a signed 64-bit number of nanoseconds, the years 1677
to 2262. A std function that hands an Instant to Go says what one
outside those years means there: a deadline past 2262 never comes, and
a timestamp written out is clamped to the nearest end or refused.
start = Instant.from_seconds(1_700_000_000)
later = start + Duration.minutes(90)
assert later - start == Duration.minutes(90)
assert Instant.is_before(start, later)
assert Instant.to_seconds(later) == 1_700_005_400
Instant.now
Section titled “Instant.now”fn now() -> Instant
type function on Instant
The time now, read from the system clock at nanosecond precision.
Instant.to_seconds(Instant.now()) is the Unix timestamp in whole
seconds. The system clock can be set back, so a later call may
return an earlier Instant.
Subtract an earlier reading to time a step:
took = Instant.now() - started
Instant.from_seconds
Section titled “Instant.from_seconds”fn from_seconds(n: Int) -> Instant
type function on Instant
The Instant n whole seconds after the Unix epoch, before it for a
negative n.
assert Instant.to_seconds(Instant.from_seconds(42)) == 42
assert Instant.to_seconds(Instant.from_seconds(10_000_000_000)) == 10_000_000_000
Instant.to_seconds
Section titled “Instant.to_seconds”fn to_seconds(Instant(nanos)) -> Int
type function on Instant
The whole seconds from the Unix epoch to the Instant, the count
Instant.from_seconds takes. A part of a second is dropped, toward
the epoch: half a second before the epoch is second 0.
assert Instant.to_seconds(Instant.from_seconds(42)) == 42
assert Instant.to_seconds(Instant.from_nanos(1_999_999_999)) == 1
assert Instant.to_seconds(Instant.from_nanos(-500_000_000)) == 0
Instant.from_nanos
Section titled “Instant.from_nanos”fn from_nanos(n: Int) -> Instant
type function on Instant
The Instant n nanoseconds after the Unix epoch, before it for a
negative n. Instant.as_nanos reads the count back, so the pair
stores an Instant with nothing lost; Instant.to_seconds drops the
part of a second that Instant.now reads.
assert Instant.as_nanos(Instant.from_nanos(1_500_000_042)) == 1_500_000_042
assert Instant.as_nanos(Instant.from_nanos(-9_223_372_036_854_775_809))
== -9_223_372_036_854_775_809
Instant.as_nanos
Section titled “Instant.as_nanos”fn as_nanos(Instant(nanos)) -> Int
type function on Instant
The nanoseconds from the Unix epoch to the Instant, negative for one
before it: the count Instant.from_nanos takes. Nothing is dropped,
where Instant.to_seconds drops the part of a second.
assert Instant.as_nanos(Instant.from_seconds(42)) == 42_000_000_000
Instant.between
Section titled “Instant.between”fn between(Instant(earlier), Instant(later)) -> Duration
type function on Instant
The Duration from earlier to later, which is later - earlier.
It is negative when later is the earlier of the two.
assert Instant.between(Instant.from_seconds(10), Instant.from_seconds(15)) == Duration.seconds(5)
assert Instant.between(Instant.from_seconds(15), Instant.from_seconds(10)) == Duration.seconds(-5)
Instant.is_before
Section titled “Instant.is_before”fn is_before(Instant(a), Instant(b)) -> Bool
type function on Instant
Whether a is earlier than b. Two equal Instants are not before
each other.
assert Instant.is_before(Instant.from_seconds(10), Instant.from_seconds(15))
refute Instant.is_before(Instant.from_seconds(15), Instant.from_seconds(10))
refute Instant.is_before(Instant.from_seconds(10), Instant.from_seconds(10))
Instant.add
Section titled “Instant.add”impl Add<Duration, Instant> for Instant
fn add(Instant(nanos), rhs: Duration) -> Instant
impl Add.add
instant + duration: the Instant that long after instant, or
before it for a negative Duration. An Instant has no largest value,
so the sum always exists.
assert Instant.from_seconds(10) + Duration.seconds(5) == Instant.from_seconds(15)
assert Instant.to_seconds(Instant.from_seconds(0) + Duration.hours(3_000_000)) == 10_800_000_000
Instant.subtract Subtract<Duration, Instant>
Section titled “Instant.subtract Subtract<Duration, Instant>”impl Subtract<Duration, Instant> for Instant
fn subtract(Instant(nanos), rhs: Duration) -> Instant
impl Subtract.subtract
instant - duration: the Instant that long before instant.
assert Instant.from_seconds(15) - Duration.seconds(5) == Instant.from_seconds(10)
Instant.subtract Subtract<Instant, Duration>
Section titled “Instant.subtract Subtract<Instant, Duration>”impl Subtract<Instant, Duration> for Instant
fn subtract(lhs: Instant, rhs: Instant) -> Duration
impl Subtract.subtract
a - b: the Duration from b to a, which is
Instant.between(b, a). It is negative when a is before b.
assert Instant.from_seconds(15) - Instant.from_seconds(10) == Duration.seconds(5)
assert Instant.from_seconds(10) - Instant.from_seconds(15) == Duration.seconds(-5)
earliest = Instant.from_nanos(-9_223_372_036_854_775_808)
latest = Instant.from_nanos(9_223_372_036_854_775_807)
assert Duration.as_hours(latest - earliest) == 5_124_095
Instant.inspect
Section titled “Instant.inspect”impl Debug for Instant
fn inspect(value: Instant) -> String
impl Debug.inspect
Instant.equal
Section titled “Instant.equal”impl Equatable for Instant
fn equal(a: Instant, b: Instant) -> Bool
impl Equatable.equal