Skip to content

std::duration

Exact elapsed time. A Duration is a span of physical time in nanoseconds, the same length wherever a wall clock or a calendar puts it: build one with a unit function (Duration.seconds(5)) or the literal Display writes (Duration"1h30m"). Hours, minutes and seconds are units here; months and years are not, since they are no exact length. Instant + Duration is an Instant, and so is Instant - Duration; a - b on two instants is the Duration from b to a.

A time-bearing type of std::calendar adds a Duration as exact elapsed time: start + Duration.hours(24) moves the instant by 24 real hours, wherever the wall clock lands. The civil periods of std::calendar (Hours(24), Days(1), Months(1)) move the wall reading instead, so across a daylight-saving change + Hours(24) is not always + Duration.hours(24); std::calendar gives both.

A length reads for a person with Duration.format, in the locale’s words, and as a stopwatch shows it with Duration.clock, the same in every locale. A count of civil units from now (“in 3 days”, “yesterday”) is TimeUnit.format_relative in std::calendar, which takes a unit and a count, not a Duration, because a month is no fixed length.

Import with import std::duration.

type Duration Int

opaque — construction surface is private to its defining module

A length of time: a fixed span, the same whatever a wall clock or a calendar reads. It is a count of nanoseconds, so sub-second spans (timeouts, sleep intervals, elapsed measurements) add up exactly. Build one with a unit function (Duration.seconds(5), Duration.milliseconds(250)) or a literal (Duration"1h30m"), read it with the Duration.as_* functions, combine two with +, - and %, scale one with * and / by an Int, and compare two with ==, < and the rest of Comparable.

A Duration does not add to a Date, which has no time of day. Calendar and wall-clock arithmetic uses the civil periods of std::calendar. A Duration adds to an Instant and to the time-bearing calendar types, and timer.sleep and Context.with_timeout take one.

A Duration is an exact Int count of nanoseconds of any size, so no constructor and no +, - or * has a range to fault on, and the difference of any two Instants is a Duration. / takes a NonZeroInt and % a NonZeroDuration, so neither divides by zero. A function that hands a Duration to the clock (timer.sleep, Context.with_timeout, Arm.after, a server’s timeouts) says what a length past about 292 years, the longest wait the clock counts, means there: a wait that never ends.

assert Duration.minutes(90) == Duration"1h30m"
assert Duration.hours(1_000_000_000_000) / 1_000_000_000_000 == Duration.hours(1)
fn nanoseconds(n: Int) -> Duration

type function on Duration

Construct a Duration from whole nanoseconds.

assert Duration.as_nanos(Duration.nanoseconds(42)) == 42
fn microseconds(n: Int) -> Duration

type function on Duration

Construct a Duration from whole microseconds.

assert Duration.to_string(Duration.microseconds(1)) == "1µs"
assert Duration.as_nanos(Duration.microseconds(2)) == 2000
fn milliseconds(n: Int) -> Duration

type function on Duration

Construct a Duration from whole milliseconds.

assert Duration.as_millis(Duration.milliseconds(1500)) == 1500
fn seconds(n: Int) -> Duration

type function on Duration

Construct a Duration from whole seconds.

assert Duration.as_seconds(Duration.seconds(5)) == 5
assert Duration.seconds(5) == Duration.milliseconds(5000)
fn minutes(n: Int) -> Duration

type function on Duration

Construct a Duration from whole minutes.

assert Duration.as_seconds(Duration.minutes(3)) == 180
fn hours(n: Int) -> Duration

type function on Duration

Construct a Duration from whole hours.

assert Duration.to_string(Duration.hours(1)) == "1h"
fn abs(Duration(ns)) -> NonNegativeDuration

type function on Duration

The Duration’s length with its sign dropped, a NonNegativeDuration.

assert Duration.abs(Duration.seconds(-90)) == Duration.seconds(90)
assert Duration.abs(Duration.seconds(5)) == Duration.seconds(5)
fn as_nanos(Duration(ns)) -> Int

type function on Duration

The Duration in nanoseconds, exactly. A negative Duration gives a negative count, here and in the other as_* functions.

assert Duration.as_nanos(Duration.microseconds(2)) == 2000
assert Duration.as_nanos(Duration.seconds(-1)) == -1_000_000_000
fn as_micros(Duration(ns)) -> Int

type function on Duration

Total whole microseconds, truncating any sub-microsecond remainder.

