Timestamp

Module std.time

import std.time;

Public declaration contracts and authored examples. A page can document several related symbols. Implementation bodies are excluded.

Timestamp

pub struct Timestamp

Stores a finite UTC timestamp distinct from monotonic clock time.

The value owns signed nanoseconds since the Unix epoch; negative values are valid. Arithmetic allocates nothing and retains no external storage. Concurrent immutable use is safe; shared mutation requires caller synchronization. Wall timestamps can move backwards when a clock is adjusted and must not measure monotonic deadlines. No implicit Instant conversion exists.

Example

module example.timestamp_arithmetic;
from std.time import Timestamp, Seconds, Nanoseconds, DurationError;
fn Main() -> i32 {
    let Before = switch Timestamp.TryFromUnixDuration(Seconds.Create(-1)) {
        case .Ok { Value = Value } => break Value;
        case .Err { Error = _ } => return 1;
    };
    let After = switch Before.TryAdd(Seconds.Create(2)) {
        case .Ok { Value = Value } => break Value;
        case .Err { Error = _ } => return 2;
    };
    if Before.UnixTime.Count != -1000000000_i128 { return 3; }
    if After.UnixTime.Count != 1000000000_i128 { return 4; }
    // Direct comparison reads the stored UTC values without subtraction or
    // another adjustable-clock sample, including equality and reverse order.
    if Before.Compare(After) >= 0 || After.Compare(Before) <= 0 || Before.Compare(Before) != 0 { return 32; }
    switch After.TryDifference(Before) {
        case .Ok { Value = Delta } => { if Delta.Count != 2000000000_i128 { return 5; } }
        case .Err { Error = _ } => return 6;
    }
    switch Before.TryDifference(After) {
        case .Ok { Value = Delta } => { if Delta.Count != -2000000000_i128 { return 24; } }
        case .Err { Error = _ } => return 25;
    }
    switch Before.TryDifference(Before) {
        case .Ok { Value = Delta } => { if Delta.Count != 0_i128 { return 26; } }
        case .Err { Error = _ } => return 27;
    }
    switch After.TryAdd(Nanoseconds.Create(0)) {
        case .Ok { Value = Value } => { if Value.UnixTime.Count != 1000000000_i128 { return 28; } }
        case .Err { Error = _ } => return 29;
    }
    switch Before.TrySubtract(Nanoseconds.Create(0)) {
        case .Ok { Value = Value } => { if Value.UnixTime.Count != -1000000000_i128 { return 30; } }
        case .Err { Error = _ } => return 31;
    }
    switch After.TrySubtract(Nanoseconds.Create(1)) {
        case .Ok { Value = Value } => { if Value.UnixTime.Count != 999999999_i128 { return 7; } }
        case .Err { Error = _ } => return 8;
    }
    // Sampling owns detached UTC values; wall time can move backwards, so
    // validate exact round trips without comparing two clock samples.
    let Sampled = switch Timestamp.TryNow() {
        case .Ok { Value = Value } => break Value;
        case .Err => return 33;
    };
    let SampledCopy = switch Timestamp.TryFromUnixDuration(Sampled.UnixTime) {
        case .Ok { Value = Value } => break Value;
        case .Err => return 34;
    };
    let Direct = Timestamp.Now();
    let DirectCopy = switch Timestamp.TryFromUnixDuration(Direct.UnixTime) {
        case .Ok { Value = Value } => break Value;
        case .Err => return 35;
    };
    if Sampled.Compare(SampledCopy) != 0 || Direct.Compare(DirectCopy) != 0 { return 36; }
    return 0;
}

Timestamp.fn

pub static const fn Create(UnixTime: Duration<i128, 1, 1000000000>) -> Timestamp

Stores explicit Unix nanoseconds without allocation or clock sampling. UnixTime: Owned finite epoch-relative value; negative dates are valid. Return: Independent timestamp without allocation, synchronization or sampling.

Timestamp.TryNow

pub static fn TryNow() -> Result<Timestamp, TimeError>

Samples adjustable Unix wall time. Return: Owned timestamp or checked platform sampling failure.

Timestamp.Now

pub static fn Now() -> Timestamp

Samples Unix wall time, trapping checked sampling failure. Return: Owned timestamp; use TryNow for recovery.

Timestamp.TryFromUnixDuration

pub static fn TryFromUnixDuration<Rep, const Numerator: u64, const Denominator: u64>(
        UnixTime: readonly Duration<Rep, Numerator, Denominator>&) -> Result<Timestamp, DurationError>
        where Rep: Data, DurationCount

