Reference

std/time/lib

std/time/src/lib.trb

Wall-clock time: points in time (Instant) and the spans between them (Duration).

Both are a count of nanoseconds in an Int64 and nothing else, so they cost what the number costs: comparing and subtracting them is integer arithmetic, and only reading the clock goes to the operating system.

type Instant

type Instant with Compare, Subtract<Instant, Duration>, Add<Duration, Instant>

A point in time. Only differences between two Instants are meaningful, never the value on its own: it is a monotonic reading whose origin is chosen by the process.

Examples

const start = Clock.now()
const later = start + 2.seconds()
print(later - start)

Related

  • Clock.now - where an Instant comes from.
  • Duration - what the difference of two of them is.

fn compare

fn compare(other: Instant): Ordering

Which of the two readings came first.

fn subtract

fn subtract(other: Instant): Duration

The span from other to this reading: negative where other is the later one.

fn add

fn add(other: Duration): Instant

The point in time other after this one: a deadline, Clock.now() + 2.seconds().

type Duration

type Duration with Compare, Show, Add, Subtract

The span between two Instants, or a length of time asked for on its own (2.seconds()). It is signed: the difference of two readings taken the wrong way round is negative.

Examples

const wait = 2.seconds() + 500.milliseconds()
print wait
print(wait > 2.seconds())

Related

fn seconds

fn seconds(): Float64

As a fractional number of seconds: (Clock.now() - start).seconds().

fn nanoseconds

fn nanoseconds(): Int64

As a whole number of nanoseconds, which is exactly what it holds.

fn compare

fn compare(other: Duration): Ordering

Which of the two spans is the shorter one.

fn add

fn add(other: Duration): Duration

The two spans one after the other. Panics where the sum does not fit, as every Int64 addition does.

fn subtract

fn subtract(other: Duration): Duration

How much longer this span is than other: negative where it is shorter.

fn show

fn show(): String

The seconds with an s behind them: 2.5s.

type Timestamp

type Timestamp with Compare, Equals, Hash, Show, Subtract<Timestamp, Duration>, Add<Duration, Timestamp>

A point on the wall clock: nanoseconds since 1970-01-01 00:00:00 UTC. It means something on its own - when a file was last written - where an Instant only means something against another reading; and it can jump, because the clock of a machine is set.

Examples

const written = Timestamp.fromUnixNanoseconds 1_790_000_000_500_000_000
print written
print(written + 2.seconds())
// prints 2026-09-21T14:13:20.5Z
// prints 2026-09-21T14:13:22.5Z

Related

  • Instant - the monotonic reading, for measuring.
  • Duration - what the difference of two of them is.

fn fromUnixNanoseconds

static fn fromUnixNanoseconds(nanoseconds: Int64): Self

The point in time nanoseconds after 1970-01-01 00:00:00 UTC - before it, where the number is negative.

fn unixNanoseconds

fn unixNanoseconds(): Int64

Nanoseconds since 1970-01-01 00:00:00 UTC, which is exactly what it holds.

fn compare

fn compare(other: Self): Ordering

Which of the two points in time came first.

fn subtract

fn subtract(other: Self): Duration

The span from other to this one: negative where other is the later one.

fn add

fn add(other: Duration): Self

The point in time other after this one.

fn show

fn show(): String

RFC 3339 in UTC: 2026-09-27T08:15:00Z, with as many digits of the second's fraction as it has and none where it has none (08:15:00.25Z).

extend Int64

extend Int64

The short way to write a Duration: 2.seconds() instead of a constructor.

fn seconds

fn seconds(): Duration

A Duration of this many seconds: 2.seconds(). Mainly for sandbox and task limits. More than about 292 years either way do not fit into the nanoseconds, and the Int64 multiplication under it panics then.

fn milliseconds

fn milliseconds(): Duration

A Duration of this many milliseconds: 250.milliseconds(). The Int64 multiplication under it panics where they do not fit into the nanoseconds.

type Clock

native type Clock

The wall clock. Needs the std/time capability inside a sandboxed script.

fn now

static fn now(): Instant

The current point in time.

fn milliseconds

native static fn milliseconds(): Int64

Monotonic milliseconds, counted from the first reading. Only differences between two readings are meaningful, as for an Instant - this is the form a tool that measures its own work wants (torb check --timings), where a reading in milliseconds is the unit it prints.

fn sleep

native fn sleep(seconds: Float64): Task<Void>

Suspends the running task for this many seconds. Needs .await(), like every Task.