assert Duration.as_micros(Duration.milliseconds(2)) == 2000
fn as_millis(Duration(ns)) -> Int

type function on Duration

Total whole milliseconds, truncating any sub-millisecond remainder.

assert Duration.as_millis(Duration.seconds(2)) == 2000
fn as_seconds(Duration(ns)) -> Int

type function on Duration

Total whole seconds, truncating any sub-second remainder toward zero.

assert Duration.as_seconds(Duration.minutes(3)) == 180
assert Duration.as_seconds(Duration.milliseconds(-1500)) == -1
fn as_minutes(Duration(ns)) -> Int

type function on Duration

Total whole minutes, truncating any sub-minute remainder.

assert Duration.as_minutes(Duration.hours(2)) == 120
fn as_hours(Duration(ns)) -> Int

type function on Duration

Total whole hours, truncating any sub-hour remainder.

assert Duration.as_hours(Duration.minutes(150)) == 2
fn format(d: Duration, locale: Locale, width: DurationWidth = DurationWidth.Long) -> String

type function on Duration

The length as a reader of locale says it: each unit it has, from hours down to nanoseconds, in the plural form the count takes, joined by the locale’s unit list pattern, as the locale joins the parts of one measure. width picks the units’ long, short or narrow words (DurationWidth). Zero is zero seconds. A negative length has the locale’s minus sign before its first number. A day is a civil unit of no fixed length, so the largest unit is the hour: 50 hours reads “50 hours”.

assert Duration.format(Duration.minutes(90), Locale"en") == "1 hour, 30 minutes"
assert Duration.format(Duration.hours(50), Locale"en") == "50 hours"
assert Duration.format(Duration.minutes(90), Locale"pl") == "1 godzina i 30 minut"
assert Duration.format(Duration.minutes(90), Locale"de") == "1 Stunde, 30 Minuten"
assert Duration.format(Duration.seconds(0), Locale"en") == "0 seconds"
assert Duration.format(Duration.milliseconds(1500), Locale"en", width: .Short) == "1 sec, 500 ms"
assert Duration.format(Duration.minutes(-5), Locale"en", width: .Narrow) == "-5m"
fn clock(d: Duration, fraction_digits: Int = 0) -> String

type function on Duration

The length as a stopwatch shows it, HH:MM:SS: the hours in at least two digits and as many more as they need, then the minutes and the seconds in two digits each. A negative length has a leading -. The seconds are whole unless fraction_digits asks for that many digits of the second after a .. A count above 9 (nanoseconds) writes 9 digits and one below 0 writes none. What the digits do not show is cut off, not rounded. Duration.parse_clock reads it back.

assert Duration.clock(Duration.seconds(88)) == "00:01:28"
assert Duration.clock(Duration.hours(100) + Duration.minutes(5)) == "100:05:00"
assert Duration.clock(Duration.seconds(-5)) == "-00:00:05"
assert Duration.clock(Duration.milliseconds(1_999)) == "00:00:01"
assert Duration.clock(Duration.milliseconds(1_250), fraction_digits: 3) == "00:00:01.250"
fn parse_clock(text: String) -> Result<Duration, NumberParseError>

type function on Duration

Reads a length written as Duration.clock writes it: an optional -, the hours in one digit or more, then :, the minutes, : and the seconds in two digits each, both below 60, and an optional . and one to nine digits of the second. The error says where the text stops being that, at a position counted in grapheme clusters.

assert Duration.parse_clock("00:01:28") == Ok(Duration.seconds(88))
assert Duration.parse_clock("-1:00:00.5") == Ok(Duration.milliseconds(-3_600_500))
assert Duration.parse_clock("00:61:00") == Err(NumberParseError.Unexpected{at: 3, text: "61"})
assert Duration.parse_clock("1:02") == Err(NumberParseError.Unexpected{at: 4, text: ""})
assert Duration.parse_clock("") == Err(NumberParseError.Empty)

d = Duration.seconds(5_000) + Duration.milliseconds(25)
assert Duration.parse_clock(Duration.clock(d, fraction_digits: 3)) == Ok(d)
fn parse(text: String) -> Result<Duration, NumberParseError>

type function on Duration

Reads a length written as Display writes it: an optional -, then counts, each followed by its unit, largest unit first and each at most once: h, m, s, ms, µs and ns (1h30m, 1s500ms, -5m, 0s). A count below the hours stays below the next unit up, so 90 minutes is 1h30m, not 90m; the hours have no bound. The error says where the text stops being that, at a position counted in grapheme clusters. A Duration"1m28s" literal reads its text the same way.

