std.time.Duration

Value

type pub copy Duration

A span of time measured in nanoseconds.

A Duration can be used to measure the span of time without having to worry about casting the time to different scales yourself. A Duration can be created using various scales such as seconds and milliseconds.

Duration measures a time duration in nanoseconds, limiting it to durations of up to 292 years. Operations producing values greater than this range will panic.

Duration objects can represent negative durations such as "-5 seconds". This is useful when performing arithmetic on Duration objects, as you won't have to worry about overflows. It also lets you represent a duration that goes back in time, i.e. "something that happened 5 seconds ago".

Static methods

from_micros

Show source code

fn pub inline static from_micros[T: ToInt](micros: ref T) -> Duration {
  Duration(micros.to_int * MILLIS_PER_SEC)
}

fn pub inline static from_micros[T: ToInt](micros: ref T) -> Duration

Creates a new Duration from the given number of microseconds.

Examples

import std.time (Duration)

Duration.from_micros(10)

from_millis

Show source code

fn pub inline static from_millis[T: ToInt](millis: ref T) -> Duration {
  Duration(millis.to_int * MICROS_PER_SEC)
}

fn pub inline static from_millis[T: ToInt](millis: ref T) -> Duration

Creates a new Duration from the given number of milliseconds.

Examples

import std.time (Duration)

Duration.from_millis(10)

from_nanos

Show source code

fn pub inline static from_nanos[T: ToInt](nanos: ref T) -> Duration {
  Duration(nanos.to_int)
}

fn pub inline static from_nanos[T: ToInt](nanos: ref T) -> Duration

Creates a new Duration from the given number of nanoseconds.

Examples

import std.time (Duration)

Duration.from_nanos(10)

from_secs

Show source code

fn pub inline static from_secs[T: ToFloat](secs: ref T) -> Duration {
  Duration((secs.to_float * NANOS_PER_SEC).to_int)
}

fn pub inline static from_secs[T: ToFloat](secs: ref T) -> Duration

Creates a new Duration from the given number of seconds.

Examples

import std.time (Duration)

Duration.from_secs(10.5)

Instance methods

!=

Show source code

fn pub !=(other: T) -> Bool {
  (self == other).false?
}

fn pub !=(other: T) -> Bool

Returns true if self and the given object are not equal to each other.

*

Show source code

fn pub inline *(other: Int) -> Duration {
  Duration(@nanos * other)
}

fn pub inline *(other: Int) -> Duration

Multiplies self with the given object.

+

Show source code

fn pub inline +(other: Duration) -> Duration {
  Duration(@nanos + other.nanos)
}

fn pub inline +(other: Duration) -> Duration

Adds the given object to self.

-

Show source code

fn pub inline -(other: Duration) -> Duration {
  Duration(@nanos - other.nanos)
}

fn pub inline -(other: Duration) -> Duration

Subtracts the given object from self.

/

Show source code

fn pub inline /(other: Int) -> Duration {
  Duration(@nanos / other)
}

fn pub inline /(other: Int) -> Duration

Divides self by the given object.

<

Show source code

fn pub <(other: ref T) -> Bool {
  match cmp(other) {
    case Less -> true
    case _ -> false
  }
}

fn pub <(other: ref T) -> Bool

Returns true if self is lower than the given argument.

<=

Show source code

fn pub <=(other: ref T) -> Bool {
  match cmp(other) {
    case Less or Equal -> true
    case _ -> false
  }
}

fn pub <=(other: ref T) -> Bool

Returns true if self is lower than or equal to the given argument.

==

Show source code

fn pub inline ==(other: Duration) -> Bool {
  @nanos == other.nanos
}

fn pub inline ==(other: Duration) -> Bool

Returns true if self and the given object are equal to each other.

This operator is used to perform structural equality. This means two objects residing in different memory locations may be considered equal, provided their structure is equal. For example, two different arrays may be considered to have structural equality if they contain the exact same values.

>

Show source code

fn pub >(other: ref T) -> Bool {
  match cmp(other) {
    case Greater -> true
    case _ -> false
  }
}

