Duration

Standard library struct · Written Duration(hours: 1, minutes: 30)

A Duration is an exact length of time, to the nanosecond: a timeout, a lap time, how long until lunch. It can be negative. A day in a Duration is exactly 24 hours, unlike a day on the calendar, which is 23 or 25 hours long when clocks change.

const talk = Duration(minutes: 45)
const questions = Duration(minutes: 15)
const total = talk + questions
print(total)
print(total.total_minutes)

Output

1h
60.0

A Duration is a value: equal when the lengths are, ordered from shorter to longer, and usable as a dictionary key. It prints as the units that aren’t zero, largest first: 2d 3h, 1h 30m, 45s. A fraction of a second is shown as decimal seconds, such as 1.25s, zero is 0s, and a negative length starts with -.

At a glance

Making one
Duration(days:, hours:, ...)	A length from any units

Arithmetic
+, -	Add or subtract two lengths
*, / by a whole number	A multiple or a part of a length
/ by a length	How many times one fits in another
abs(), zero?(), negative?()	The size without its sign, and tests

Reading
total_days, total_hours, total_minutes, total_seconds, total_milliseconds	The whole length in one unit, with a fraction
whole_days, whole_hours, whole_minutes, whole_seconds, whole_milliseconds, whole_microseconds, whole_nanoseconds	The whole length in one unit, rounded toward zero

Making one

Duration(days: Int = 0, hours: Int = 0, minutes: Int = 0, seconds: Int = 0, milliseconds: Int = 0, microseconds: Int = 0, nanoseconds: Int = 0): Duration

Any combination of units, added together. Every amount must be named, because Duration(5) would silently mean five days; Emerald refuses it and lists the units. Duration() is zero.

print(Duration(hours: 1, minutes: 30))
print(Duration(days: 2, hours: 3))
print(Duration(seconds: 1, milliseconds: 250))
print(Duration())
print(Duration(minutes: -5))

Output

1h 30m
2d 3h
1.25s
0s
-5m

Program.sleep and the date and time types all take a Duration, so the unit is never in doubt.

Arithmetic

duration + other: Duration

The sum of two lengths; duration - other is the difference. += and -= work too.

var left = Duration(minutes: 10)
left += Duration(minutes: 5)
left -= Duration(minutes: 1)
print(left)

Output

14m

duration * factor: Duration

A length multiplied by a whole number, or divided by one with duration / divisor. Division rounds toward zero, to the nanosecond.

const lap = Duration(minutes: 14)
print(lap * 3)
print(lap / 2)
print(Duration(seconds: 1) / 3)

Output

42m
7m
0.333333333s

Raises a DateTimeError for a divisor of zero.

duration / other: Float

Dividing one length by another gives how many times the second fits into the first, as a Float.

print(Duration(hours: 1, minutes: 30) / Duration(minutes: 45))

Output

2.0

Raises a DateTimeError when other is zero.

abs(): Duration

The length without its sign. Two tests go with it: zero?() asks whether the length is zero, and negative?() whether it is below zero.

print(Duration(minutes: -3).abs())
print(Duration().zero?())
print(Duration(seconds: -1).negative?())

Output

3m
true
true

Reading

total_hours: Float

The whole length in one unit, as a Float with a fraction. The units are total_days, total_hours, total_minutes, total_seconds, and total_milliseconds. None needs parentheses.

const length = Duration(minutes: 90)
print(length.total_hours)
print(length.total_minutes)

Output

1.5
90.0

whole_hours: Int

The whole length in one unit, rounded toward zero, as an Int. The units are whole_days, whole_hours, whole_minutes, whole_seconds, whole_milliseconds, whole_microseconds, and whole_nanoseconds.

const length = Duration(minutes: 90)
print(length.whole_hours)
print(length.whole_minutes)

Output

1
90

Use a whole_ unit to count, and a total_ unit when the fraction matters.