Date and time

Instants, durations, and timing.

Generated by bin/build_library_doc.py from the kernel sources. Do not edit by hand: change the generator, or the doc comments in kernel/src/, and re-run it.

Date and time

CLASS DateTime

IMPLEMENTS Comparable, Equatable, Hashable, Cloneable

UTC wall-clock instant, millisecond precision.

Storage shape (LOCKED): canonical int64 epochMs — milliseconds since the Unix epoch — is the single source of truth. The seven broken-down fields (year/month/day/hour/minute/second/ millisecond) are public read-only and derived once at construction by the gmtime_r-backed ev_datetime_to_broken_down shim.

Construction (LOCKED, ISO 8601 range [year 1, year 9999]): - CREATE DateTime() — wall-clock now (always valid) - DateTimeFactory->newDateTime(...) — explicit components, pipe-XOR FAILURE on out-of-range. The factory lives on the DateTimeFactory singleton because fallible INIT isn't a V1 surface (parser has no INIT-RETURNS form; revisit when it does).

kernel/src/DateTime.ev:44

Fields

Constructors

INIT()

Construct from the current wall-clock instant (UTC). Always valid — system time cannot be outside the representable range.

INIT(int64 epochMs)

Construct from a raw Unix epoch ms value. Primarily used by DateTimeFactory.newDateTime after it has validated components and computed epochMs via ev_datetime_from_broken_down — that is the supported path for explicit construction, because it surfaces a pipe-XOR FAILURE on out-of-range. Direct use is also fine if you already hold a known-valid epoch (e.g. from another DateTime, from a database column). Out-of-range epoch values surface as gmtime_r returning bogus broken-down fields; no FAILURE is raised here, so prefer DateTimeFactory.newDateTime for untrusted input.

Methods

METHOD getEpochMs() RETURNS int64

Wall-clock instant as milliseconds since the Unix epoch (UTC).

METHOD isLessThan(REFERENCE DateTime other) RETURNS boolean

Comparable[DateTime] — strict less-than on epochMs (UTC). The ordering operators (<, <=, >, >=) are derived by the compiler from this single method per Comparable's convention.

METHOD equals(REFERENCE DateTime other) RETURNS boolean

Equatable[DateTime] — Comparable's parent. Two DateTimes are equal iff their epochMs match; broken-down field equality is a derived consequence (both produced by gmtime_r from the same ms).

METHOD compareTo(REFERENCE DateTime other) RETURNS TimeComparison

Explicit three-way comparison — for callers that want the named TimeComparison enum (BEFORE / EQUAL / AFTER) rather than composing the Comparable primitives. Both surfaces are intentional per Phase 0 #3 LOCKED.

METHOD __op_plus__(REFERENCE TimeDuration d) RETURNS DateTime

dt + td — shift forward by d. UTC.

METHOD __op_minus__(REFERENCE TimeDuration d) RETURNS DateTime

dt - td — shift back by d. UTC.

METHOD __op_minus__(REFERENCE DateTime other) RETURNS TimeDuration

dt - dt' — the TimeDuration FROM other TO self. Sign follows the convention later - earlier > 0.

METHOD format(REFERENCE String pattern) RETURNS String

Render this DateTime against pattern, substituting each recognised token with its zero-padded field value and copying every other character verbatim.

METHOD hash() RETURNS uint64

FNV-1a 64-bit hash of epochMs, mixed as 8 little-endian bytes. epochMs is the canonical state — two DateTimes with equal epochMs are Equatable-equal and must hash identically.

METHOD clone() RETURNS DateTime

Field copy. Routes through INIT(int64) so the broken-down decomposition runs once on the clone; epochMs is the source of truth, the seven public fields are derived.

CLASS DateTimeFactory

Fallible DateTime construction surface.

Envzn has no static-method facility and fallible INIT is not a V1 parser surface, so the two DateTime factories that validate their components and return pipe-XOR (DateTime | STATUS) live on a dedicated stateless singleton rather than on the DateTime class itself.

Both delegate range / calendar validation to the same ev_datetime_from_broken_down shim that DateTime.ev binds (FOREIGN scope is per-file, §17), using NumericLimits.INT64_MIN as the failure sentinel.

kernel/src/DateTimeFactory.ev:32

Methods

METHOD parseDateTime(REFERENCE String text, REFERENCE String pattern) RETURNS | DateTime

