Duration

Duration :: # (opaque)

A non-negative length of time with nanosecond resolution.

Build one from a unit, Duration.seconds(5), and pass it wherever a timeout or a wait is expected. Durations support +, -, == and the ordering operators, and sort with List.sort.

Every result is clamped to what a Duration can hold: zero at the low end and U64.highest nanoseconds (about 584 years) at the high end. Nothing here crashes on overflow, so a - b is Duration.zero when b is longer than a.

zero : Duration

The empty duration. A timeout of Duration.zero expires immediately.

nanos : U64 -> Duration

A duration of the given number of nanoseconds.

millis : U64 -> Duration

A duration of the given number of milliseconds, clamped to the longest representable duration.

seconds : U64 -> Duration

A duration of the given number of seconds, clamped to the longest representable duration.

minutes : U64 -> Duration

A duration of the given number of minutes, clamped to the longest representable duration.

to_nanos : Duration -> U64

The length of this duration in nanoseconds.

to_millis : Duration -> U64

The length of this duration in whole milliseconds, truncating any remainder: 1999 microseconds is 1 millisecond.

to_seconds : Duration -> U64

The length of this duration in whole seconds, truncating any remainder.

to_str : Duration -> Str

Format this duration for people, in the largest unit that fits: nanoseconds below a millisecond ("999ns"), whole milliseconds below a second ("250ms"), then seconds with up to three decimals ("1.5s", "10800s"). Digits past the unit's precision are truncated, not rounded.

to_inspect : Duration -> Str

How Str.inspect renders a duration: Duration(1.5s).

sleep! : Duration => {}

Pause the current process for this duration.

Use this for a wait that was computed, such as interval.minus(start.elapsed!()).sleep!(); Sleep.millis!(250) reads better for a literal one. Duration.zero returns immediately.

plus : Duration, Duration -> Duration

Add two durations (a + b), clamped to the longest representable duration.

minus : Duration, Duration -> Duration

Subtract one duration from another (a - b), giving Duration.zero when b is the longer one.

This gives several timed operations one budget: budget - start.elapsed!() is the time left, and is zero once the budget is spent.

is_eq : _

Compare two durations for equality (== and !=).

is_lt : Duration, Duration -> Bool

Whether the first duration is shorter than the second (<).

is_lte : Duration, Duration -> Bool

Whether the first duration is no longer than the second (<=).

is_gt : Duration, Duration -> Bool

Whether the first duration is longer than the second (>).

is_gte : Duration, Duration -> Bool

Whether the first duration is at least as long as the second (>=).

order_relative_to : Duration, Duration -> [Before, Same, After]

Order two durations, shortest first. This is what List.sort and List.sort_by use.