Skip to content
Protos

std:datetime/Instant

std:datetime/Instant

Section titled “std:datetime/Instant”

Canonical occurrence: protos/lib/datetime/Instant.protos · Protos revision: e99b712ecf658a527b1fe82c8beba2c1286d8dc9.

Instants on a uniform timeline with nanosecond precision. An instant is a frozen ordinary object with one Integer nanoseconds slot holding the exact signed count of uniform nanoseconds from the conceptual reference 1970-01-01T00:00:00Z: Instant(0) is that reference, Instant(-1) is one nanosecond before it, and Instant(1) one nanosecond after it. Integers are exact and unbounded, so no host timestamp, machine-word, or other artificial range applies.

The timeline is Unix-like: every day has exactly 86400 uniform seconds. Leap seconds, TAI, and GPS time are not represented, and this is not a claim of physically exact UTC. An instant carries no offset, zone, or clock state, and nothing here reads a current time.

Every instant’s immediate delegation parent is this module, the canonical instant factory and prototype. recognizes accepts exactly the instants of this family: objects whose immediate parent is this module and whose local slots are exactly the instant state and behavior slots with an Integer position. A nanoseconds slot under another parent, such as a std:datetime/Duration, is not an instant.

Instants answer semantic equality through ==: two instants are equal when both are instants at the same timeline position. hash is coherent with that equality, so independently constructed equal instants work as the same Map key. === remains ordinary object identity. compare is the natural timeline order and answers 0 exactly for equal instants.

Observable top-level slots

Section titled “Observable top-level slots”

This page lists the complete mechanically observable top-level slot inventory required by D067. Authored documentation, when present, is canonical D062 prose; mechanical presence alone does not create a stability or compatibility promise.

addDuration

Section titled “addDuration”

Answers a fresh instant exactly duration.nanoseconds after instant (before it for a negative duration). Arguments that are not an instant and a std:datetime/Duration signal an Error.

Mechanical facts

Section titled “Mechanical facts”

call

Section titled “call”

Answers a fresh frozen instant nanoseconds uniform nanoseconds from 1970-01-01T00:00:00Z. nanoseconds must be an Integer and may be positive, zero, or negative; any other argument signals an Error.

Mechanical facts

Section titled “Mechanical facts”

compare

Section titled “compare”

Answers -1, 0, or 1 as instant left is before, equal to, or after instant right on the timeline. The result is 0 exactly when left == right. Arguments must be instants recognized by this module; otherwise an Error is signalled.

Mechanical facts

Section titled “Mechanical facts”

durationBetween

Section titled “durationBetween”

Answers the std:datetime/Duration of exactly end.nanoseconds - start.nanoseconds, so that addDuration(start, durationBetween(start, end)) == end. The duration is negative when end is before start. Non-instant arguments signal an Error.

Mechanical facts

Section titled “Mechanical facts”

recognizes

Section titled “recognizes”

Answers true exactly when value is an instant of this family: its immediate delegation parent is this module, its local slots are exactly nanoseconds, equals, ==, and hash, and nanoseconds is an Integer. Answers false for any other value.

Mechanical facts

Section titled “Mechanical facts”

subtractDuration

Section titled “subtractDuration”

Answers a fresh instant exactly duration.nanoseconds before instant; equivalent to addDuration(instant, Duration.negate(duration)). Arguments that are not an instant and a std:datetime/Duration signal an Error.

Mechanical facts

Section titled “Mechanical facts”

Exact module source · Standard-library API · Standard library overview