Skip to content

std::instant

Import with import std::instant.

Types

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
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
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
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
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
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
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)
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))

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

impl Debug for Instant

fn inspect(value: Instant) -> String

impl Debug.inspect

impl Equatable for Instant

fn equal(a: Instant, b: Instant) -> Bool

impl Equatable.equal