datetime
Dates, times and instants on the proleptic Gregorian calendar, with UTC and fixed UTC offsets. Parses and formats RFC 3339 / ISO 8601, and formats with strftime-style patterns and HTTP dates. A DateTime is an instant (Unix milliseconds) plus the offset used to display it, so comparing and subtracting instants never depends on the offset. Errors are a typed DateErr.
Effects: none. The package never reads the clock; pass it in with datetime.from_unix_ms(time.now()) (which needs uses time in your code).
fn main(): int! uses time {
let now = datetime.from_unix_ms(time.now())
let due = datetime.parse("2024-02-29T13:05:09.120+05:30")?
print("{due}") // 2024-02-29T13:05:09.120+05:30
print("{due.date()} {due.weekday()}") // 2024-02-29 Thu
print(due.add(1, datetime.Month)) // 2024-03-29T13:05:09.120+05:30 (clamped at month end)
print(datetime.format(due.utc(), "%a %d %b %Y %H:%M")) // Thu 29 Feb 2024 07:35
print(datetime.http_date(now)) // e.g. Fri, 30 Oct 2026 09:12:44 GMT
let late_ms = datetime.diff(now, due) // milliseconds
let d = datetime.date(2024, 2, 30) else e => fail(datetime.message(e)) // day out of range: 30
0
}
API
Types:
struct Date { year, month, day }andstruct Time { hour, minute, second, ms }(allint). The fields are public; build them withdate/timeto validate.struct DateTime { ms: int, offset_min: int }: milliseconds since 1970-01-01T00:00:00Z, and the display offset in minutes east of UTC (-1439..1439).enum Weekday { Mon, Tue, Wed, Thu, Fri, Sat, Sun },enum Unit { Ms, Sec, Min, Hour, Day, Week, Month, Year }enum DateErr { Syntax(expected: str, col: int), OutOfRange(field: str, value: int) }, andmessage(e): str(col 6: expected 2-digit month,day out of range: 30)
Calendar (on Date):
date(y, m, d): Date!DateErr,time(h, m, s, ms): Time!DateErr: validated constructors (|year| <= 999,999)is_leap(year): bool,days_in_month(year, month): int,day_of_year(d): intdays(d): int(days since 1970-01-01) andfrom_days(n): Dateweekday(d): Weekday(also onDateTime),number(w): int(ISO: Mon = 1 .. Sun = 7)add_days(d, n): Date,add_months(d, n): Date(clamps the day),diff(a, b): int(days)
Instants (on DateTime):
from_unix_ms(ms): DateTime(UTC),unix_ms(d): intutc(y, m, d, h, mi, s): DateTime!DateErr,make(date, time, offset_min): DateTime!DateErrutc(d): DateTime,with_offset(d, minutes): DateTime!DateErr: the same instant shown elsewheredate(d): Date,time(d): Time: the local fields atd's offsetadd(d, n, unit): DateTime:Ms..Weekare exact;Month/Yearmove the local date, clampeddiff(a, b): int(milliseconds,a - b)<,sort:DateTimeorders by instant (then offset);DateandTimeorder chronologically
Text:
parse(s): DateTime!DateErr:YYYY-MM-DD+T/t/space +hh:mm[:ss[.fff…]]+Z/z/±hh:mm/±hhmm/±hh. A date alone is midnight UTC; otherwise the offset is required. Extra fraction digits are truncated to ms.parse_date(s): Date!DateErr,parse_time(s): Time!DateErrshow, i.e."{x}": RFC 33392024-02-29T13:05:09.120Z(ms omitted when zero,Zfor offset 0);Dateas2024-02-29,Timeas13:05:09or13:05:09.120format(d, pattern): str:%Y %m %d %H %M %S,%L(ms),%j(day of year),%a %A(Mon,Monday),%b %B(Jan,January),%u(ISO weekday),%s(Unix seconds),%z(+0530),%Z(Zor+05:30),%%http_date(d): str:Sun, 06 Nov 1994 08:49:37 GMT(always GMT)
Design notes and limits (0.1)
- Time zones: UTC and fixed offsets only. There is no IANA time zone database (
Europe/Paris, daylight saving), soDayalways means 24 hours. Store the zone name yourself and pass the offset in for now. - Calendar: the proleptic Gregorian calendar for every year, with astronomical year numbering (year 0 = 1 BC, and negative years are allowed). Years outside 0000..9999 are written with a sign (
-0044-03-15,+12345-01-01), butparsereads 4-digit years only, as RFC 3339 does. - Precision: milliseconds, to match
time.now(). Leap seconds are not represented:23:59:60is anOutOfRangeerror, as in Unix time. - Plain
intmilliseconds, notint<ms>: coretime.now()returns a plainint, and a plainintdoesn't convert toint<ms>implicitly, so a unit would makefrom_unix_ms(time.now())and every caller's arithmetic need conversions. Durations are justdiffresults in ms, andaddtakes aUnit, so units of measure would add noise without catching real bugs here.