Strict-parse a DateTime from text against a pattern using the Phase 5 token grammar: YYYY (4-digit year), MM/DD/HH/ mm/ss (2-digit), SSS (3-digit milliseconds). Each token consumes exactly its width in decimal digits; every other pattern character must match the next text character exactly. On any mismatch (width / non-digit / literal mismatch / trailing text / out-of-range components / invalid calendar date such as Feb 30), returns FAILURE rather than a partial DateTime.

METHOD newDateTime(int32 year, int32 month, int32 day, int32 hour, int32 minute, int32 second, int32 millisecond) RETURNS | DateTime

Construct a DateTime from explicit year-through-millisecond components. UTC. Pipe-XOR FAILURE on out-of-range per Phase 0 #5: year must lie in [1, 9999] (ISO 8601 range), month in [1, 12], day in [1, 31] (timegm rejects e.g. Feb 30 → FAILURE too), hour in [0, 23], minute in [0, 59], second in [0, 60] (leap-second permissible), millisecond in [0, 999].

CLASS TimeDuration

IMPLEMENTS Cloneable, Hashable, Equatable, Comparable

Signed wall-clock duration with millisecond precision.

Storage: canonical int64 totalMs (signed) — single source of truth. The five broken-down accessor fields (days/hours/minutes/seconds/millis) are public read-only and decomposed once at construction; for negative totalMs each carries the same sign as totalMs (mirrors java.time.Duration's sign convention).

Construction: - CREATE TimeDuration() — zero duration - CREATE TimeDuration(d, h, m, s, ms) — explicit components; the INIT composes totalMs and re-decomposes the fields, so callers reading .days / .hours / ... always see the normalised values (1 day 25 hours → 2 days 1 hour). - CREATE TimeDuration(int64 totalMs) — direct totalMs (used by arithmetic operator results — e.g., DateTime operator -(DateTime)).

Arithmetic / comparison: TimeDuration implements Comparable (and the parent Equatable), Hashable, Cloneable, plus operator + / operator - over TimeDuration → TimeDuration and a named negate() (V1 leaves unary - on classes out of scope per Phase 0 #6 LOCKED).

kernel/src/TimeDuration.ev:43

Fields

Constructors

INIT()

Zero duration.

INIT(int32 days, int32 hours, int32 minutes, int32 seconds, int32 millis)

Explicit-component constructor. Each parameter contributes linearly to totalMs (1 day = 86_400_000 ms; 1 hour = 3_600_000 ms; 1 minute = 60_000 ms; 1 second = 1_000 ms; 1 ms = 1 ms). The broken-down fields below are then derived from totalMs, so (1 day, 25 hours, 0, 0, 0) yields .days = 2, .hours = 1.

INIT(int64 totalMs)

Direct totalMs constructor. Used by arithmetic-operator results (DateTime->operator-(DateTime), TimeDuration±TimeDuration) where the int64 difference is already known and re-running the component composition would just round-trip.

Methods

METHOD getTotalMs() RETURNS int64

Signed milliseconds — the canonical underlying value.

METHOD __op_plus__(REFERENCE TimeDuration other) RETURNS TimeDuration

td1 + td2 lowering. Returns a new TimeDuration whose totalMs is the int64 sum; no overflow check (int64 ms range is ~±292M years, well past anything practical).

METHOD __op_minus__(REFERENCE TimeDuration other) RETURNS TimeDuration

td1 - td2 lowering.

METHOD negate() RETURNS TimeDuration

Named unary negation. Unary - on classes is out of V1 scope (Phase 0 #6 LOCKED); callers compose td->negate() instead.

METHOD isLessThan(REFERENCE TimeDuration other) RETURNS boolean

Strict less-than on totalMs. Drives derived </<=/>/>=.

METHOD equals(REFERENCE TimeDuration other) RETURNS boolean

Two TimeDurations are equal iff their totalMs match.

METHOD hash() RETURNS uint64

FNV-1a 64-bit hash of totalMs, mixed as 8 little-endian bytes. Mirrors the per-byte mixing String.hash() uses; equal totalMs → equal hash, the Equatable contract.

METHOD clone() RETURNS TimeDuration

Field copy. Routes through INIT(int64) so the decomposition runs once on the clone; totalMs is the source of truth, the public fields are derived.

METHOD format() RETURNS String

ISO-8601 duration text — [-]P[nD]T[nH][nM][nS[.mmm]], millisecond precision: PT0S for zero, a leading - for a negative duration, and fractional seconds (PT1.500S) only when there are sub-second millis. TOTAL — every duration has a text form. The inverse is DurationText.parse (DurationText.ev); serde carries a TimeDuration field through this pair (I.P.i).

CLASS DurationText

ISO-8601 duration PARSE, the inverse of TimeDuration.format.

Reads [-]P[nD]T[nH][nM][nS[.mmm]] (millisecond precision) back into a TimeDuration. Fallible: a malformed string is a FAILURE, never a silent zero — which is exactly what serde's reconstruct needs at the untrusted document boundary (I.P.i). A NAMESPACE (not a method on TimeDuration) because it is a fallible construction with no receiver, mirroring DateTimeFactory.parseDateTime.

Bounds are checked explicitly before every index (the scan advances by a variable amount), so the walk never indexes past the end regardless of AND evaluation order.

kernel/src/DurationText.ev:22

Methods

METHOD parse(REFERENCE String text) RETURNS | TimeDuration

Parse an ISO-8601 duration string into a TimeDuration, or FAILURE.

CLASS MeasuringTimer

A stack-scoped RAII elapsed-time probe.

Construct one as a local; it captures a monotonic start instant. When it leaves scope its CLEANUP (destructor) reports the elapsed time — so the measured region is simply the local's lexical scope:

{
    MeasuringTimer t := CREATE MeasuringTimer("parse phase")
    ... work to measure ...
}   // → prints  "parse phase: 1.234 ms"

Read the elapsed value mid-scope with elapsedNanos() / report(), or call silence() to suppress the automatic print (record-only).

Clock: a monotonic, nanosecond-resolution counter (ev_monotonic_nanos, EV_timer_native.hpp) — excludes system sleep, immune to wall-clock adjustments. The right source for timing code regions. (A direct FOREIGN BIND to libc's clock_gettime_nsec_np was rejected by the emitted C++: its clockid_t enum parameter won't implicitly construct from an Envzn uint32, so the one-line extern "C" wrapper takes the enum and exposes int64 nanos — and stays portable.)

kernel/src/MeasuringTimer.ev:37

Fields

Constructors

INIT(REFERENCE String label)

Start a labelled timer.

INIT()

Start an unlabelled timer (reports under "timer").

Methods

METHOD elapsedNanos() RETURNS int64

Elapsed monotonic nanoseconds since construction.

METHOD report() RETURNS String

Human-readable elapsed time, auto-scaled to ns / us / ms / s, prefixed with the label: e.g. "parse phase: 1.234 ms".

METHOD show() RETURNS void

Print the elapsed-time report line to stdout now. (Kept a normal method, not inlined into CLEANUP: the kernel's header-ordering scanner doesn't walk destructor bodies, so the Stdio dependency must surface from a scanned method to order EV_stdio.hpp ahead of this class.)

MODIFY METHOD silence() RETURNS void

Suppress the automatic CLEANUP print — use elapsedNanos()/report() to read the value yourself.

MODIFY METHOD unsilence() RETURNS void

Re-enable the automatic CLEANUP print.

CLASS TimeConstants

The fixed factors between time units, in one place.

These are not arbitrary tuning numbers — every one is a definition, fixed by the units themselves and unchanging. They lived as bare literals in TimeDuration, DurationText and MeasuringTimer, which meant the same 86400000 appeared in two files with nothing connecting them and nothing saying which unit pair it converted. A reader met mag / 86400000 and had to count the zeroes to learn it was days.

Sibling of HashConstants and NumericLimits — a namespace whose whole content is named constants, reached as TimeConstants.MS_PER_DAY.

kernel/src/TimeConstants.ev:23

Fields

ENUM TimeComparison

Three-way comparison result for DateTime->compareTo. Co-exists with Comparable[DateTime]'s isLessThan / equals — both surfaces are intentional per the constitution §28.5 reservation. Comparable derives the ordering operators (<, <=, >, >=); compareTo names the result for callers that want the explicit enum.

kernel/src/enums.ev:183

Case Description
? —
? —
? —

STRUCT DateTimeFields

DateTimeFields — boundary marshalling STRUCT for the gmtime_r round-trip backing DateTime.ev (Phase 2). All fields int32 so the POD-by-value FOREIGN BIND lowering applies (V1 Part E, exercised by kernel_probe/structbind). Not part of the public DateTime surface — callers read the public fields on the DateTime instance.

kernel/src/structs.ev:89

Fields