std/datetime
Date and time from epoch timestamps, and formatting and parsing of RFC 2822 and ISO 8601 dates. Construct with a DateTime static; format epoch milliseconds with formatIso8601, formatRfc2822 or a strftime-style formatDateTime.
from "std/datetime" import { DateTime, weekdayName, monthName }Example
let dt = DateTime.now()
print(dt.format())
print(weekdayName(dt.weekday) + ", " + monthName(dt.month))Parsing
parseRfc2822 reads the dates RSS pubDate and email Date: headers carry (RFC 5322, 2822, 1123 and 822), and parseIso8601 reads ISO 8601 / RFC 3339 timestamps (Atom, JSON APIs). Both return epoch milliseconds in UTC, or an error naming what was wrong.
from "std/datetime" import { DateTime, parseRfc2822, parseIso8601 }
fn main() {
let a = parseRfc2822("Mon, 12 Oct 2026 14:00:00 GMT")!
let b = parseIso8601("2026-10-12T16:00:00.250+02:00")!
print(a) // 1791813600000
print(b - a) // 250
print(DateTime.fromEpoch(a / 1000).format()) // 2026-10-12T14:00:00
print(parseIso8601("2026-10-12T14:00:00").isErr()) // true: no offset
}Named zones are limited to the ones RFC 2822 defines (GMT, UT, the US zones); CEST or IST mean different offsets in different places and are rejected. An ISO date-time without an offset is rejected too, rather than guessed as local time.
Formatting
The formatters take epoch milliseconds, the unit the parsers return, so each one round-trips through its parser. formatIso8601 writes UTC with millisecond precision (what JavaScript's toISOString writes). formatRfc2822 writes the IMF-fixdate HTTP requires, which is also a valid RFC 2822 date for RSS and email; it has whole seconds.
from "std/datetime" import { formatIso8601, formatRfc2822, formatDateTime, parseIso8601 }
fn main() {
let t = parseIso8601("2026-10-12T21:05:09.042Z")!
print(formatIso8601(t)) // 2026-10-12T21:05:09.042Z
print(formatRfc2822(t)) // Mon, 12 Oct 2026 21:05:09 GMT
print(formatDateTime(t, "%a %b %d, %-I:%M %p", -420)) // Mon Oct 12, 2:05 PM
}formatDateTime takes the offset east of UTC in minutes rather than a zone name: there is no time zone database, so the caller decides which offset applies to the instant.
API reference
DateTime
pub struct DateTimeA broken-down calendar date and time. month is 1-based and weekday counts from 0 = Sunday.
Fields: year: i32, month: i32, day: i32, hour: i32, minute: i32, second: i32, weekday: i32.
DateTime.format
fn DateTime.format(self: &DateTime): stringISO 8601: 2024-03-15T14:30:00
DateTime.formatDate
fn DateTime.formatDate(self: &DateTime): stringThe date portion only: 2024-03-15.
DateTime.formatTime
fn DateTime.formatTime(self: &DateTime): stringThe time portion only: 14:30:00.
DateTime.fromEpoch
fn DateTime.fromEpoch(epochSec: i64): DateTimeComponents in UTC for the given epoch seconds (negative is before 1970).
DateTime.fromEpochLocal
fn DateTime.fromEpochLocal(epochSec: i64): DateTimeSame components as fromEpoch but in the host timezone (TZ env / /etc/localtime). struct tm leads with nine consecutive ints (tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year, tm_wday, tm_yday, tm_isdst) on both macOS and glibc — only those leading fields are read, so the trailing platform differences (tm_gmtoff/tm_zone) don't matter.
The host timezone is an input like the clock (TZ, /etc/localtime), so the breakdown is recorded and replayed under MILO_RECORD / MILO_REPLAY (std/replay).
DateTime.localNow
fn DateTime.localNow(): DateTimeCurrent time in the host timezone.
DateTime.now
fn DateTime.now(): DateTimeCurrent UTC time.
Functions
formatDateTime
pub fn formatDateTime(ms: i64, pattern: &string, offsetMinutes: i64): stringFormat epoch milliseconds ms with a strftime-style pattern, at a fixed offset of offsetMinutes east of UTC (0 for UTC, -420 for PDT). There is no time zone database: the caller supplies the offset that applies to the instant.
%Y year (2026) %m month 01-12 %d day 01-31 %e day, space-padded %H hour 00-23 %I hour 01-12 %M minute 00-59 %S second 00-60 %L millisecond 000 %p AM or PM %j day of year 001-366 %a Mon %A Monday %b Oct %B October %z offset +hhmm %y year 00-99 %F = %Y-%m-%d %T = %H:%M:%S %% a literal %
A - after % drops a numeric field's padding (%-d is 5, %-I is 2). Names are English. A directive not listed is copied to the output unchanged, as C strftime implementations do.
formatIso8601
pub fn formatIso8601(ms: i64): stringISO 8601 / RFC 3339 in UTC with millisecond precision, 2026-10-12T14:00:00.000Z, for epoch milliseconds ms (the form JavaScript's toISOString writes). parseIso8601 reads it back to the same ms.
formatRfc2822
pub fn formatRfc2822(ms: i64): stringAn RFC 5322 / 2822 date in UTC, in the IMF-fixdate form HTTP requires (RFC 9110 5.6.7): Mon, 12 Oct 2026 14:00:00 GMT, for epoch milliseconds ms. The one form is right for HTTP Date, Last-Modified and Expires, cookie Expires, RSS pubDate and email Date:. Sub-second precision is dropped (floored); parseRfc2822 reads the result back to the whole second.
monthName
pub fn monthName(m: i32): stringEnglish name for a month, 1 = January.
parseIso8601
pub fn parseIso8601(s: &string): Result<i64>Parse an ISO 8601 / RFC 3339 timestamp in extended format: 2026-10-12T14:00:00Z, 2026-10-12T14:00:00.123+02:00, 2026-10-12 14:00:00z, or a bare date 2026-10-12 (midnight UTC). Returns epoch milliseconds (UTC). Fractional seconds take any number of digits and are truncated to milliseconds; hh:mm without seconds is accepted. The offset is Z, ±hh:mm, ±hhmm or ±hh, and a date-time without one is an error rather than a guess at local time (append Z if it is UTC).
parseRfc2822
pub fn parseRfc2822(s: &string): Result<i64>Parse an RFC 5322 / 2822 / 1123 / 822 date, the form RSS pubDate and email Date: headers use: Mon, 12 Oct 2026 14:00:00 GMT, 12 Oct 2026 14:00 -0700 (PDT). Returns epoch milliseconds (UTC). The weekday is optional and not checked against the date; seconds are optional. Accepted zones: numeric (+0000, -07:00), UT, GMT, UTC, Z, the US zones EST EDT CST CDT MST MDT PST PDT, and the military letters, which RFC 2822 §4.3 says to read as -0000 (UTC). Other names (CEST, IST) are ambiguous and rejected. Two-digit years follow RFC 2822 §4.3: 00-49 is 20xx, 50-99 is 19xx; three digits add 1900. A trailing (comment) is ignored.
weekdayName
pub fn weekdayName(wd: i32): stringEnglish name for a weekday, 0 = Sunday.