fn pub >(other: ref T) -> Bool

Returns true if self is greater than the given argument.

>=

Show source code

fn pub >=(other: ref T) -> Bool {
  match cmp(other) {
    case Greater or Equal -> true
    case _ -> false
  }
}

fn pub >=(other: ref T) -> Bool

Returns true if self is equal to or greater than the given argument.

clone

Show source code

fn pub inline clone -> Duration {
  Duration(@nanos)
}

fn pub inline clone -> Duration

Creates a clone of self.

cmp

Show source code

fn pub inline cmp(other: Duration) -> Ordering {
  @nanos.cmp(other.nanos)
}

fn pub inline cmp(other: Duration) -> Ordering

Returns the ordering between self and the given argument.

The returned value should be as follows:

a == b: Ordering.Equal
a > b: Ordering.Greater
a < b: Ordering.Less

fmt

Show source code

fn pub fmt(formatter: mut Formatter) {
  let abs = @nanos.absolute
  let write = if abs >= 1_000_000_000 {
    '${to_secs} sec'
  } else if abs >= 1_000_000 {
    '${to_millis} msec'
  } else if abs >= 1_000 {
    '${to_micros} µsec'
  } else {
    '${@nanos} nsec'
  }

  formatter.write(write)
}

fn pub fmt(formatter: mut Formatter)

Formats self in a human-readable format for debugging purposes.

positive?

Show source code

fn pub inline positive? -> Bool {
  @nanos > 0
}

fn pub inline positive? -> Bool

Returns true if self is greater than zero.

Examples

import std.time (Duration)

Duration.from_secs(1).positive? # => true
Duration.from_secs(0).positive? # => false

to_instant

Show source code

fn pub inline to_instant -> Instant {
  Instant.new + self
}

fn pub inline to_instant -> Instant

Adds self to the current monotonic time, returning a new Instant representing the resulting point in time.

Examples

import std.time (Duration, Instant)

let duration = Duration.from_secs(5)

duration.to_instant.remaining <= duration # => true

Panics

This method panics if the resulting Instant is invalid, such as when it's a negative time.

to_micros

Show source code

fn pub inline to_micros -> Int {
  @nanos / MILLIS_PER_SEC
}

fn pub inline to_micros -> Int

Returns the duration in microseconds.

Examples

import std.time (Duration)

Duration.from_secs(5).to_micros # => 5000000

to_millis

Show source code

fn pub inline to_millis -> Int {
  @nanos / MICROS_PER_SEC
}

fn pub inline to_millis -> Int

Returns the duration in milliseconds.

Examples

import std.time (Duration)

Duration.from_secs(5).to_millis # => 5000

to_nanos

Show source code

fn pub inline to_nanos -> Int {
  @nanos
}

fn pub inline to_nanos -> Int

Returns the duration in nanoseconds.

Examples

import std.time (Duration)

Duration.from_secs(5).to_nanos # => 5000000000

to_secs

Show source code

fn pub inline to_secs -> Float {
  @nanos.to_float / NANOS_PER_SEC
}

fn pub inline to_secs -> Float

Returns the duration in seconds.

Examples

import std.time (Duration)

Duration.from_secs(5).to_secs # => 5.0

zero?

Show source code

fn pub inline zero? -> Bool {
  @nanos == 0
}

fn pub inline zero? -> Bool

Returns true if self is zero.

Examples

import std.time (Duration)

Duration.from_secs(1).zero? # => false
Duration.from_secs(0).zero? # => true

Implemented traits

std.clone.

Clone

impl Clone[Duration] for Duration

std.cmp.

Compare

impl Compare[Duration] for Duration

std.cmp.

Equal

impl Equal[Duration] for Duration

std.fmt.

Format

impl Format for Duration

std.ops.

Add

impl Add[Duration, Duration] for Duration

std.ops.

Divide

impl Divide[Int, Duration] for Duration

std.ops.

Multiply

impl Multiply[Int, Duration] for Duration

std.ops.

Subtract

impl Subtract[Duration, Duration] for Duration

std.time.

ToInstant

impl ToInstant for Duration