envzn
0.8 · beta · not released

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 Calendar.epochMsToFields (Calendar.ev).

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:37

Fields

  • int32 year
  • int32 month
  • int32 day
  • int32 hour
  • int32 minute
  • int32 second
  • int32 millisecond

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 Calendar.fieldsToEpochMs — 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). An epoch outside [year 1, year 9999] splits into proleptic-Gregorian fields outside that range; 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 split by Calendar 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.

  • newDateTime(year..millisecond) — explicit components, UTC.
  • parseDateTime(text, pattern) — strict token-grammar parse.

Both delegate range / calendar validation to Calendar.fieldsToEpochMs, which answers NumericLimits.INT64_MIN for components out of range.

kernel/src/DateTimeFactory.ev:25

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] (and a day the month has — Feb 30 is a FAILURE), 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

  • int64 days
  • int64 hours
  • int64 minutes
  • int64 seconds
  • int64 millis

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

  • int64 startNanos
  • String label
  • boolean reportOnExit

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

  • int64 MS_PER_SECOND — 1_000 — milliseconds in a second.
  • int64 MS_PER_MINUTE — 60_000 — milliseconds in a minute (60 x MS_PER_SECOND).
  • int64 MS_PER_HOUR — 3_600_000 — milliseconds in an hour (60 x MS_PER_MINUTE).
  • int64 MS_PER_DAY — 86_400_000 — milliseconds in a day (24 x MS_PER_HOUR). A NOMINAL day: this is duration arithmetic, which knows nothing of leap seconds or of the 23- and 25-hour days a DST transition produces. Calendar-aware arithmetic belongs to DateTime, not here.
  • int64 NS_PER_MICROSECOND — 1_000 — nanoseconds in a microsecond.
  • int64 NS_PER_MILLISECOND — 1_000_000 — nanoseconds in a millisecond.
  • int64 NS_PER_SECOND — 1_000_000_000 — nanoseconds in a second.

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 — the seven UTC calendar fields Calendar.epochMsToFields fills for DateTime's INITs. All int32. Not part of the public DateTime surface — callers read the public fields on the DateTime instance. (ev_time_to_fields, and its C layout was pinned at 28 bytes, Calendar.ev is Envzn now.)

kernel/src/structs.ev:89

Fields

  • int32 year
  • int32 month
  • int32 day
  • int32 hour
  • int32 minute
  • int32 second
  • int32 millisecond