Skip to content

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.

milo
from "std/datetime" import { DateTime, weekdayName, monthName }

Example ​

milo
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.

milo
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.

milo
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 ​

milo
pub struct DateTime

A 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 ​

milo
fn DateTime.format(self: &DateTime): string

ISO 8601: 2024-03-15T14:30:00

DateTime.formatDate ​

milo
fn DateTime.formatDate(self: &DateTime): string

The date portion only: 2024-03-15.

DateTime.formatTime ​

milo
fn DateTime.formatTime(self: &DateTime): string

The time portion only: 14:30:00.

DateTime.fromEpoch ​

milo
fn DateTime.fromEpoch(epochSec: i64): DateTime

Components in UTC for the given epoch seconds (negative is before 1970).

DateTime.fromEpochLocal ​

milo
fn DateTime.fromEpochLocal(epochSec: i64): DateTime

Same 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 ​

milo
fn DateTime.localNow(): DateTime

Current time in the host timezone.

DateTime.now ​

milo
fn DateTime.now(): DateTime

Current UTC time.

Functions ​

formatDateTime ​

milo
pub fn formatDateTime(ms: i64, pattern: &string, offsetMinutes: i64): string

Format 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 ​

milo
pub fn formatIso8601(ms: i64): string

ISO 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 ​

milo
pub fn formatRfc2822(ms: i64): string

An 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 ​

milo
pub fn monthName(m: i32): string

English name for a month, 1 = January.

parseIso8601 ​

milo
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 ​

milo
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 ​

milo
pub fn weekdayName(wd: i32): string

English name for a weekday, 0 = Sunday.