DurationPeriod

Module std.time

import std.time;

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

DurationPeriod

pub struct DurationPeriod

Stores a strictly positive reduced rational time period measured in seconds.

Period operations allocate nothing, retain no external storage and support concurrent immutable use. Declarative defaults form the one-second ratio. Named checked construction rejects zero scales; common-period selection reports range overflow rather than silently wrapping a denominator. Generic duration period identity/literal integration remains owned separately.

Example

module example.duration_conversion;
from std.time import DurationPeriod, DurationScale;
fn Main() -> i32 {
    let Milliseconds = switch DurationPeriod.TryCreate(1, 1000) {
        case .Ok { Value = Value } => break Value;
        case .Err { Error = _ } => return 1;
    };
    let Seconds = switch DurationPeriod.TryCreate(2, 2) {
        case .Ok { Value = Value } => break Value;
        case .Err { Error = _ } => return 2;
    };
    if Seconds.Numerator != 1 || Seconds.Denominator != 1 { return 3; }
    let Unit = default(DurationPeriod);
    if Unit.Numerator != 1 || Unit.Denominator != 1 { return 12; }
    let Identity = default(DurationScale);
    switch Identity.ConvertMagnitude(17, false, .Exact) {
        case .Ok { Value = Value } => { if Value != 17 { return 13; } }
        case .Err { Error = _ } => return 14;
    }
    let Common = switch Milliseconds.TryCommonPeriod(Seconds) {
        case .Ok { Value = Value } => break Value;
        case .Err { Error = _ } => return 15;
    };
    if Common.Numerator != 1 || Common.Denominator != 1000 { return 16; }
    let Scale = Milliseconds.ScaleTo(Seconds);
    if Scale.ConvertMagnitude(2250, false, .Exact) is .Ok { Value = _ } { return 4; }
    switch Scale.ConvertMagnitude(2250, false, .Floor) {
        case .Ok { Value = Value } => { if Value != 2 { return 5; } }
        case .Err { Error = _ } => return 6;
    }
    switch Scale.ConvertMagnitude(2250, true, .Floor) {
        case .Ok { Value = Value } => { if Value != 3 { return 7; } }
        case .Err { Error = _ } => return 8;
    }
    switch Scale.ConvertMagnitude(2500, false, .NearestEven) {
        case .Ok { Value = Value } => { if Value != 2 { return 9; } }
        case .Err { Error = _ } => return 10;
    }
    if DurationPeriod.TryCreate(0, 1) is .Ok { Value = _ } { return 11; }
    return 0;
}

DurationPeriod.fn

pub static const fn TryCreate(Numerator: u64, Denominator: u64) -> Result<DurationPeriod, DurationError>

Validates and reduces a positive rational period. Numerator: Nonzero numerator measured in seconds. Denominator: Nonzero denominator. Return: Reduced period or InvalidPeriod; no allocation or truncation.

DurationPeriod.Numerator

pub Numerator: u64;

Observes the reduced seconds numerator. Return: Positive reduced numerator.

DurationPeriod.Denominator

pub Denominator: u64;

Observes the reduced seconds denominator. Return: Positive reduced denominator.

DurationPeriod.fn

pub readonly const fn ScaleTo(Target: readonly DurationPeriod&) -> DurationScale

Computes the exact positive source-to-target count scale. Target: Positive reduced destination period, borrowed only during this call. Return: Reduced128-bit rational scale without forcing time into nanoseconds.

DurationPeriod.fn

pub readonly const fn TryCommonPeriod(Other: readonly DurationPeriod&) -> Result<DurationPeriod, DurationError>

Selects the finest reduced period needed for exact mixed-unit counts. Other: Positive reduced input period borrowed only during this call. Return: Common period or RangeOverflow when its reduced u64 denominator cannot fit.