Module time/duration
Duration type representing a span of time with nanosecond precision.
Example
{ Duration } :: import "std/time/duration";
d := Duration.from_millis(i64(500));
println(d.as_secs()); // 0
println(d.as_millis()); // 500
Stability
unstable — the signedness question is open, and it is not cosmetic. Rust's
Duration is (u64, u32), so a negative span cannot exist; Yo's is
(i64, i64), so Duration.from_secs(i64(-1)) is an ordinary safe call.
The type then takes two stances at once: from_secs_f64 clamps a negative
input to zero and sub saturates at zero, while the four integer
constructors store the negative value as given. That already has a
consequence outside this file — std/time/sleep.yo casts as_millis() to
an unsigned count, so a negative span sleeps ~585 million years instead of
returning at once
(issues/stddoc-io-negative-duration-sleeps-forever.md).
Freezing needs that decided — unsigned like Rust, or signed with the clamp
made uniform — and needs the checked_*/saturating_* family that add
lacks, plus the mul/div Rust has and accessor widths that do not
overflow at 292 years (Rust returns u128 from as_nanos). The member
names and units are Rust's and are not expected to move.
Types
Span of time stored as seconds and nanoseconds.
Signed, unlike Rust's Duration, which is (u64, u32) and so cannot
hold a negative span. See ## Stability — the divergence is an open
question, not a feature.
Fields
| Name | Type | Description |
|---|---|---|
secs | i64 | Whole seconds; negative for a negative span. |
nanos | i64 | Sub-second part, strictly between |
Trait Implementations
impl(generic(T : Type), where(T <: ToString), T : (ToString))
impl(generic(T : Type), where(T <: ToString), T : (ToString), Format)
format : fn(self : Self, spec : str) -> StringRender self under spec. An unrecognised spec degrades to the plain
to_string() rendering rather than failing.
Parameters
| Name | Type | Notes |
|---|---|---|
self | Self | |
spec | str |
Returns: String
impl(Duration, ...)
from_secs : (Duration) fn(secs : i64) -> DurationA span of secs whole seconds — Rust's Duration::from_secs.
Parameters
| Name | Type | Notes | Description |
|---|---|---|---|
secs | i64 | Whole seconds; negative for a negative span. |
Returns: Duration
from_millis : (Duration) fn(millis : i64) -> DurationA span given in milliseconds. The remainder lands in nanos exactly,
so nothing is rounded away — Rust's Duration::from_millis.
Parameters
| Name | Type | Notes |
|---|---|---|
millis | i64 |
Returns: Duration
from_micros : (Duration) fn(micros : i64) -> DurationA span given in microseconds, exactly — Rust's
Duration::from_micros.
Parameters
| Name | Type | Notes |
|---|---|---|
micros | i64 |
Returns: Duration
zero : (Duration) fn() -> DurationThe zero-length span — the only value is_zero answers true for, and
what sub returns when it saturates.
Returns: Duration
from_nanos : (Duration) fn(nanos : i64) -> DurationA span given in nanoseconds — the finest resolution the type stores, so this is the exact constructor.
Parameters
| Name | Type | Notes | Description |
|---|---|---|---|
nanos | i64 | Sub-second part, strictly between |
Returns: Duration
as_secs : (Duration) fn(self : Duration) -> i64Whole seconds, truncating the sub-second part toward zero — this is the
secs field, so 1.999 s reads as 1. Rust's Duration::as_secs.
Parameters
| Name | Type | Notes |
|---|---|---|
self | Duration |
Returns: i64
as_millis : (Duration) fn(self : Duration) -> i64Total milliseconds, truncated toward zero. Computed as
secs * 1000 + nanos / 1e6, so it overflows i64 for spans beyond
~2.9e8 years — Rust returns a u128 here for that reason.
Parameters
| Name | Type | Notes |
|---|---|---|
self | Duration |
Returns: i64
as_micros : (Duration) fn(self : Duration) -> i64Total microseconds, truncated toward zero. Same multiply-out as
as_millis, so it overflows i64 beyond ~292 000 years.
Parameters
| Name | Type | Notes |
|---|---|---|
self | Duration |
Returns: i64
as_nanos : (Duration) fn(self : Duration) -> i64Total nanoseconds — exact for every value this type can hold up to
~292 years, past which secs * 1e9 overflows i64 (signed overflow is
UB in C, so this is not a wrap you may rely on). Rust returns u128.
Parameters
| Name | Type | Notes |
|---|---|---|
self | Duration |
Returns: i64
as_secs_f64 : (Duration) fn(self : Duration) -> f64Total seconds as an f64 — Rust's Duration::as_secs_f64. An f64
carries 53 significant bits, so beyond ~104 days the nanosecond part no
longer fits and the result quietly loses sub-nanosecond precision.
Parameters
| Name | Type | Notes |
|---|---|---|
self | Duration |
Returns: f64
add : (Duration) fn(self : Duration, other : Duration) -> Durationsub : (Duration) fn(self : Duration, other : Duration) -> Durationself - other, SATURATING at zero — a subtraction that would go
negative returns Duration.zero(). That is Rust's saturating_sub
behaviour under the plain name, and it is why a span produced by
subtraction is never negative even though the type could hold one.
Both sides go through as_nanos, so this inherits its ~292-year
overflow bound.
Parameters
| Name | Type | Notes |
|---|---|---|
self | Duration | |
other | Duration |
Returns: Duration
is_zero : (Duration) fn(self : Duration) -> boolTrue only for the zero span, both fields being zero — Rust's
Duration::is_zero.
Parameters
| Name | Type | Notes |
|---|---|---|
self | Duration |
Returns: bool
impl(Duration, ToString(...))
to_string : (Duration) fn(self : Duration) -> Stringimpl(Duration, ...)
SECOND : (Duration) fn() -> DurationOne second.
Returns: Duration
MILLISECOND : (Duration) fn() -> DurationOne millisecond.
Returns: Duration
MICROSECOND : (Duration) fn() -> DurationOne microsecond.
Returns: Duration
NANOSECOND : (Duration) fn() -> DurationOne nanosecond.
Returns: Duration
MINUTE : (Duration) fn() -> DurationOne minute.
Returns: Duration
HOUR : (Duration) fn() -> DurationOne hour.
Returns: Duration
from_secs_f64 : (Duration) fn(secs : f64) -> DurationFrom fractional seconds (Duration.from_secs_f64(0.25) = 250ms).
Sub-nanosecond precision truncates toward zero; negative inputs clamp
to zero (a Duration is a non-negative span, like sub's saturation).
Parameters
| Name | Type | Notes | Description |
|---|---|---|---|
secs | f64 | Whole seconds; negative for a negative span. |
Returns: Duration
subsec_millis : (Duration) fn(self : Duration) -> i64subsec_micros : (Duration) fn(self : Duration) -> i64The sub-second part in microseconds (0..999_999).
Parameters
| Name | Type | Notes |
|---|---|---|
self | Duration |
Returns: i64
subsec_nanos : (Duration) fn(self : Duration) -> i64The sub-second part in nanoseconds (0..999_999_999).
Parameters
| Name | Type | Notes |
|---|---|---|
self | Duration |
Returns: i64
impl(Duration, Add(Duration)(...))
Output : Durationimpl(Duration, Sub(Duration)(...))
Output : Durationimpl(Duration, Eq(Duration)(...))
impl(Duration, Ord(Duration)(...))
impl(Duration, Hash(...))
impl(Duration, Default(...))
default : (Duration) fn() -> DurationThe default value of the type.
Returns: Duration
Methods
+ : (Duration) fn(self : Duration, other : Duration) -> Duration- : (Duration) fn(self : Duration, other : Duration) -> Duration== : (Duration) fn(lhs : Duration, rhs : Duration) -> bool!= : (Duration) fn(lhs : Duration, rhs : Duration) -> bool< : (Duration) fn(lhs : Duration, rhs : Duration) -> bool<= : (Duration) fn(lhs : Duration, rhs : Duration) -> bool> : (Duration) fn(lhs : Duration, rhs : Duration) -> bool>= : (Duration) fn(lhs : Duration, rhs : Duration) -> bool