Time Domain API Guidelines

Core Semantics

calendar = proleptic Gregorian
time zone = UTC, normalized fixed offset, or supported named IANA zone
monotonic point = steady-clock value used only for elapsed-time measurement
duration = signed span with second resolution
precise delta = signed span with nanosecond resolution
calendar delta = independent signed calendar and fixed-unit components

Primary Types

Date // civil Gregorian date with an invalid state
Time // nanosecond-precision wall-clock time within one day
TimeWithZone // wall-clock time plus a zone but no date
DateTime // UTC instant with display offset or named-zone metadata
Duration // signed second-resolution span
TimeDelta // signed nanosecond-resolution span
CalendarDelta // independent calendar and fixed-unit delta
TimeZone // UTC, fixed offset, or supported named IANA zone
TimePoint // monotonic steady-clock point

Amount and Part Types

Nanoseconds, Microseconds, Milliseconds // fractional-second amounts
Seconds, Minutes, Hours, Days, Weeks // fixed-ratio second amounts
Months, Years // calendar amounts
Year, Month, Day, DayOfYear, DayOfWeek // bounded calendar parts
Hour, Minute, Second // bounded wall-clock parts

Supporting Types

DateParts, TimeParts, DateTimeParts // named aggregate part results
YearDayOfYearParts, YearMonthParts, MonthDayParts // calendar extraction results
Duration::Parts, Duration::DaysAndNanoseconds // duration decomposition results
TimeWrapResult // time-of-day arithmetic result with day crossings
ElapsedTimer // restartable monotonic elapsed-time helper
TimeZoneId // transient numeric zone identifier
tz::TimeOffset // resolved offset, abbreviation, and daylight-saving metadata
TimeDeltaFormat // human-readable and ELCL delta formatting policy

Policy Types

DateTimePrecision // ISO precision from year through nanosecond
IsoTimeFormat, IsoTimeFormatFlags // ISO date and time formatting policy
DayOfWeekFormat, DurationPart // name style and largest split duration part
TimeOccurrenceInFold // first or second local occurrence during a daylight-saving fold
TimeDeltaUnit // smallest fixed unit shown by delta formatting
SecondsUnitTag, MonthsUnitTag, YearsUnitTag // dimensions of time amount types

Part Value Patterns

T(value) // create a clamped part value
T::first/last/minimum/maximum() -> T // create part boundaries
T::contains(value) -> bool // test raw-value membership
o.isFirst()/isLast() -> bool // test a part boundary
o.add/subtract(value) // apply clamped part arithmetic
o.added/subtracted(value) -> T // return a clamped arithmetic result
o.next/previous([context]) -> T // navigate to an adjacent valid calendar part
o.toAmount() -> T // convert a bounded part to its zero-based amount
T::fromAmount/fromAmountOrThrow(amount) -> T // convert with clamping or exact failure

Calendar Inspection Patterns

o.year()/month()/day()/dayOfYear()/dayOfWeek() -> T // access calendar parts
o.hour()/minute()/second() -> T // access wall-clock parts
o.parts() -> T // return a named aggregate of available parts
T::exists(parts) -> bool // test whether civil parts form a real date
T::firstDay/lastDay(context) -> Date // get a month or year boundary date
T::extract❮Parts❯(value) -> T // decompose an epoch or day-of-year value

Civil Value Patterns

T(parts) // create a civil value with clamped or invalid-state behavior
T::fromParts/fromPartsOrThrow(parts) -> T // create with invalid or throwing failure reporting
o.isValid()/isFirst()/isLast() -> bool // inspect civil state or supported boundaries
o.add/subtract(amount) // apply saturating arithmetic in place
o.added/subtracted(amount) -> T // return a saturating arithmetic result
o.addOrThrow/subtractOrThrow(amount) // apply exact arithmetic in place
o.addedOrThrow/subtractedOrThrow(amount) -> T // return an exact result or throw
o.wouldAddSaturate/wouldSubtractSaturate(amount) -> bool // test boundary saturation
o.durationTo/timeDeltaTo(other) -> T // calculate a signed distance
T::epoch/first/last() -> T // create named civil boundaries

Time-of-Day Patterns

o.durationSinceMidnight()/timeDeltaSinceMidnight() -> T // get fixed time since midnight
o.addWithWrap(delta) -> Days // add in place and return signed day crossings
o.addedWithWrap(delta) -> TimeWrapResult // return wrapped time and day crossings
T::fromDurationSinceMidnight(delta) -> Time // wrap a fixed delta into one day
o.time()/timeZone() -> T // inspect a zoned wall-clock value

Duration and Delta Patterns

T(amount-or-parts) // create a duration or delta
T::❮unit❯/❮unit❯OrThrow(ticks) -> T // create with saturation or exact failure reporting
T::zero() -> T // create a zero span
o.isZero()/isPositive()/isNegative() -> bool // inspect sign state
o.to❮Unit❯()/toStd❮Unit❯() -> T // convert to a Core or standard duration
o.parts([largestPart]) -> T // decompose a duration
o.toTimeDelta/toTimeDeltaOrThrow() -> TimeDelta // convert with saturation or exact failure
o.toDuration() -> Duration // truncate a precise delta toward zero seconds
o.isValidTimeDelta() -> bool // test exact conversion of a calendar delta

Date-Time Patterns

T(date, time[, zone-or-offset, occurrence]) // create an instant from civil values
o.utcDate()/utcTime() -> T // inspect stored UTC parts
o.date()/time()/timeZone()/timeOffset() -> T // inspect display-zone parts
o.toUtc()/toTimeZone(zone) -> DateTime // preserve the instant and change display metadata
o.toTicks<U>([epoch]) -> T // convert exact epoch ticks
o.toSecondsAndFractions([epoch]) -> V // convert full precision seconds and ns
o.toTimeT() -> time_t // convert to the platform POSIX time type
T::now() -> T // get the current UTC instant
T::fromTicks<U>(value[, epoch]) -> T // create a date/time from ticks since an epoch
T::fromTicks(seconds, fractions[, epoch]) -> T // create a date/time from seconds/ns since an epoch
T::fromTimeT(value) -> T // create from the platform POSIX time type
T::epoch([epoch]) -> T // get a well-known epoch

Time-Zone Patterns

T(offset-or-id) // create UTC, a fixed offset, or a named zone
o.isUtc()/isStaticOffset()/isNamed()/isLocalTime() -> bool // inspect zone representation
o.staticOffset()/name()/id() -> T // inspect zone identity
T::fromName/fromNameOrThrow(name) -> TimeZone // resolve with empty or throwing failure reporting
T::names() -> text::StringList // list supported IANA zone names
T::databaseVersion() -> unit::Version // inspect the bundled IANA database version
T::utc()/local() -> TimeZone // access UTC or cached system-local zones

Formatting and Parsing Patterns

o.toIsoString([flags, precision]) -> text::String // create ISO text
T::fromIsoString/fromIsoStringOrThrow(text[, zone, precision]) -> T // parse with invalid or throwing failure
o.toString([format]) -> text::String // create normalized human-readable text
T::shortUnits/longUnits/elcl() -> TimeDeltaFormat // create a standard delta format

Monotonic Time Patterns

T::now()/inFuture(delta) -> TimePoint // create current or future steady-clock points
o.timeDeltaTo(point)/timeDeltaToNow() -> TimeDelta // measure a signed monotonic delta
T() // start an elapsed timer at construction
o.restart() // restart elapsed measurement at the current monotonic point
o.elapsed() -> TimeDelta // inspect elapsed monotonic time