std/time

A monotonic stopwatch. Construct with start(), read elapsed time with stop(). Cheap to copy (it holds a single zero-cost Monotonic).

Wall-clock instant: nanoseconds since the Unix epoch (1970-01-01 UTC). Suitable for formatting, persistence, and absolute-time comparisons. NOT suitable for measuring elapsed time : the wall clock can jump forwards or backwards (NTP corrections, manual clock adjustments, daylight-saving when the OS exposes local time). Use Monotonic for elapsed measurements.

Monotonic instant: nanoseconds since an opaque, process-stable epoch. Guaranteed never to decrease across observations within a single process. Use for micro-benchmarks, timeouts, deadlines, and any elapsed-time measurement. NOT comparable across processes ; NOT convertible to wall-clock time.

Signed time interval with nanosecond precision. May be negative (e.g. b - a when b < a). Range : ±~292 years (i64 ns).

Error returned by parse_iso8601 when the input doesn't conform to the supported subset of ISO 8601.

Start a stopwatch from the current monotonic instant.

Elapsed Duration since the stopwatch was started. Re-reads the monotonic clock on every call, so repeated stop()s report time since start(), not since the previous stop() ; the stopwatch is never consumed.

Construct a Duration from a count of nanoseconds.

Construct a Duration from a count of microseconds.

Construct a Duration from a count of milliseconds.

Construct a Duration from a count of seconds.

Current wall-clock time. Reads the host clock: successive calls may observe non-monotonic jumps (NTP, manual adjustments).

Current monotonic instant. Never decreases across calls within a single process.

Construct a wall-clock Instant from a Unix-epoch nanosecond count (nanoseconds since 1970-01-01 UTC ; negative for pre-epoch instants). The inverse of to_unix_nanos. Use for deterministic timestamps that don't come from the host clock.

Unix-epoch nanoseconds for this Instant (since 1970-01-01 UTC ; negative for pre-epoch). The inverse of from_unix_nanos.

Elapsed time since self, measured against the current monotonic clock. The contract is one-directional : self must come from monotonic(). Returns a non-negative Duration in normal operation.

UFCS-callable as start.since().

Whole nanoseconds.

Whole microseconds (truncated towards zero).

Whole milliseconds (truncated towards zero).

Whole seconds (truncated towards zero).

Format a Duration in the most readable unit (ns, µs, ms, or s) such that the integer part is non-empty and < 1000. Picks the largest unit that fits. Negative durations are formatted with a leading -.

Format an Instant as an ISO 8601 timestamp in UTC with millisecond precision, e.g. "2026-05-15T12:34:56.789Z". Years before 0001 or after 9999 are still formatted but the year field widens beyond four digits (no truncation).

Sub-millisecond nanosecond detail is intentionally dropped: the MVP host clock only provides millisecond resolution for the wall clock, and emitting trailing zero-noise would mislead the reader.

Parse an ISO 8601 wall-clock timestamp into an Instant. The accepted shape is YYYY-MM-DDTHH:MM:SS[.fff]Z (UTC only ; the trailing Z is required, fractional seconds are optional and truncated to milliseconds when present). The mirror of format_iso8601.