vercel-labs--zerolang/docs/articles/modules/time.md

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.