time API

pub fn from_ymd(fy: integer, fmo: integer, fd: integer) -> integer

Epoch-ms at UTC midnight of the given calendar date.

pub fn from_millis(ms: integer) -> integer

Identity wrapper — for readability where a raw ms count becomes a time.

pub fn from_unix_seconds(secs: integer) -> integer

Epoch-SECONDS boundary. Garmin / Strava REST APIs speak Unix seconds (.timestamp()), while loft times are milliseconds — convert at the edge.

pub fn to_unix_seconds(uts: integer) -> integer

Whole seconds since the epoch — what a system call or a wire format usually wants, where this library works in milliseconds.

pub fn parse(ps: text) -> integer?

Parse an ISO date "YYYY-MM-DD", optionally followed by " HH:MM[:SS]" or "THH:MM[:SS]" with an optional trailing "Z".

Null (test with !result) means the text is not SHAPED like a date — too short, or a non-digit where a digit belongs. It never means the date is not real: out-of-range fields ROLL OVER, so "2026-13-45" answers 2027-02-14 and "2026-02-30" answers 2026-03-02, both non-null. To reject an impossible date, round-trip it through format_date.

pub fn year(yt: integer) -> integer

The calendar year, UTC. Proleptic Gregorian, so it is defined before 1970 too.

pub fn month(mt: integer) -> integer

The month, 1..12 — one-based, as a calendar reads.

pub fn day(dt: integer) -> integer

The day of the month, 1..31.

pub fn hour(ht: integer) -> integer

The hour of the day, 0..23, in UTC.

pub fn minute(mit: integer) -> integer

The minute of the hour, 0..59.

pub fn second(st: integer) -> integer

The second of the minute, 0..59.

pub fn weekday(wt: integer) -> integer

0 = Monday .. 6 = Sunday. 1970-01-01 was a Thursday (weekday 3).

pub fn add_days(adt: integer, days: integer) -> integer

Step by whole days / weeks / seconds. These exist because the raw value is MILLISECONDS: t + 3 is three thousandths of a second, and reads at the call site like three of whatever the reader had in mind.

pub fn add_weeks(awt: integer, weeks: integer) -> integer

Move by whole weeks. Calendar-safe like add_days: no hour drifts, because there is no daylight saving in this model.

pub fn add_seconds(ast: integer, secs: integer) -> integer

Move by whole seconds.

pub fn days_between(da: integer, db: integer) -> integer

Calendar days from a to b (b later → positive) — a count of UTC-MIDNIGHTS CROSSED, not of elapsed time, so a 26-hour span can answer 2 where a 46-hour span answers 1. This is the streak / "day 3 of" question; for elapsed time use seconds_between.

pub fn seconds_between(sa: integer, sb: integer) -> integer

Elapsed whole seconds from a to b, TRUNCATED TOWARD ZERO — a backwards span of 1.5 s answers -1, not -2.

pub fn start_of_day(sdt: integer) -> integer

Midnight UTC at the start of this day — the anchor for bucketing events by day. For a local day, offset first with to_local.

pub fn start_of_week(swt: integer) -> integer

Monday 00:00 UTC of the week containing t.

pub fn at_time(atd: integer, hh: integer, mm: integer, ss: integer) -> integer

Combine a date with a time-of-day given as components (datetime.combine).

pub fn combine(cmd: integer, time_text: text) -> integer?

Combine a date with an "HH:MM" or "HH:MM:SS" time string. Mirrors datetime.combine(date, time.fromisoformat(s)). Null on a mis-SHAPED time only — as with parse, out-of-range fields roll over ("99:99" lands four days later), so this never rejects a real clock.

pub fn iso_year(iyt: integer) -> integer

pub fn iso_week(iwt: integer) -> integer

pub fn to_local(lt: integer, offset_min: integer) -> integer

Shift so that the field accessors / formatters yield local values. The answer is an INSTANT moved by the offset, so it must never be compared with, or subtracted from, an unshifted time.

pub fn local_day(ldt: integer, offset_min: integer) -> integer

UTC-midnight key of the local calendar day containing t — a value to GROUP by, not the instant local midnight happened (that is local_day(t, off) - off * 60000).

pub fn today(offset_min: integer) -> integer

The local calendar day for "now" at the given offset.

pub fn format_date(fdt: integer) -> text

The date as YYYY-MM-DD.

pub fn format_time(ftt: integer) -> text

The time as HH:MM.

pub fn format_seconds(fst: integer) -> text

The time as HH:MM:SS, when the seconds matter.

pub fn format_datetime(fdtt: integer) -> text

Date and time together, for a log line or a label.

pub fn format_iso(fit: integer) -> text

Full ISO-8601 in UTC — the spelling to store or send, and the one parse reads back.

pub fn weekday_name(wnt: integer) -> text

The weekday's short English name ("Mon" … "Sun"), for display only.

pub fn month_name(mnt: integer) -> text

The month's short English name ("Jan" … "Dec"), for display only.

pub value struct DateTime { ms: integer }

A point in time: milliseconds since the epoch, UTC. date and datetime make one, and "2026-07-08" as DateTime parses one; subtracting two gives a Duration.

