Time

Module time

import time

Three types that refuse to be mixed up.

time defines the three values a clock deals in and the arithmetic over them. Duration is a span, Instant a monotonic reading, and Timestamp a point on the wall clock.

They are separate types on purpose. Subtracting two Instants gives a Duration; adding a Duration to either moves it. Subtracting two Timestamps is between. What you cannot do is measure elapsed time with wall-clock readings, because a wall clock jumps and the types will not let you pretend otherwise.

Duration is a primitive rather than a wrapper, so spans add, subtract and scale with the usual operators and print as 1.5s rather than as a bare number.

Contents

• Types — Duration, Instant, Timestamp
• Functions — absolute, asHours, asMilliseconds, asMinutes, asNanoseconds, asSeconds, between, day, format, formatDuration, fromEpoch, hour, hours, microseconds, milliseconds, minute, minutes, month, nanoseconds, origin, parse, parseDuration, second, seconds, since, toEpoch, year, zero

---

Types

Duration

`time/time.zirr:5`

extern type Duration

A span of time, in nanoseconds.
A primitive rather than a wrapper, so that spans add, subtract and scale with the usual operators, and print as 1.5s rather than as a bare number.

---

Instant

`time/time.zirr:9`

extern type Instant

A reading from a monotonic clock. Its origin is arbitrary, so it is only meaningful next to another Instant.
Subtracting two gives a Duration; adding a Duration moves it. Nothing else is allowed, which is what keeps elapsed time honest.

---

Timestamp

`time/time.zirr:13`

extern type Timestamp

A point on the wall clock, as nanoseconds since the Unix epoch.
Distinct from Instant because wall clocks jump, so a Timestamp must never be used to measure how long something took.

---

Functions

absolute

`time/durations.zirr:42`

extern fn absolute(d: Duration) -> Duration

d without its sign.

---

asHours

`time/durations.zirr:39`

extern fn asHours(d: Duration) -> Float

The number of hours in d, including any fraction.

---

asMilliseconds

`time/durations.zirr:30`

extern fn asMilliseconds(d: Duration) -> Int

The whole number of milliseconds in d, discarding any remainder.

---

asMinutes

`time/durations.zirr:36`

extern fn asMinutes(d: Duration) -> Float

The number of minutes in d, including any fraction.

---

asNanoseconds

`time/durations.zirr:27`

extern fn asNanoseconds(d: Duration) -> Int

The whole number of nanoseconds in d.

---

asSeconds

`time/durations.zirr:33`

extern fn asSeconds(d: Duration) -> Float

The number of seconds in d, including any fraction.

---

between

`time/instants.zirr:10`

extern fn between(earlier: Timestamp, later: Timestamp) -> Duration

The span between two points on the wall clock.

---

day

`time/instants.zirr:27`

extern fn day(t: Timestamp) -> Int

---

format

`time/instants.zirr:19`

extern fn format(t: Timestamp) -> String

t rendered in RFC 3339 form, in UTC, such as “2024-03-05T14:30:00Z”.

---

formatDuration

`time/durations.zirr:46`

extern fn formatDuration(d: Duration) -> String

A human reading of d, such as “1.5s” or “250ms”.
The result always reads back through parseDuration as the same span.

---

fromEpoch

`time/instants.zirr:13`

extern fn fromEpoch(nanoseconds: Int) -> Timestamp

A Timestamp the given number of nanoseconds after the Unix epoch.

---

hour

`time/instants.zirr:28`

extern fn hour(t: Timestamp) -> Int

---

hours

`time/durations.zirr:21`

extern fn hours(count: Int) -> Duration

A span of the given number of hours.

---

microseconds

`time/durations.zirr:9`

extern fn microseconds(count: Int) -> Duration

A span of the given number of microseconds.

---

milliseconds

`time/durations.zirr:12`

extern fn milliseconds(count: Int) -> Duration

A span of the given number of milliseconds.

---

minute

`time/instants.zirr:29`

extern fn minute(t: Timestamp) -> Int

---

minutes

`time/durations.zirr:18`

extern fn minutes(count: Int) -> Duration

A span of the given number of minutes.

---

month

`time/instants.zirr:26`

extern fn month(t: Timestamp) -> Int

---

nanoseconds

`time/durations.zirr:6`

extern fn nanoseconds(count: Int) -> Duration

A span of the given number of nanoseconds.

---

origin

`time/instants.zirr:4`

extern fn origin() -> Instant

The zero point of the monotonic scale. Its position carries no meaning; it exists so that instants can be constructed, which is mostly useful for test clocks.

---

parse

`time/instants.zirr:22`

extern fn parse(text: String) -> Result

Reads an RFC 3339 timestamp, failing with Err when the text is not one.

---

parseDuration

`time/durations.zirr:50`

extern fn parseDuration(text: String) -> Result

Reads a span such as “1.5s”, “250ms”, “2h45m” or “-1.5h”, failing with Err when the text is not one.
Accepts the units ns, us, µs, ms, s, m and h.

---

second

`time/instants.zirr:30`

extern fn second(t: Timestamp) -> Int

---

seconds

`time/durations.zirr:15`

extern fn seconds(count: Int) -> Duration

A span of the given number of seconds.

---

since

`time/instants.zirr:7`

extern fn since(earlier: Instant, later: Instant) -> Duration

The span from earlier to later, which is negative when they are the other way round.

---

toEpoch

`time/instants.zirr:16`

extern fn toEpoch(t: Timestamp) -> Int

The number of nanoseconds from the Unix epoch to t.

---

year

`time/instants.zirr:25`

extern fn year(t: Timestamp) -> Int

The calendar parts of t, in UTC.

---

zero

`time/durations.zirr:24`

extern fn zero() -> Duration

A span of no time at all.