silk.time.duration.
Exact elapsed time: the Duration type, a signed span of seconds and nanoseconds.
When to use#
Use Duration for a timeout, a measured time, or the distance between two instants. It
counts real time only, so an hour is always 3600 seconds. A span in calendar units, such as
"one month", has no fixed length and is not a Duration.
Details#
A Duration holds signed whole seconds and a nanosecond part from 0 to 999,999,999. Two equal
spans always have equal fields, so == and < compare spans. +, -, unary -, and * by
an i64 are exact and trap when the result leaves the range. The checked functions return
None instead.
Examples#
Add two spans and read the parts#
import silk.time.duration { Duration }
pub fn main() -> i32 {
let total = Duration.fromSeconds(90) + Duration.fromMilliseconds(1500)
if total.wholeSeconds() != 91 || total.subsecondNanoseconds() != 500000000 {
return 1
}
if !(&Duration.fromMinutes(1) < &total) {
return 2
}
return 0
}Import as Duration with import silk.time.duration { Duration }.
Public declarations: 1.
Duration#
pub struct DurationA signed span of exact time with nanosecond precision.
Details#
The span is wholeSeconds seconds plus subsecondNanoseconds nanoseconds. The nanosecond part
is always from 0 to 999,999,999, also for a negative span: one nanosecond before zero is -1
second plus 999,999,999 nanoseconds. Equal spans have equal parts. The seconds cover the whole
i64 range, about 292 billion years in each direction.
==, !=, <, <=, >, and >= compare spans. +, -, unary -, and * by an i64
trap when the result is outside the range.
Implementation Copy for Duration#
impl Copy for DurationImplementation Duration#
impl DurationAssociated function zero#
pub fn zero() -> DurationReturns the empty span.
Associated function make#
pub fn make(seconds: i64, nanoseconds: i64) -> DurationReturns the span of seconds seconds plus nanoseconds nanoseconds.
Details#
Whole seconds in nanoseconds move into the seconds, and nanoseconds can be negative. So
Duration.make(0, 1500000000) is 1.5 seconds and Duration.make(1, -1) is one nanosecond
less than a second.
Gotchas#
A total outside the i64 seconds range traps. Duration.checkedMake returns None
instead.
Associated function checkedMake#
pub fn checkedMake(seconds: i64, nanoseconds: i64) -> Option<Duration>Returns the span of seconds seconds plus nanoseconds nanoseconds, or None when the total
is outside the i64 seconds range.
Details#
Whole seconds in nanoseconds move into the seconds, and nanoseconds can be negative.
Associated function fromHours#
pub fn fromHours(hours: i64) -> DurationReturns the span of hours hours of 3600 seconds each. A total outside the range traps.
Associated function fromMinutes#
pub fn fromMinutes(minutes: i64) -> DurationReturns the span of minutes minutes of 60 seconds each. A total outside the range traps.
Associated function fromSeconds#
pub fn fromSeconds(seconds: i64) -> DurationReturns the span of seconds seconds.
Associated function fromMilliseconds#
pub fn fromMilliseconds(milliseconds: i64) -> DurationReturns the span of milliseconds milliseconds. Each i64 value is in range.
Associated function fromMicroseconds#
pub fn fromMicroseconds(microseconds: i64) -> DurationReturns the span of microseconds microseconds. Each i64 value is in range.
Associated function fromNanoseconds#
pub fn fromNanoseconds(nanoseconds: i64) -> DurationReturns the span of nanoseconds nanoseconds. Each i64 value is in range.
Method wholeSeconds#
pub fn wholeSeconds(self: Self) -> i64Returns the whole seconds of the span, rounded toward negative infinity.
Details#
The span is this value plus Duration.subsecondNanoseconds. For -1.5 seconds the result is
-2, and the nanosecond part is 500,000,000.
Method subsecondNanoseconds#
pub fn subsecondNanoseconds(self: Self) -> u32Returns the nanosecond part of the span, from 0 to 999,999,999.
Details#
The part counts forward from Duration.wholeSeconds, also for a negative span. For -1.5
seconds the whole seconds are -2 and this part is 500,000,000.
Method round#
pub fn round(self: Self, step: TimeIncrement, mode: RoundingMode) -> DurationReturns the span rounded to a multiple of step.
Details#
A day is 24 hours. RoundingMode.HalfExpand is the rounding of school arithmetic: to the
nearest step, and away from zero from the middle.
Gotchas#
A result outside the range traps. Duration.checkedRound returns None instead.
Examples#
import silk.time.duration { Duration }
import silk.time.rounding { RoundingMode, TimeIncrement, TimeUnit }
pub fn main() -> i32 {
let span = Duration.make(3 * 3600 + 52 * 60 + 30, 0)
let quarter = TimeIncrement.of(15, TimeUnit.Minute)
let rounded = span.round(quarter, RoundingMode.HalfExpand)
if &rounded != &Duration.make(4 * 3600, 0) {
return 1
}
let down = (-span).round(TimeIncrement.one(TimeUnit.Hour), RoundingMode.Trunc)
if &down != &Duration.make(-3 * 3600, 0) {
return 2
}
return 0
}Method checkedRound#
pub fn checkedRound(self: Self, step: TimeIncrement, mode: RoundingMode) -> Option<Duration>Returns the span rounded to a multiple of step, or None when the result is outside the
range.
Method toMilliseconds#
pub fn toMilliseconds(self: Self) -> Option<i64>Returns the span in whole milliseconds, rounded toward zero, or None when the count does not
fit an i64.
Method toMicroseconds#
pub fn toMicroseconds(self: Self) -> Option<i64>Returns the span in whole microseconds, rounded toward zero, or None when the count does not
fit an i64.
Method toNanoseconds#
pub fn toNanoseconds(self: Self) -> Option<i64>Returns the span in nanoseconds, or None when the count does not fit an i64.
Details#
An i64 holds about 292 years of nanoseconds in each direction.
Method toSecondsF64#
pub fn toSecondsF64(self: Self) -> f64Returns the span in seconds as a float. Spans above 2^53 nanoseconds lose precision.
Method isZero#
pub fn isZero(self: Self) -> boolReturns true if the span is empty.
Method isNegative#
pub fn isNegative(self: Self) -> boolReturns true if the span is less than zero.
Method sign#
pub fn sign(self: Self) -> i32Returns -1 for a negative span, 0 for the empty span, and 1 for a positive span.
Method checkedNegate#
pub fn checkedNegate(self: Self) -> Option<Duration>Returns the span with the opposite sign, or None when it is outside the range.
Details#
Only spans within one second of the most negative value have no opposite.
Method checkedAbsolute#
pub fn checkedAbsolute(self: Self) -> Option<Duration>Returns the span without its sign, or None when it is outside the range.
Details#
Only spans within one second of the most negative value have no absolute value.
Method absolute#
pub fn absolute(self: Self) -> DurationReturns the span without its sign. A result outside the range traps.
Method checkedAdd#
pub fn checkedAdd(self: Self, other: Duration) -> Option<Duration>Returns self + other, or None when the sum is outside the range.
Method checkedSubtract#
pub fn checkedSubtract(self: Self, other: Duration) -> Option<Duration>Returns self - other, or None when the difference is outside the range.
Method checkedMultiply#
pub fn checkedMultiply(self: Self, factor: i64) -> Option<Duration>Returns the span factor times, or None when the product is outside the range.
Implementation Equal for Duration#
impl Equal for DurationOperation equals#
equals: Duration.sameImplementation Order for Duration#
impl Order for DurationOperation compare#
compare: Duration.compareImplementation Add<Duration, Duration> for Duration#
impl Add<Duration, Duration> for DurationOperation add#
add: Duration.addOperatorImplementation Subtract<Duration, Duration> for Duration#
impl Subtract<Duration, Duration> for DurationOperation subtract#
subtract: Duration.subtractOperatorImplementation Multiply<i64, Duration> for Duration#
impl Multiply<i64, Duration> for DurationOperation multiply#
multiply: Duration.multiplyOperatorImplementation Multiply<i32, Duration> for Duration#
impl Multiply<i32, Duration> for DurationOperation multiply#
multiply: Duration.multiplyOperator32Implementation Negate<Duration> for Duration#
impl Negate<Duration> for DurationOperation negate#
negate: Duration.negateOperatorImplementation Display for Duration#
impl Display for DurationWrites the span as an ISO 8601 duration in hours, minutes, and seconds, such as PT1H30M,
PT0.5S, or -PT45S. The empty span is PT0S.
Operation display#
effect fn display(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterImplementation Debug for Duration#
impl Debug for DurationWrites the same text as Display: an ISO 8601 duration such as PT1H30M.
Operation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterCategory: Time.
Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.