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.
Exports
Section titled “Exports”type Duration
Section titled “type 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)
Duration.nanoseconds
Section titled “Duration.nanoseconds”fn nanoseconds(n: Int) -> Duration
type function on Duration
Construct a Duration from whole nanoseconds.
assert Duration.as_nanos(Duration.nanoseconds(42)) == 42
Duration.microseconds
Section titled “Duration.microseconds”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
Duration.milliseconds
Section titled “Duration.milliseconds”fn milliseconds(n: Int) -> Duration
type function on Duration
Construct a Duration from whole milliseconds.
assert Duration.as_millis(Duration.milliseconds(1500)) == 1500
Duration.seconds
Section titled “Duration.seconds”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)
Duration.minutes
Section titled “Duration.minutes”fn minutes(n: Int) -> Duration
type function on Duration
Construct a Duration from whole minutes.
assert Duration.as_seconds(Duration.minutes(3)) == 180
Duration.hours
Section titled “Duration.hours”fn hours(n: Int) -> Duration
type function on Duration
Construct a Duration from whole hours.
assert Duration.to_string(Duration.hours(1)) == "1h"
Duration.abs
Section titled “Duration.abs”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)
Duration.as_nanos
Section titled “Duration.as_nanos”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
Duration.as_micros
Section titled “Duration.as_micros”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
Duration.as_millis
Section titled “Duration.as_millis”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
Duration.as_seconds
Section titled “Duration.as_seconds”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
Duration.as_minutes
Section titled “Duration.as_minutes”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
Duration.as_hours
Section titled “Duration.as_hours”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
Duration.format
Section titled “Duration.format”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"
Duration.clock
Section titled “Duration.clock”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"
Duration.parse_clock
Section titled “Duration.parse_clock”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)
Duration.parse
Section titled “Duration.parse”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)
Duration.from_fragments
Section titled “Duration.from_fragments”impl Literal for Duration
fn from_fragments(fragments: List<Fragment<String>>) -> Result<Duration, NumberParseError>
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)
Duration.add
Section titled “Duration.add”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)
Duration.empty_sum
Section titled “Duration.empty_sum”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)
Duration.subtract
Section titled “Duration.subtract”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)
Duration.multiply
Section titled “Duration.multiply”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)
Duration.divide
Section titled “Duration.divide”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)
Duration.remainder
Section titled “Duration.remainder”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)
Duration.to_string
Section titled “Duration.to_string”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"
Duration.localize
Section titled “Duration.localize”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"
Duration.inspect
Section titled “Duration.inspect”impl Debug for Duration
fn inspect(d: Duration) -> String
impl Debug.inspect
assert Duration.inspect(Duration.seconds(5)) == "5s"
Duration.equal
Section titled “Duration.equal”impl Equatable for Duration
fn equal(a: Duration, b: Duration) -> Bool
impl Equatable.equal
Duration.hash
Section titled “Duration.hash”impl Hashable for Duration
fn hash(value: Duration) -> Int
impl Hashable.hash
Duration.compare
Section titled “Duration.compare”impl Comparable for Duration
fn compare(a: Duration, b: Duration) -> Ordering
impl Comparable.compare
enum DurationWidth
Section titled “enum DurationWidth”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.
DurationWidth.inspect
Section titled “DurationWidth.inspect”impl Debug for DurationWidth
fn inspect(value: DurationWidth) -> String
impl Debug.inspect
DurationWidth.equal
Section titled “DurationWidth.equal”impl Equatable for DurationWidth
fn equal(a: DurationWidth, b: DurationWidth) -> Bool
impl Equatable.equal
type NonZeroDuration
Section titled “type NonZeroDuration”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
NonZeroDuration.try_from
Section titled “NonZeroDuration.try_from”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.
type NonNegativeDuration
Section titled “type NonNegativeDuration”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
NonNegativeDuration.try_from
Section titled “NonNegativeDuration.try_from”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.
type PositiveDuration
Section titled “type PositiveDuration”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
PositiveDuration.try_from
Section titled “PositiveDuration.try_from”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.