pub const DURATION: BuiltinSchema;Expand description
Duration: a signed count of nanoseconds.
§One function per literal suffix, in both directions
500ms is a literal and was, until these existed, the only way to have a
Duration at all: a program that read 250 out of a manifest, an
argument, or the environment had no expression that turned it into the
Duration clock.sleep takes (issue #146). The six associated functions
are that expression, and there is exactly one per suffix the lexer
accepts — ns, us, ms, s, m, h — so that
Duration.seconds(1) and 1s are the same value and the reader has one
table to learn rather than two. Nothing about a literal changes: 1s is
still 1,000,000,000 nanoseconds, written the way it always was.
The six methods are the same table read backwards, which is what lets a
duration be reported as well as built: d.millis() is the whole number
of milliseconds in d. That direction is not free of a choice, so it is
written down — see the entries.
A unit is a function name rather than an argument because a builtin
parameter is a name and a type and nothing else: a Duration.of(count, unit) would need a unit type to pass, which would be a seventh builtin
enum existing only to be an argument. This is Int.parse/Int.parseRadix
answering the same pressure the same way.
Scalar multiplication — Duration * Int — was the other shape and is not
this one. It is a smaller change and it can only build: there is no
expression made of * that reads a count back out, and issue #146 asks
for both directions because a timeout that can be configured is a timeout
that gets reported.
§What a builder does with a count it cannot hold
A negative count is a negative duration and nothing else. A
Duration is signed nanoseconds, -1h is already a value a program can
write, and Duration.hours(-1) is that value. A builder that refused one
would be narrower than the literal it mirrors.
A count whose nanoseconds do not fit in an Int stops the run, in the
words Duration arithmetic already stops it in. The Language Card calls
integer overflow a broken invariant rather than a wrapped result, and
1h + 1h past the end already trapped; a builder that answered a
Result instead would make the same overflow two different kinds of
event depending on how the duration was reached.