std.time | Zero

When To Use std.time

In Zerolang, use std.time for duration math, RFC 3339 date and time validation and parsing, and target-gated monotonic or wall-clock helpers.

Runnable today:

API	Return	Notes
`std.time.ns(value)`	`Duration`	Builds a nanosecond duration.
`std.time.us(value)`	`Duration`	Builds a microsecond duration.
`std.time.ms(value)`	`Duration`	Builds a millisecond duration.
`std.time.seconds(value)`	`Duration`	Builds a second duration.
`std.time.minutes(value)`	`Duration`	Builds a minute duration.
`std.time.hours(value)`	`Duration`	Builds an hour duration.
`std.time.zero()`	`Duration`	Returns a zero duration.
`std.time.add(a, b)`	`Duration`	Adds two durations.
`std.time.sub(a, b)`	`Duration`	Subtracts one duration from another.
`std.time.min(a, b)`	`Duration`	Returns the smaller duration.
`std.time.max(a, b)`	`Duration`	Returns the larger duration.
`std.time.clamp(value, low, high)`	`Duration`	Clamps a duration between normalized bounds.
`std.time.abs(value)`	`Duration`	Returns a non-negative duration magnitude.
`std.time.between(start, end)`	`Duration`	Returns the non-negative duration between two values.
`std.time.hasElapsed(start, now, timeout)`	`Bool`	Reports whether a timeout window has elapsed.
`std.time.deadlineAfter(start, timeout)`	`Duration`	Builds a deadline by adding a timeout to a start instant.
`std.time.remainingUntil(deadline, now)`	`Duration`	Returns remaining time or zero once the deadline has passed.
`std.time.deadlineExpired(deadline, now)`	`Bool`	Reports whether `now` is at or past `deadline`.
`std.time.sleep(duration)`	`Bool`	Sleeps for a hosted non-negative duration; returns `false` on host failure.
`std.time.asNs(value)`	`i64`	Converts to nanoseconds.
`std.time.asUsFloor(value)`	`i64`	Converts to whole microseconds.
`std.time.asMsFloor(value)`	`i32`	Converts to whole milliseconds.
`std.time.asSecondsFloor(value)`	`i64`	Converts to whole seconds.
`std.time.lessThan(a, b)`	`Bool`	Compares two durations.
`std.time.isZero(value)`	`Bool`	Reports whether a duration is zero.
`std.time.monotonic()`	`Duration`	Reads a monotonic target clock where available.
`std.time.wallSeconds()`	`i64`	Reads target wall-clock seconds where available.
`std.time.isRfc3339Date(text)`	`Bool`	Validates an RFC 3339 full-date with leap years and days-in-month.
`std.time.isRfc3339Time(text)`	`Bool`	Validates an RFC 3339 full-time with fractional seconds, numeric offsets, and the leap-second rule.
`std.time.isRfc3339DateTime(text)`	`Bool`	Validates an RFC 3339 date-time joined by `T` or `t`.
`std.time.parseRfc3339DateTimeOr(text, fallback)`	`i64`	Parses a date-time into UTC epoch seconds; returns the fallback when invalid. Fractional seconds truncate; a valid leap second maps to the same epoch second as `:59`.
`std.time.isLeapYear(year)`	`Bool`	Gregorian leap-year predicate.
`std.time.daysInMonth(year, month)`	`u32`	Days in a month; returns `0` for invalid months.
`std.time.writeDurationNs(buffer, value)`	`Maybe<Span<u8>>`	Writes nanoseconds with an `ns` suffix into caller storage.
`std.time.writeDurationMs(buffer, value)`	`Maybe<Span<u8>>`	Writes whole milliseconds with an `ms` suffix into caller storage.
`std.time.writeDurationSeconds(buffer, value)`	`Maybe<Span<u8>>`	Writes whole seconds with an `s` suffix into caller storage.

Current limits:

Target-specific clock availability diagnostics.
Timer handles and fake-clock handles are not public APIs.

Metadata labels:

effects: time
allocation behavior: no allocation
target support: duration math is target-neutral; clock reads and sleep require a time-capable target
error behavior: infallible helpers; RFC 3339 validators return Bool and the epoch parser returns its fallback for invalid text
ownership notes: no ownership transfer
example: examples/std-platform.graph

Example

pub fn main(world: World) -> Void raises {    let a: Duration = std.time.ms(250)    let b: Duration = std.time.seconds(1)    let total: Duration = std.time.add(a, b)    let span: Duration = std.time.between(std.time.seconds(2), std.time.ms(250))    let deadline: Duration = std.time.deadlineAfter(std.time.seconds(10), std.time.ms(500))    let remaining: Duration = std.time.remainingUntil(deadline, std.time.seconds(10))    let slept: Bool = std.time.sleep(std.time.zero())    var text_storage: [32]u8 = [0_u8; 32]    let text: Maybe<Span<u8>> = std.time.writeDurationMs(text_storage, total)    if slept && std.time.asMsFloor(total) == 1250 && std.time.asMsFloor(span) == 1750 && (std.time.asMsFloor(remaining) == 500 && text.has) {        check world.out.write("duration ok\n")    }}

RFC 3339 validation includes the exact leap-second rule: seconds == 60 is valid only when the time normalized by its numeric offset equals 23:59:60 UTC, wrapping modulo 24 hours. 00:29:60+00:30 is valid because it normalizes to 23:59:60 UTC on the previous day, while 23:59:60-01:00 is invalid because it normalizes to 00:59:60 UTC.

pub fn main(world: World) -> Void raises {    let wrapped: Bool = std.time.isRfc3339Time("00:29:60+00:30")    let not_leap: Bool = std.time.isRfc3339Time("23:59:60-01:00")    let epoch: i64 = std.time.parseRfc3339DateTimeOr("2000-01-01T00:00:00Z", -1)    if wrapped && !not_leap && epoch == 946684800 && std.time.daysInMonth(2024, 2) == 29 {        check world.out.write("rfc3339 ok\n")    }}

Design Notes

Time is an effect when it observes or waits on the outside world.

Pure duration math can stay allocation-free and target-independent. Timer and fake-clock APIs are not exposed in the current public surface.