Constructs a timestamp from an exactly convertible Unix duration. Rep: Copyable Defaultable numeric count representation. Numerator: Positive rational seconds numerator. Denominator: Positive rational seconds denominator. UnixTime: Epoch-relative duration borrowed only for this call. Return: Owned timestamp or exact-conversion range/precision error.

Timestamp.UnixTime

pub UnixTime: Duration<i128, 1, 1000000000>;

Observes signed Unix nanoseconds as an owned duration. Return: Exact finite value copy.

Timestamp.TryAdd

pub readonly fn TryAdd<Rep, const Numerator: u64, const Denominator: u64>(
        Delta: readonly Duration<Rep, Numerator, Denominator>&) -> Result<Timestamp, DurationError>
        where Rep: Data, DurationCount

Adds an exact finite duration with checked timestamp range. Rep: Copyable Defaultable count representation. Numerator: Positive seconds numerator. Denominator: Positive seconds denominator. Delta: Borrowed displacement; negative displacements are valid. Return: New timestamp or conversion/arithmetic error; this value is unchanged.

Timestamp.TrySubtract

pub readonly fn TrySubtract<Rep, const Numerator: u64, const Denominator: u64>(
        Delta: readonly Duration<Rep, Numerator, Denominator>&) -> Result<Timestamp, DurationError>
        where Rep: Data, DurationCount

Subtracts an exact finite duration without negating a signed minimum. Rep: Copyable Defaultable count representation. Numerator: Positive seconds numerator. Denominator: Positive seconds denominator. Delta: Borrowed displacement; negative displacements are valid. Return: New timestamp or conversion/arithmetic error; this value is unchanged.

Timestamp.TryDifference

pub readonly fn TryDifference(Other: readonly Timestamp&) -> Result<Duration<i128, 1, 1000000000>, DurationError>

Computes checked signed nanoseconds between UTC timestamps. Other: Timestamp borrowed only for this subtraction. Return: Signed elapsed duration or RangeOverflow; wall-clock monotonicity is not implied.

Timestamp.Compare

pub readonly fn Compare(Other: readonly Timestamp&) -> i32

Compares two stored UTC timestamps without arithmetic overflow. Other: Timestamp borrowed only for this comparison. Return: Negative, zero or positive according to chronological stored value order.

Timestamp.operator

pub readonly fn operator +<Rep, const Numerator: u64, const Denominator: u64>(
        Delta: readonly Duration<Rep, Numerator, Denominator>&) -> Timestamp where Rep: Data, DurationCount

Adds an exact duration, trapping on checked conversion/range failure. Rep: Copyable Defaultable count representation. Numerator: Positive seconds numerator. Denominator: Positive seconds denominator. Delta: Borrowed finite displacement. Return: New timestamp; use TryAdd for recoverable failure.

Timestamp.operator

pub readonly fn operator -<Rep, const Numerator: u64, const Denominator: u64>(
        Delta: readonly Duration<Rep, Numerator, Denominator>&) -> Timestamp where Rep: Data, DurationCount

Subtracts an exact duration, trapping on checked conversion/range failure. Rep: Copyable Defaultable count representation. Numerator: Positive seconds numerator. Denominator: Positive seconds denominator. Delta: Borrowed finite displacement. Return: New timestamp; use TrySubtract for recoverable failure.

Timestamp.operator

pub readonly fn operator -(Other: readonly Timestamp&) -> Duration<i128, 1, 1000000000>

Subtracts stored timestamps with checked signed nanosecond range. Other: Borrowed UTC timestamp. Return: Signed duration; range failure traps. Use TryDifference for recoverable errors.

Timestamp.operator

pub readonly fn operator == (Other: readonly Timestamp&) -> bool

Compares stored UTC values without subtracting or sampling a clock. Other: Timestamp borrowed only during comparison. Return: Whether the chronological == relation holds.

Timestamp.operator

pub readonly fn operator < (Other: readonly Timestamp&) -> bool

Compares stored UTC values without subtracting or sampling a clock. Other: Timestamp borrowed only during comparison. Return: Whether the chronological < relation holds.

Timestamp.operator

pub readonly fn operator <= (Other: readonly Timestamp&) -> bool

Compares stored UTC values without subtracting or sampling a clock. Other: Timestamp borrowed only during comparison. Return: Whether the chronological <= relation holds.

Timestamp.operator

pub readonly fn operator > (Other: readonly Timestamp&) -> bool

Compares stored UTC values without subtracting or sampling a clock. Other: Timestamp borrowed only during comparison. Return: Whether the chronological > relation holds.

Timestamp.operator

pub readonly fn operator >= (Other: readonly Timestamp&) -> bool

Compares stored UTC values without subtracting or sampling a clock. Other: Timestamp borrowed only during comparison. Return: Whether the chronological >= relation holds.