assert Duration.parse("1m28s") == Ok(Duration.seconds(88))
assert Duration.parse("-1h30m15s250ms") == Ok(Duration.milliseconds(-5_415_250))
assert Duration.parse("0s") == Ok(Duration.seconds(0))
assert Duration.parse("90m") == Err(NumberParseError.Unexpected{at: 0, text: "90"})
assert Duration.parse("5s1m") == Err(NumberParseError.Unexpected{at: 3, text: "m"})
assert Duration.parse("5") == Err(NumberParseError.Unexpected{at: 1, text: ""})
assert Duration.parse("") == Err(NumberParseError.Empty)

long = Duration.hours(-10_000_000_000) - Duration.nanoseconds(1)
assert Duration.parse(Duration.to_string(long)) == Ok(long)

impl Literal for Duration

fn from_fragments(fragments: List<Fragment<String>>) -> Result<Duration, NumberParseError>

impl Literal.from_fragments

Duration"1m28s" is Duration.seconds(88): the text as Display writes it, which Duration.parse reads. A literal without slots is checked when the program is checked, so a malformed one is a compile error at the literal.

assert Duration"1m28s" == Duration.seconds(88)
assert Duration"1h30m15s250ms" == Duration.milliseconds(5_415_250)
assert Duration"-5m" == Duration.minutes(-5)
assert Duration"500ms" == Duration.milliseconds(500)
assert Duration"0s" == Duration.seconds(0)
assert Duration"2h" == Duration.hours(2)

impl Add<Duration, Duration> for Duration

fn add(Duration(a), Duration(b)) -> Duration

impl Add.add

Sum of two Durations.

assert Duration.add(Duration.seconds(1), Duration.milliseconds(500)) == Duration.milliseconds(1500)
assert Duration.seconds(1) + Duration.milliseconds(500) == Duration.milliseconds(1500)

impl Summable for Duration

fn empty_sum() -> Duration

impl Summable.empty_sum

The sum of no Durations: zero length.

assert Duration.empty_sum() == Duration.seconds(0)
assert Duration.seconds(3) + Duration.empty_sum() == Duration.seconds(3)

impl Subtract<Duration, Duration> for Duration

fn subtract(Duration(a), Duration(b)) -> Duration

impl Subtract.subtract

Difference of two Durations (the first minus the second); may be negative.

assert Duration.subtract(Duration.seconds(1), Duration.seconds(3)) == Duration.seconds(-2)
assert Duration.seconds(1) - Duration.seconds(3) == Duration.seconds(-2)

impl Multiply<Int, Duration> for Duration

fn multiply(Duration(ns), rhs: Int) -> Duration

impl Multiply.multiply

Multiply a Duration by an integer factor.

assert Duration.multiply(Duration.seconds(2), 3) == Duration.seconds(6)
assert Duration.seconds(2) * 3 == Duration.seconds(6)

impl Divide<NonZeroInt, Duration> for Duration

fn divide(Duration(ns), rhs: NonZeroInt) -> Duration

impl Divide.divide

Divide a Duration by a NonZeroInt, truncating toward zero. A literal divisor is checked when the program is compiled; NonZeroInt.try_from(n) checks one computed at run time.

assert Duration.seconds(6) / 3 == Duration.seconds(2)
assert Duration.nanoseconds(-7) / 2 == Duration.nanoseconds(-3)

impl Remainder<NonZeroDuration, Duration> for Duration

fn remainder(Duration(ns), rhs: NonZeroDuration) -> Duration

impl Remainder.remainder

What is left of lhs after as many whole rhs as fit, with lhs’s sign: elapsed % Duration.minutes(15) is how far into the current quarter hour elapsed is. The divisor is a NonZeroDuration.

assert Duration.minutes(40) % Duration.minutes(15) == Duration.minutes(10)
assert Duration.seconds(-7) % Duration.seconds(3) == Duration.seconds(-1)

impl Display for Duration

fn to_string(Duration(ns)) -> String

impl Display.to_string

The length as counts of units, largest first, leaving out a unit whose count is zero: 1h30m, 250ms. Zero is 0s, and a negative length starts with -. Duration.parse reads it back.