pub value struct Duration { ms: integer }

A span of time in milliseconds, negative when it runs backwards. milliseconds, seconds, minutes, hours, days and weeks make one.

pub fn date(dcy: integer, dcmo: integer, dcd: integer) -> DateTime

── DateTime construction ── A DateTime at midnight UTC on this calendar date — the usual way into the typed layer.

pub fn datetime(tcy: integer, tcmo: integer, tcd: integer, tch: integer, tcmi: integer, tcs: integer) -> DateTime

A DateTime at an exact calendar date and time of day, UTC.

pub fn milliseconds(nms: integer) -> Duration

── Duration construction ── A Duration of this many milliseconds.

pub fn seconds(nsec: integer) -> Duration

A Duration of this many seconds.

pub fn minutes(nmin: integer) -> Duration

A Duration of this many minutes.

pub fn hours(nhr: integer) -> Duration

A Duration of this many hours.

pub fn days(nday: integer) -> Duration

A Duration of this many days. Add it to a DateTime rather than doing the arithmetic yourself, so the unit is in the code instead of in your head.

pub fn weeks(nwk: integer) -> Duration

A Duration of this many weeks.

pub fn year(self: DateTime) -> integer

── DateTime field accessors (methods; delegate to the integer API above) ── This value's year.

pub fn month(self: DateTime) -> integer

This value's month.

pub fn day(self: DateTime) -> integer

This value's day.

pub fn hour(self: DateTime) -> integer

This DateTime's hour, the method form of the free function above.

pub fn minute(self: DateTime) -> integer

This DateTime's minute, the method form of the free function above.

pub fn second(self: DateTime) -> integer

This DateTime's second, the method form of the free function above.

pub fn weekday(self: DateTime) -> integer

This value's weekday.

pub fn iso_year(self: DateTime) -> integer

This value's iso year.

pub fn iso_week(self: DateTime) -> integer

This value's iso week.

pub fn weekday_name(self: DateTime) -> text

This DateTime's weekday name, the method form of the free function above.

pub fn month_name(self: DateTime) -> text

This DateTime's month name, the method form of the free function above.

pub fn to_millis(self: DateTime) -> integer

This DateTime as milliseconds since the epoch — the way OUT of the typed layer, for storage, a wire format, or the plain-integer routines above.

pub fn total_millis(self: Duration) -> integer

── Duration accessors ── The span in whole milliseconds — its exact value.

pub fn total_seconds(self: Duration) -> integer

The span in whole seconds, truncated toward zero.

pub fn total_minutes(self: Duration) -> integer

The span in whole minutes, truncated toward zero.

pub fn total_hours(self: Duration) -> integer

The span in whole hours, truncated toward zero.

pub fn total_days(self: Duration) -> integer

The span in whole days, truncated toward zero.

pub operator compare(self: DateTime, other: DateTime) -> Ordering

── DateTime operators (comparison + typed arithmetic) ── == and != compare the one field, so two DateTimes are equal at the same millisecond. Orders instants, so dates compare with <, <=, >, >= like numbers.

pub operator minus(self: DateTime, other: DateTime) -> Duration

DateTime - DateTime is the Duration BETWEEN them, which is why a span never has to be spelled as a bare integer.

pub operator minus(self: DateTime, span: Duration) -> DateTime

DateTime - Duration moves backward by the span; dt.minus(span) is the same call.

pub operator plus(self: DateTime, span: Duration) -> DateTime

DateTime + Duration moves forward by the span.

pub operator negate(self: Duration) -> Duration

The same span, backwards: -span, or span.negate().

pub operator compare(self: Duration, other: Duration) -> Ordering

── Duration operators ── == and != compare the length. Orders spans by length.

pub operator plus(self: Duration, other: Duration) -> Duration

Two spans add.

pub operator minus(self: Duration, other: Duration) -> Duration

One span less another.

pub operator times(self: Duration, factor: integer) -> Duration

A span scaled by a whole number — minutes(5) * 3 is fifteen minutes.

pub operator to_text(self: DateTime, spec: text) -> text

── custom formatting (operator to_text: "{dt}" and "{dt:spec}") ── "" / "datetime" -> YYYY-MM-DD HH:MM · "date" -> YYYY-MM-DD · "time" -> HH:MM "seconds" -> HH:MM:SS · "iso" -> …THH:MM:SSZ · "wday" -> Mon · "month" -> May

pub operator to_text(self: Duration, _spec: text) -> text

A Duration renders as [-]H:MM:SS (hours may exceed 24).

pub operator to_integer(self: DateTime) -> integer

── conversions (as) ── dt as integer: the point in time as milliseconds since the epoch, UTC.

pub operator to_date_time(self: integer) -> DateTime

ms as DateTime: milliseconds since the epoch, UTC, as a point in time — the way back from as integer, and the checked path from parse (see FALLIBILITY above).

pub operator to_date_time(self: text) -> DateTime

text -> DateTime: a TOTAL best-effort parse (bad input -> epoch); see the FALLIBILITY note above for the checked path via parse.