std/duration

Import with import std/duration.

Exports

Types

• Duration

type Duration

type Duration Int

opaque — construction surface is private to its defining module

A length of time — a fixed span, independent of any wall clock or calendar. Backed by nanoseconds (opaque type Duration Int), so sub-second spans (timeouts, sleep intervals, elapsed measurements) compose precisely. Construct with unit functions (Duration.seconds(5), Duration.milliseconds(250)); inspect via the Duration.as_* accessors; combine via Duration.add, +, Duration.subtract, -, Duration.multiply, *, and /; compare via Comparable / ==.

Duration is a time-domain quantity and deliberately does not interact with Date; civil calendar and wall-clock arithmetic use Civil.* period types from std/calendar. It pairs with Instant (Instant.add / Instant.between) and backs Timer.sleep / Context.with_timeout.

Duration.nanoseconds

fn nanoseconds(n: Int): Duration

type function on Duration

Construct a Duration from whole nanoseconds.

Interactive Tests

assert Duration.as_nanos(Duration.nanoseconds(42)) == 42

Duration.microseconds

fn microseconds(n: Int): Duration

type function on Duration

Construct a Duration from whole microseconds.

Interactive Tests

assert Duration.to_string(Duration.microseconds(1)) == "1µs"
assert Duration.as_nanos(Duration.microseconds(2)) == 2000

Duration.milliseconds

fn milliseconds(n: Int): Duration

type function on Duration

Construct a Duration from whole milliseconds.

Interactive Tests

assert Duration.as_millis(Duration.milliseconds(1500)) == 1500

Duration.seconds

fn seconds(n: Int): Duration

type function on Duration

Construct a Duration from whole seconds.

Interactive Tests

assert Duration.as_seconds(Duration.seconds(5)) == 5
assert Duration.seconds(5) == Duration.milliseconds(5000)

Duration.minutes

fn minutes(n: Int): Duration

type function on Duration

Construct a Duration from whole minutes.

Interactive Tests

assert Duration.as_seconds(Duration.minutes(3)) == 180

Duration.hours

fn hours(n: Int): Duration

type function on Duration

Construct a Duration from whole hours.

Interactive Tests

assert Duration.to_string(Duration.hours(1)) == "1h"

Duration.as_nanos

fn as_nanos(Duration(ns)): Int

type function on Duration

Total whole nanoseconds in the Duration (the exact magnitude).

Interactive Tests

assert Duration.as_nanos(Duration.microseconds(2)) == 2000

Duration.as_micros

fn as_micros(Duration(ns)): Int

type function on Duration

Total whole microseconds, truncating any sub-microsecond remainder.

Interactive Tests

assert Duration.as_micros(Duration.milliseconds(2)) == 2000

Duration.as_millis

fn as_millis(Duration(ns)): Int

type function on Duration

Total whole milliseconds, truncating any sub-millisecond remainder.

Interactive Tests

assert Duration.as_millis(Duration.seconds(2)) == 2000

Duration.as_seconds

fn as_seconds(Duration(ns)): Int

type function on Duration

Total whole seconds, truncating any sub-second remainder.

Interactive Tests

assert Duration.as_seconds(Duration.minutes(3)) == 180

Duration.as_minutes

fn as_minutes(Duration(ns)): Int

type function on Duration

Total whole minutes, truncating any sub-minute remainder.

Interactive Tests

assert Duration.as_minutes(Duration.hours(2)) == 120

Duration.as_hours

fn as_hours(Duration(ns)): Int

type function on Duration

Total whole hours, truncating any sub-hour remainder.

Interactive Tests

assert Duration.as_hours(Duration.minutes(150)) == 2

Duration.add

impl Add

fn add(Duration(a), Duration(b)): Duration

impl Add.add

Sum of two Durations.

Interactive Tests

assert Duration.add(
  Duration.seconds(1),
  Duration.milliseconds(500),
) == Duration.milliseconds(1500)
assert Duration.seconds(1) + Duration.milliseconds(
  500
) == Duration.milliseconds(1500)

Duration.subtract

impl Subtract

fn subtract(Duration(a), Duration(b)): Duration

impl Subtract.subtract

Difference of two Durations (the first minus the second); may be negative.

Interactive Tests

assert Duration.subtract(
  Duration.seconds(1),
  Duration.seconds(3),
) == Duration.seconds(-2)
assert Duration.seconds(1) - Duration.seconds(3) == Duration.seconds(-2)

Duration.multiply

impl Multiply

fn multiply(Duration(ns), rhs: Int): Duration

impl Multiply.multiply

Multiply a Duration by an integer factor.

Interactive Tests

assert Duration.multiply(Duration.seconds(2), 3) == Duration.seconds(6)
assert Duration.seconds(2) * 3 == Duration.seconds(6)

Duration.divide

impl Divide

fn divide(Duration(ns), rhs: Int): Duration

impl Divide.divide

Divide a Duration by an integer divisor.

Interactive Tests

assert Duration.seconds(6) / 3 == Duration.seconds(2)

Duration.to_string

impl Display

fn to_string(d: Duration): String

impl Display.to_string

Compact, human-readable rendering — decomposes into the largest units that fit (e.g. 1h30m, 250ms).

Interactive Tests

assert Duration.to_string(Duration.seconds(5)) == "5s"
assert Duration.to_string(Duration.milliseconds(1500)) == "1s500ms"
assert Duration.to_string(Duration.minutes(90)) == "1h30m"
assert Duration.to_string(Duration.nanoseconds(0)) == "0s"

Duration.inspect

impl Debug

fn inspect(d: Duration): String

impl Debug.inspect

Interactive Tests

assert Duration.inspect(Duration.seconds(5)) == "5s"

Duration.equal?

impl Equatable

fn equal?(a: Duration, b: Duration): Bool

impl Equatable.equal?

Duration.hash

impl Hashable

fn hash(value: Duration): Int

impl Hashable.hash

Duration.compare

impl Comparable

fn compare(a: Duration, b: Duration): Ordering

impl Comparable.compare