Standard Library
struct Duration
A length of time, stored as a whole number of milliseconds.
since 0.1.0-alpha.1linuxwindowswasm
Overview
Duration is a value type: copying it copies the number, and plus and minus return new values. Create one with a labeled constructor (Duration::ofSeconds(90), Duration::ofHours(2), and so on), combine them with plus and minus, and read them back with toMillis, toSeconds or toString. Durations can be negative.
Description
Duration is a value struct with one field, ms: a signed count of milliseconds. It is built with one
of five labeled constructors, named for the unit of their argument: Duration::ofMillis, ofSeconds,
ofMinutes, ofHours and ofDays. All of them convert to milliseconds on construction.
toMillis() returns the stored milliseconds. toSeconds() returns whole seconds, discarding the
remainder toward zero. plus and minus combine two durations into a new one.
toString() writes the duration in the largest units that apply: hours, minutes and seconds with the
minutes and seconds padded to two digits (1h02m03s), minutes and seconds (5m00s), seconds alone
(7s), or milliseconds (45ms) when the duration is under one second. A negative duration gets a
leading -. Sub-second detail is dropped once the duration reaches one second, so Duration::ofMillis(1500)
prints as 1s. Days are not a unit of the text form: two days print as 48h00m00s.
Building and printing durations
Duration d = Duration::ofHours(1).plus(Duration::ofMinutes(2));
console.writeln(d.toString());
console.writeln(d.toMillis());
console.writeln(Duration::ofDays(2).toString());
console.writeln(Duration::ofMinutes(5).toString());
console.writeln(Duration::ofSeconds(7).toString());
console.writeln(Duration::ofMillis(45).toString());
console.writeln(Duration::ofMillis(1500).toString());
console.writeln(Duration::ofSeconds(0 - 90).toString());
1h02m00s
3720000
48h00m00s
5m00s
7s
45ms
1s
-1m30s
Rules
Durationis a value:plusandminusreturn a new duration.toSeconds()truncates toward zero:Duration::ofMillis(2999).toSeconds()is2andDuration::ofMillis(0 - 2999).toSeconds()is-2.- A duration can be negative;
DateTime.minusreturns a negative duration when the argument is the later instant.
Examples
Subtracting and converting
Duration total = Duration::ofMinutes(3).minus(Duration::ofSeconds(30));
console.writeln(total.toString());
console.writeln(total.toMillis());
console.writeln(total.toSeconds());
console.writeln(Duration::ofMillis(2999).toSeconds());
console.writeln(Duration::ofMillis(0 - 2999).toSeconds());
2m30s
150000
150
2
-2
Examples
Building and combining durations
Duration d = Duration::ofHours(1).plus(Duration::ofMinutes(2));
console.writeln(d.toString());
console.writeln(d.toSeconds());
Duration shorter = d.minus(Duration::ofMinutes(60));
console.writeln(shorter.toString());
console.writeln(Duration::ofSeconds(5).minus(Duration::ofSeconds(8)).toString());
1h02m00s
3720
2m00s
-3s
Constructors
ofDays
Duration::ofDays(int d)Create a duration of a number of days, each exactly 24 hours long.
Parameters
- d
- The number of days.
Examples
Duration span = Duration::ofDays(2);
console.writeln(span.toMillis());
console.writeln(span.toString());
172800000
48h00m00s
ofHours
Duration::ofHours(int h)Create a duration of a number of hours.
Parameters
- h
- The number of hours.
Examples
Duration d = Duration::ofHours(2);
console.writeln(d.toSeconds());
console.writeln(d.toString());
7200
2h00m00s
ofMillis
Duration::ofMillis(int m)Create a duration of a number of milliseconds.
Parameters
- m
- The number of milliseconds.
Examples
Duration d = Duration::ofMillis(250);
console.writeln(d.ms);
console.writeln(d.toString());
250
250ms
ofMinutes
Duration::ofMinutes(int m)Create a duration of a number of minutes.
Parameters
- m
- The number of minutes.
Examples
Duration d = Duration::ofMinutes(5);
console.writeln(d.toSeconds());
console.writeln(d.toString());
300
5m00s
ofSeconds
Duration::ofSeconds(int s)Create a duration of a number of seconds.
Parameters
- s
- The number of seconds.
Examples
Duration d = Duration::ofSeconds(90);
console.writeln(d.toMillis());
console.writeln(d.toString());
90000
1m30s
Fields
ms
int msThe length of time in milliseconds. It is negative for a negative duration.
Methods
minus
Subtract another duration from this one.
The result is negative when o is longer than this duration.
Parameters
- o
- The duration to subtract.
Returns
A new duration equal to the difference; neither operand changes.
Examples
Duration a = Duration::ofMinutes(1);
Duration b = Duration::ofSeconds(30);
console.writeln(a.minus(b).toString());
console.writeln(b.minus(a).toString());
30s
-30s
See also: plus
plus
Add another duration to this one.
Parameters
- o
- The duration to add.
Returns
A new duration equal to the sum; neither operand changes.
Examples
Duration a = Duration::ofMinutes(1);
Duration b = Duration::ofSeconds(30);
console.writeln(a.plus(b).toString());
console.writeln(a.toString());
1m30s
1m00s
See also: minus
toMillis
toMillis() -> intGet the duration as a number of milliseconds.
Returns
The length in milliseconds; the same value as the ms field.
Examples
console.writeln(Duration::ofSeconds(3).toMillis());
console.writeln(Duration::ofMinutes(1).toMillis());
3000
60000
See also: toSeconds
toSeconds
toSeconds() -> intGet the duration as a whole number of seconds.
Any fraction of a second is discarded, rounding toward zero, so 1999 milliseconds is 1 second and -1999 milliseconds is -1 second.
Returns
The length in whole seconds.
Examples
console.writeln(Duration::ofMillis(1999).toSeconds());
console.writeln(Duration::ofMillis(0 - 1999).toSeconds());
console.writeln(Duration::ofHours(1).toSeconds());
1
-1
3600
See also: toMillis
toString
toString() -> stringFormat the duration as compact text.
Durations of an hour or more print as 1h02m03s, durations of a minute or more as 2m05s, and shorter ones as seconds, 7s. Leading zeros are dropped from the largest unit only. The text is truncated to whole seconds, so 1500 milliseconds prints as 1s; a duration under one second prints its milliseconds, as in 250ms. A negative duration starts with -.
Returns
The formatted text.
Examples
console.writeln(Duration::ofHours(1).plus(Duration::ofMinutes(2)).plus(Duration::ofSeconds(3)).toString());
console.writeln(Duration::ofSeconds(125).toString());
console.writeln(Duration::ofSeconds(7).toString());
console.writeln(Duration::ofMillis(1500).toString());
console.writeln(Duration::ofMillis(250).toString());
console.writeln(Duration::ofDays(1).toString());
console.writeln(Duration::ofSeconds(0 - 90).toString());
1h02m03s
2m05s
7s
1s
250ms
24h00m00s
-1m30s
See also: toSeconds