Skip to main content

Module duration

tempoch_core::foundation

Module duration 

Source
Expand description

Exact-precision duration container.

ExactDuration is the canonical duration type for tempoch. Its representation is deliberately opaque: today it is backed by a single i128 of nanoseconds (range ≈ ±5.4 × 10²¹ yr at 1 ns resolution). A future internal migration to i128 attoseconds or another sub-nanosecond representation is a non-breaking change as long as callers go through the named accessors (as_seconds_i64_nanos, as_seconds_f64, …).

§Design choices

  • Sign convention — a single signed integer carries the sign uniformly. This avoids the classic {whole_seconds: i64, sub_nanos: u32} pitfall where -0.5 s must be represented as {-1, 500_000_000} and negation becomes asymmetric near zero.
  • No f64 in the public exact API — f64 boundaries are reachable only through explicitly named methods (from_seconds_f64_lossy, as_seconds_f64) so users see the lossy step in code review.
  • qtty interop — ExactDuration::from_quantity / ExactDuration::as_quantity bridge to typed Quantity<U> for any qtty::time::TimeUnit. The bridge through f64 is intentional: qtty itself is a floating-point quantity system; users wanting exact duration math should keep values inside ExactDuration.
  • Overflow — arithmetic uses checked operations and reports DurationError::Overflow when the result leaves the i128 range; the public +/- operators panic on overflow (debug + release) to match Duration/std::time ergonomics. Use ExactDuration::checked_add / ExactDuration::checked_sub / ExactDuration::checked_neg for non-panicking callers (FFI, parsers, formal-verification harnesses).

§Future-proofing

Because the storage is opaque and the boundary projection (seconds: i64, nanos: u32) is the only serde shape, migrating to a sub-nanosecond representation is non-breaking; callers requesting attosecond precision in serde will opt in through a future serde-attos feature.

Structs§

ExactDuration
Exact-precision signed duration.

Enums§

DurationError
Error type for fallible ExactDuration operations.

Constants§

NANOS_PER_SECOND
Nanoseconds per second; convenience constant for boundary code.