Time.Duration

struct Duration

A length of time, held as NANOSECONDS.

A real type rather than an Int of milliseconds, because a bare number does not say which unit it is and every caller has to agree by convention. #7 will want timeouts, Http will want them, Terminal will want them, and the alternative is each module growing its own timeout_ms: Int that cannot be passed to the others.

The field is PRIVATE: a Duration is built through a constructor that names its unit, which is the whole point of having the type. Nanoseconds internally because a signed 64-bit count of them spans ~292 years, which is more than any duration needs, and because losing sub-millisecond precision would make the type useless for the timing code that wants it most.

let Duration.as_nanos (d: Duration): Int

Accessors, TRUNCATING toward zero the way / does: a duration of 1500 microseconds is 1 millisecond, not 2. Ask in the unit you care about rather than rounding one answer into another.

let Duration.as_micros (d: Duration): Int

The duration in microseconds, TRUNCATED toward zero. Use Duration.as_nanos when the remainder matters.

let Duration.as_millis (d: Duration): Int

The duration in milliseconds, TRUNCATED toward zero. Use Duration.as_nanos when the remainder matters.

let Duration.as_seconds (d: Duration): Int

The duration in whole seconds, TRUNCATED toward zero. Use Duration.as_nanos when the remainder matters.

let Duration.is_zero (d: Duration): Bool

Whether this is exactly no time. A negative duration is not zero.

let Duration.add (a: Duration) (b: Duration): Duration

Adds two durations.

let Duration.sub (a: Duration) (b: Duration): Duration

Subtracts b from a. The result may be negative, which is a legal duration and is what Time.between returns for two instants given the other way round.

let Duration.scale (d: Duration) (n: Int): Duration

Multiplies a duration by a whole number.

let Duration.negate (d: Duration): Duration

A duration can be NEGATIVE. sub may produce one, and refusing to represent it would only move the problem to every caller of sub. sleep treats a non-positive duration as no wait at all.

let Duration.compare (a: Duration) (b: Duration): Int

--- Comparison ---

Functions rather than <, because this checker offers ordered comparison on Int, Float and String and on nothing else -- a struct has no <. == works, since that is structural.

If ordered comparison ever reaches single-field wrappers, < starts working on a Duration for free and these stay as the spelling that always worked.

let Duration.lt (a: Duration) (b: Duration): Bool

Whether a is shorter than b.

Spelled out rather than <, because ordered comparison in this language works on Int, Float and String and not on structs. == does work, since that one is structural.

let Duration.le (a: Duration) (b: Duration): Bool

Whether a is no longer than b.

Spelled out rather than <, because ordered comparison in this language works on Int, Float and String and not on structs. == does work, since that one is structural.

let Duration.gt (a: Duration) (b: Duration): Bool

Whether a is longer than b.

Spelled out rather than <, because ordered comparison in this language works on Int, Float and String and not on structs. == does work, since that one is structural.

let Duration.ge (a: Duration) (b: Duration): Bool

Whether a is at least as long as b.

Spelled out rather than <, because ordered comparison in this language works on Int, Float and String and not on structs. == does work, since that one is structural.

let Duration.min (a: Duration) (b: Duration): Duration

The shorter of two durations.

let Duration.max (a: Duration) (b: Duration): Duration

The longer of two durations.