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#

silk
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#

silk
pub struct Duration

A 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#

silk
impl Copy for Duration

Implementation Duration#

silk
impl Duration

Associated function zero#

silk
pub fn zero() -> Duration

Returns the empty span.

Associated function make#

silk
pub fn make(seconds: i64, nanoseconds: i64) -> Duration

Returns 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#

silk
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#

silk
pub fn fromHours(hours: i64) -> Duration

Returns the span of hours hours of 3600 seconds each. A total outside the range traps.

Associated function fromMinutes#

silk
pub fn fromMinutes(minutes: i64) -> Duration

Returns the span of minutes minutes of 60 seconds each. A total outside the range traps.

Associated function fromSeconds#

silk
pub fn fromSeconds(seconds: i64) -> Duration

Returns the span of seconds seconds.

Associated function fromMilliseconds#

silk
pub fn fromMilliseconds(milliseconds: i64) -> Duration

Returns the span of milliseconds milliseconds. Each i64 value is in range.

Associated function fromMicroseconds#

silk
pub fn fromMicroseconds(microseconds: i64) -> Duration

Returns the span of microseconds microseconds. Each i64 value is in range.

Associated function fromNanoseconds#

silk
pub fn fromNanoseconds(nanoseconds: i64) -> Duration

Returns the span of nanoseconds nanoseconds. Each i64 value is in range.

Method wholeSeconds#

silk
pub fn wholeSeconds(self: Self) -> i64

Returns 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#

silk
pub fn subsecondNanoseconds(self: Self) -> u32

Returns 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#

silk
pub fn round(self: Self, step: TimeIncrement, mode: RoundingMode) -> Duration

Returns 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#

silk
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#

silk
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#

silk
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#

silk
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#

silk
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#

silk
pub fn toSecondsF64(self: Self) -> f64

Returns the span in seconds as a float. Spans above 2^53 nanoseconds lose precision.

Method isZero#

silk
pub fn isZero(self: Self) -> bool

Returns true if the span is empty.

Method isNegative#

silk
pub fn isNegative(self: Self) -> bool

Returns true if the span is less than zero.

Method sign#

silk
pub fn sign(self: Self) -> i32

Returns -1 for a negative span, 0 for the empty span, and 1 for a positive span.

Method checkedNegate#

silk
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#

silk
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#

silk
pub fn absolute(self: Self) -> Duration

Returns the span without its sign. A result outside the range traps.

Method checkedAdd#

silk
pub fn checkedAdd(self: Self, other: Duration) -> Option<Duration>

Returns self + other, or None when the sum is outside the range.

Method checkedSubtract#

silk
pub fn checkedSubtract(self: Self, other: Duration) -> Option<Duration>

Returns self - other, or None when the difference is outside the range.

Method checkedMultiply#

silk
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#

silk
impl Equal for Duration

Operation equals#

silk
equals: Duration.same

Implementation Order for Duration#

silk
impl Order for Duration

Operation compare#

silk
compare: Duration.compare

Implementation Add<Duration, Duration> for Duration#

silk
impl Add<Duration, Duration> for Duration

Operation add#

silk
add: Duration.addOperator

Implementation Subtract<Duration, Duration> for Duration#

silk
impl Subtract<Duration, Duration> for Duration

Operation subtract#

silk
subtract: Duration.subtractOperator

Implementation Multiply<i64, Duration> for Duration#

silk
impl Multiply<i64, Duration> for Duration

Operation multiply#

silk
multiply: Duration.multiplyOperator

Implementation Multiply<i32, Duration> for Duration#

silk
impl Multiply<i32, Duration> for Duration

Operation multiply#

silk
multiply: Duration.multiplyOperator32

Implementation Negate<Duration> for Duration#

silk
impl Negate<Duration> for Duration

Operation negate#

silk
negate: Duration.negateOperator

Implementation Display for Duration#

silk
impl Display for Duration

Writes 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#

silk
effect fn display(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Implementation Debug for Duration#

silk
impl Debug for Duration

Writes the same text as Display: an ISO 8601 duration such as PT1H30M.

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Category: 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.

View the source of this page