Packages

datetime

raft add datetime

version 0.1.0 pure

Pure means this package only computes: it cannot touch files, the network or the clock.

On this page

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

auk
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 } and struct Time { hour, minute, second, ms } (all int). The fields are public; build them with date/time to 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) }, and message(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): int
  • days(d): int (days since 1970-01-01) and from_days(n): Date
  • weekday(d): Weekday (also on DateTime), 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): int
  • utc(y, m, d, h, mi, s): DateTime!DateErr, make(date, time, offset_min): DateTime!DateErr
  • utc(d): DateTime, with_offset(d, minutes): DateTime!DateErr: the same instant shown elsewhere
  • date(d): Date, time(d): Time: the local fields at d's offset
  • add(d, n, unit): DateTime: Ms..Week are exact; Month/Year move the local date, clamped
  • diff(a, b): int (milliseconds, a - b)
  • <, sort: DateTime orders by instant (then offset); Date and Time order 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!DateErr
  • show, i.e. "{x}": RFC 3339 2024-02-29T13:05:09.120Z (ms omitted when zero, Z for offset 0); Date as 2024-02-29, Time as 13:05:09 or 13:05:09.120
  • format(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 (Z or +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), so Day always 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), but parse reads 4-digit years only, as RFC 3339 does.
  • Precision: milliseconds, to match time.now(). Leap seconds are not represented: 23:59:60 is an OutOfRange error, as in Unix time.
  • Plain int milliseconds, not int<ms>: core time.now() returns a plain int, and a plain int doesn't convert to int<ms> implicitly, so a unit would make from_unix_ms(time.now()) and every caller's arithmetic need conversions. Durations are just diff results in ms, and add takes a Unit, so units of measure would add noise without catching real bugs here.

Stuck on a word? Try the glossary. Got a compiler error? Look up its code. Improve this page