assert Duration.to_string(Duration.seconds(5)) == "5s"
assert Duration.to_string(Duration.milliseconds(1500)) == "1s500ms"
assert Duration.to_string(Duration.minutes(90)) == "1h30m"
assert Duration.to_string(Duration.nanoseconds(0)) == "0s"

assert Duration.to_string(Duration.hours(-10_000_000_000) - Duration.nanoseconds(1))
    == "-10000000000h1ns"

impl Localize for Duration

fn localize(d: Duration, locale: Locale) -> String

impl Localize.localize

The length as Duration.format writes it, in long words.

assert Duration.localize(Duration.minutes(90), Locale"en") == "1 hour, 30 minutes"

impl Debug for Duration

fn inspect(d: Duration) -> String

impl Debug.inspect

assert Duration.inspect(Duration.seconds(5)) == "5s"

impl Equatable for Duration

fn equal(a: Duration, b: Duration) -> Bool

impl Equatable.equal

impl Hashable for Duration

fn hash(value: Duration) -> Int

impl Hashable.hash

impl Comparable for Duration

fn compare(a: Duration, b: Duration) -> Ordering

impl Comparable.compare

enum DurationWidth
    Long
    Short
    Narrow
end

How long the words Duration.format writes for each unit are, CLDR’s unit widths: Long (1 hour, 30 minutes), Short (1 hr, 30 min) or Narrow (1h 30m). A list’s ListWidth is a different set, CLDR’s list widths.

impl Debug for DurationWidth

fn inspect(value: DurationWidth) -> String

impl Debug.inspect

impl Equatable for DurationWidth

fn equal(a: DurationWidth, b: DurationWidth) -> Bool

impl Equatable.equal

subtype NonZeroDuration Duration when fn d -> Duration.as_nanos(d) != 0

A Duration that is not zero long. A typed literal is checked when the program is compiled; NonZeroDuration.try_from(d) checks a Duration computed at run time.

subtype: NonZeroDuration is a subtype of Duration. A literal where a NonZeroDuration is expected is checked when the program is compiled; NonZeroDuration.try_from(...) checks a value when it runs.

step: NonZeroDuration = Duration"-1s"
assert step == Duration.seconds(-1)
assert NonZeroDuration.try_from(Duration.seconds(0)) == None
fn try_from(value: Duration) -> Maybe<NonZeroDuration>

type function on NonZeroDuration

Some of the value when it satisfies NonZeroDuration’s rules, None when it does not.

subtype NonNegativeDuration Duration when fn d -> Duration.as_nanos(d) >= 0

A Duration of zero or more: how long something took, or how long to wait. Duration.abs returns one. A typed literal is checked when the program is compiled; NonNegativeDuration.try_from(d) checks a Duration computed at run time.

subtype: NonNegativeDuration is a subtype of Duration. A literal where a NonNegativeDuration is expected is checked when the program is compiled; NonNegativeDuration.try_from(...) checks a value when it runs.

wait: NonNegativeDuration = Duration"0s"
assert wait == Duration.seconds(0)
assert NonNegativeDuration.try_from(Duration.seconds(-1)) == None
fn try_from(value: Duration) -> Maybe<NonNegativeDuration>

type function on NonNegativeDuration

Some of the value when it satisfies NonNegativeDuration’s rules, None when it does not.

subtype PositiveDuration NonNegativeDuration and NonZeroDuration when fn d -> Duration.as_nanos(d) > 0

A Duration longer than zero: a schedule’s interval, which jobs.Schedule.every takes. It refines both NonNegativeDuration and NonZeroDuration, so a PositiveDuration passes wherever either, or a Duration, is expected. A typed literal is checked when the program is compiled; PositiveDuration.try_from(d) checks a Duration computed at run time.

subtype: PositiveDuration is a subtype of NonNegativeDuration and NonZeroDuration, and through them Duration. A literal where a PositiveDuration is expected is checked when the program is compiled; PositiveDuration.try_from(...) checks a value when it runs.

every: PositiveDuration = Duration"15m"
assert every == Duration.minutes(15)
wait: NonNegativeDuration = every
assert wait == every
assert PositiveDuration.try_from(Duration.seconds(0)) == None
assert PositiveDuration.try_from(Duration.seconds(-1)) == None
fn try_from(value: Duration) -> Maybe<PositiveDuration>

type function on PositiveDuration

Some of the value when it satisfies PositiveDuration’s rules, None when it does not.