index.nct

//! Normalized durations, monotonic elapsed time, and Unix wall-clock observations.

use /mem.TryAllocator
use /string.String

see ./duration.nct
see ./instant.nct
see ./primitives.nct
see ./sleep.nct
see ./system_time.nct
see ./tests.nct
see ./utc_calendar.nct
see ./rfc3339.nct

/// A normalized, non-negative span of time.
pub copy struct Duration

/// An opaque observation from the process monotonic-clock domain.
pub copy struct Instant

/// A normalized wall-clock instant relative to the Unix epoch.
pub copy struct SystemTime

/// A validated UTC date and time in the proleptic Gregorian calendar.
pub copy struct UtcDateTime

construct Duration {
    /// Creates a duration from whole seconds.
    pub noalloc func from_seconds(value: u64): Self

    /// Creates a duration from whole milliseconds without intermediate overflow.
    pub noalloc func from_milliseconds(value: u64): Self

    /// Creates a duration from whole microseconds without intermediate overflow.
    pub noalloc func from_microseconds(value: u64): Self

    /// Creates a duration from whole nanoseconds without intermediate overflow.
    pub noalloc func from_nanoseconds(value: u64): Self
}

instance Duration {
    /// Returns the normalized whole-second component.
    pub noalloc method &self.whole_seconds(): u64

    /// Returns the normalized subsecond component in nanoseconds.
    pub noalloc method &self.subsecond_nanoseconds(): u64

    /// Returns whether this duration has no length.
    pub noalloc method &self.is_zero(): bool

    /// Adds two durations, returning absence when the normalized result is unrepresentable.
    pub noalloc method &self.checked_add(other: &Self): Self?

    /// Subtracts a duration, returning absence when `other` is greater than this value.
    pub noalloc method &self.checked_sub(other: &Self): Self?

    /// Returns whether both durations denote the same normalized span.
    pub noalloc operator (&self == other: &Self): bool

    /// Returns whether this duration is shorter than `other`.
    pub noalloc operator (&self < other: &Self): bool
}

construct Instant {
    /// Observes the target monotonic clock.
    pub noalloc func now(): Self
}

instance Instant {
    /// Measures the non-negative duration from this observation to now.
    pub noalloc method &self.elapsed(): Duration
}

construct SystemTime {
    /// Creates an exact whole-second instant relative to the Unix epoch.
    pub noalloc func from_unix_seconds(seconds: i64): Self

    /// Creates an instant from Unix seconds and a subsecond nanosecond component.
    pub noalloc func from_unix_parts(seconds: i64, nanoseconds: u64): Self!

    /// Observes the target wall clock.
    pub noalloc func now(): Self!

    /// Parses the supported RFC 3339 profile and normalizes its offset to UTC.
    pub noalloc func parse_rfc3339(text: &str): Self!
}

instance SystemTime {
    /// Returns signed whole seconds relative to the Unix epoch.
    pub noalloc method &self.unix_seconds(): i64

    /// Returns the normalized subsecond nanosecond component.
    pub noalloc method &self.subsecond_nanoseconds(): u64

    /// Returns whether both values denote the same instant.
    pub noalloc operator (&self == other: &Self): bool

    /// Returns whether this instant precedes `other`.
    pub noalloc operator (&self < other: &Self): bool

    /// Converts this instant to UTC calendar components when its year is representable.
    pub noalloc method &self.to_utc(): UtcDateTime!

    /// Returns the canonical UTC RFC 3339 spelling.
    pub method &self.to_rfc3339(): String!

    /// Returns the same spelling using recoverable storage from `allocator`.
    pub method &self.try_to_rfc3339(allocator: &+TryAllocator): String! from allocator
}

construct UtcDateTime {
    /// Creates a validated UTC calendar value.
    pub noalloc func new(
        year: i64,
        month: i64,
        day: i64,
        hour: i64,
        minute: i64,
        second: i64,
        nanosecond: u64,
    ): Self!

    /// Converts a representable system-time instant to UTC calendar components.
    pub noalloc func from_system_time(value: &SystemTime): Self!
}

instance UtcDateTime {
    pub noalloc method &self.year(): i64
    pub noalloc method &self.month(): i64
    pub noalloc method &self.day(): i64
    pub noalloc method &self.hour(): i64
    pub noalloc method &self.minute(): i64
    pub noalloc method &self.second(): i64
    pub noalloc method &self.nanosecond(): u64

    /// Converts this UTC calendar value to its exact Unix wall-clock instant.
    pub noalloc method &self.to_system_time(): SystemTime

    /// Returns whether both values denote the same UTC instant.
    pub noalloc operator (&self == other: &Self): bool

    /// Returns whether this UTC value precedes `other`.
    pub noalloc operator (&self < other: &Self): bool
}

/// Blocks the current thread until at least `duration` has elapsed.
pub noalloc func sleep(duration: &Duration): void!