std/time

Function	Result
`format_duration(ms)`	`250ms`, `4.2s`, `3m 05s`, `2h 15m`, or `1d 1h`
`format_date(seconds)`	`2026-11-04` for seconds since 1970, as `unix_time` gives
`format_clock(seconds)`	`13:45:07`
`format_timestamp(seconds)`	`2026-11-04 13:45:07 UTC`
`date_from_days(days)`	a `Date` with `year`, `month`, and `day`
`time_ago(past, now)`	`just now`, `5 minutes ago`, `yesterday`, `3 days ago`, ...

Measure how long something takes with the clock_ms built-in, which never goes backwards, and show it with format_duration.

Instants, dates, and times

import "std/time"

DateTime meeting = parse_rfc3339("2026-11-06T13:45:00-03:00")?
print(meeting.format("dddd, MMMM D [at] h:mm A"))     // Friday, November 6 at 1:45 PM
print(meeting.plus(duration_of(hours: 2)))           // 2026-11-06T15:45:00-03:00
print(format_http_date(meeting.instant))             // Fri, 06 Nov 2026 16:45:00 GMT
print(relative_time(meeting.instant, now()))         // "in 3 days", or "2 hours ago"

Type	What it is
`Duration`	a length of time in nanoseconds, from `duration_of(days:, hours:, minutes:, seconds:, millis:, micros:, nanos:)`; `+`, `-`, unary `-`, and comparisons work on it, and `times(n)`, `divided_by(n)`, `total_seconds()`, `millis()`, and `whole_seconds()`
`Instant`	a point in time, nanoseconds since 1970 in UTC, from `now()`, `instant_from_seconds`, or `instant_from_millis`; comparisons work on it, and `plus`, `minus`, `since`, `seconds()`, `millis()`, `utc()`, and `local()`
`Date`	a date, from `date_of(year, month, day)`, which checks it; `weekday()` (1 for Monday), `day_of_year()`, `days()`, `plus_days`, `plus_months`, `plus_years`, `days_until`, and comparisons
`Time`	a time of day, from `time_of(hour, minute, second, nano)`, with comparisons and `of_day()`
`DateTime`	an instant with the `offset`, in seconds east of UTC, of the clock that shows it, from `datetime_of(date, time, offset)`, `local_now()`, or `utc_now()`; `date()`, `time()`, `year()` and the rest, `plus`, `minus`, `since`, `at_offset`, `format(pattern)`, and comparisons of their instants

print and to_str show them as 2h 15m, 2026-11-06T16:45:07Z, 2026-11-06, 13:45:07, and 2026-11-06T13:45:07-03:00.

Function	Result
`parse_rfc3339(text)`, `format_rfc3339(dt)`	RFC 3339, as `2026-11-06T13:45:07.25-03:00`
`parse_iso8601(text)`	ISO 8601 dates and times, extended or basic, with week and ordinal dates; a date alone is at midnight, and a time without an offset in UTC
`parse_rfc2822(text)`, `format_rfc2822(dt)`	the dates of mail, as `Fri, 06 Nov 2026 13:45:07 -0300`, with the old forms RFC 2822 allows
`parse_http_date(text)`, `format_http_date(instant)`	the three forms of dates HTTP reads, and the one it writes
`format_datetime(dt, pattern)`, `parse_datetime(text, pattern)`	dates in a pattern of tokens: `YYYY`, `YY`, `MMMM`, `MMM`, `MM`, `M`, `DD`, `D`, `dddd`, `ddd`, `HH`, `H`, `hh`, `h`, `mm`, `m`, `ss`, `s`, `SSS`, `SSSSSS`, `SSSSSSSSS`, `A`, `a`, `Z` (`+03:00`), and `ZZ` (`+0300`), with text in `[brackets]` kept
`parse_duration(text)`, `iso_duration(d)`	durations as ISO 8601 writes them, `PT1H30M`, or as Go does, `1h30m` or `250ms`
`relative_time(moment, now)`	`just now`, `5 minutes ago`, `in 3 hours`, `tomorrow`, `in 2 months`
`is_leap_year(year)`, `days_in_month(year, month)`, `days_from_date(year, month, day)`	the calendar

The calendar is the proleptic Gregorian one; leap seconds are not counted, and a second of 60 is read as 59. Parsing gives an ERROR of kind "invalid_time". The system's time zone gives local() and local_now() their offset at each instant; time zones by name are for phase 19.