@std/time.ms#

Import each required symbol with import Name from "@std/time.ms".

Clock Interface#

A monotonic clock whose readings are suitable for measuring elapsed time.

interface Clock:
    fn now() -> Instant

Clock.now#

Returns the current reading of this monotonic clock. Readings are only comparable with others from the same clock and do not correspond to a calendar date.

fn now() -> Instant

Duration Native type#

A span of elapsed time.

type Duration:
    fn add(other: Duration) -> Duration:
    fn subtract(other: Duration) -> Duration:
    fn multiply(factor: Int) -> Duration:
    fn divide(divisor: Int) -> Duration:
    fn negate() -> Duration:
    fn abs() -> Duration:
    fn compare(other: Duration) -> Int:
    fn to_nanoseconds() -> Int:
    fn to_microseconds() -> Int:
    fn to_milliseconds() -> Int:
    fn to_seconds() -> Float:
    fn to_minutes() -> Float:
    fn to_hours() -> Float:

Duration.abs#

Returns the absolute value; the minimum Duration faults.

fn abs() -> Duration:

Duration.add#

Adds signed nanoseconds; a result outside Duration’s representable range faults.

fn add(other: Duration) -> Duration:

Duration.compare#

Returns -1, 0, or 1.

fn compare(other: Duration) -> Int:

Duration.divide#

Divides by a nonzero integer, truncating toward zero; zero faults.

fn divide(divisor: Int) -> Duration:

Duration.multiply#

Multiplies by an integer factor; overflow faults.

fn multiply(factor: Int) -> Duration:

Duration.negate#

Negates this duration; the minimum Duration faults.

fn negate() -> Duration:

Duration.subtract#

Subtracts signed nanoseconds; a result outside Duration’s representable range faults.

fn subtract(other: Duration) -> Duration:

Duration.to_hours#

Converts this duration to floating-point hours.

fn to_hours() -> Float:

Duration.to_microseconds#

Converts this duration to an integer number of microseconds.

fn to_microseconds() -> Int:

Duration.to_milliseconds#

Converts this duration to an integer number of milliseconds.

fn to_milliseconds() -> Int:

Duration.to_minutes#

Converts this duration to floating-point minutes.

fn to_minutes() -> Float:

Duration.to_nanoseconds#

Converts this duration to an integer number of nanoseconds.

fn to_nanoseconds() -> Int:

Duration.to_seconds#

Converts this duration to floating-point seconds.

fn to_seconds() -> Float:

Instant Native type#

An instant on a monotonic clock; it is not a calendar timestamp.

type Instant:
    fn shift(duration: Duration) -> Instant:
    fn difference(other: Instant) -> Duration:
    fn compare(other: Instant) -> Int:

Instant.compare#

Returns -1, 0, or 1; instants from different clock domains fault.

fn compare(other: Instant) -> Int:

Instant.difference#

Returns the elapsed duration from right to this instant.

fn difference(other: Instant) -> Duration:

Instant.shift#

Shifts this monotonic instant by a duration.

fn shift(duration: Duration) -> Instant:

TimeError Alternative#

Errors returned by timestamp parsing, arithmetic, or range conversion.

type TimeError:
    case InvalidInput
    case Closed
    case InvalidData
    case OutOfRange

impl Error for TimeError:
    fn message() -> String:

TimeError.Closed#

Reserved for time operations on a closed resource; the current native time operations do not return it.

case Closed

TimeError.InvalidData#

The text is not an RFC 3339 timestamp with a four-digit year, full date and time, and an explicit Z or +hh:mm offset.

case InvalidData

TimeError.InvalidInput#

Reserved for invalid time arguments; the current native time operations do not return it.

case InvalidInput

TimeError.OutOfRange#

A nanosecond component is outside 0 through 999999999, or the result falls outside years 1 through 9999 or cannot be represented as a Duration.

case OutOfRange

TimeError.Error.message#

Returns the fixed diagnostic time: <reason>, such as time: value out of range, without echoing the input text.

fn message() -> String:

Timestamp Native type#

A wall-clock time with Unix seconds and nanoseconds.

type Timestamp:
    fn to_string() -> String:
    fn unix_seconds() -> Int:
    fn nanoseconds() -> Int:
    fn shift(duration: Duration) -> Result[Timestamp, TimeError]:
    fn difference(other: Timestamp) -> Result[Duration, TimeError]:
    fn compare(other: Timestamp) -> Int:

Timestamp.compare#

Returns -1, 0, or 1 across the full calendar range.

fn compare(other: Timestamp) -> Int:

Timestamp.difference#

Returns self - right as a duration.

fn difference(other: Timestamp) -> Result[Duration, TimeError]:

Timestamp.nanoseconds#

Returns this timestamp’s nanosecond component.

fn nanoseconds() -> Int:

Timestamp.shift#

Adds a duration to this wall-clock timestamp.

fn shift(duration: Duration) -> Result[Timestamp, TimeError]:

Timestamp.to_string#

Formats this timestamp in RFC 3339 form.

fn to_string() -> String:

Timestamp.unix_seconds#

Returns the whole Unix seconds represented by this timestamp.

fn unix_seconds() -> Int:

WallClock Interface#

A clock that reports calendar time.

interface WallClock:
    fn now() -> Timestamp

WallClock.now#

Returns the current calendar time as a UTC Timestamp with nanosecond precision. It can jump when the system clock is adjusted, so use Clock for elapsed time.

fn now() -> Timestamp

clock Function#

Returns the monotonic clock used for elapsed-time measurements.

fn clock() -> Clock:

duration Function#

Constructs a duration from a number of nanoseconds.

fn duration(nanoseconds: Int) -> Duration:

parse_timestamp Function#

Parses an RFC 3339 timestamp with an explicit time zone.

fn parse_timestamp(text: String) -> Result[Timestamp, TimeError]:

sleep Function#

Suspends the current task for at least the requested duration.

fn sleep(duration: Duration) -> Unit:

timestamp Function#

Constructs a timestamp from Unix seconds and a nanosecond adjustment.

fn timestamp(seconds: Int, nanoseconds: Int) -> Result[Timestamp, TimeError]:

wall_clock Function#

Returns the wall clock used for calendar timestamps.

fn wall_clock() -> WallClock: