Time¶
stdlib/time.kod has two clocks, a Duration type, sleep, and a Time type
for timestamps.
import "time"
import "time" { Duration }
let started = time.monotonic_ns()
time.sleep(Duration(ms: 250))
let took = Duration(ns: time.monotonic_ns() - started)
print(took.to_str()) // 250.31ms
Clocks¶
| Function | Returns |
|---|---|
monotonic_ns() |
nanoseconds from an unspecified origin that never go backwards; only differences mean anything. Use it to time things. |
unix_ns() |
nanoseconds since 1970-01-01 UTC by the wall clock. It can jump if the system clock is adjusted, so it is not for measuring elapsed time. |
monotonic_res_ns() |
the smallest step monotonic_ns() can take, in nanoseconds; at least 1. |
Both are plain int64, which holds about 292 years of nanoseconds.
Duration¶
A Duration is a length of time, kept as nanoseconds in an int64 (ns).
Make one by naming the units you want; they add up, and each defaults to 0:
The units are hours, minutes, seconds, ms, us and ns, and labels go in
that order, largest first, as in Duration(seconds: 1, ms: 500). Duration is
a struct with a custom constructor, so
Duration(...) is the only way to build one from units, and the units are
labels, not types: Duration(seconds: 90) and Duration(minutes: 1, seconds: 30)
are equal.
Arithmetic and comparison¶
Duration defines the operators:
let a = Duration(seconds: 2)
let b = Duration(ms: 500)
a + b // 2.5s
a - b // 1.5s
a * 3 // 6s
3 * a // 6s
a / 4 // 500ms
-a // -2s
a > b // true
a == Duration(ms: 2000) // true
A duration times or divided by an int64 is a duration, and Duration has
no Duration * Duration or Duration / Duration: use a.ns / b.ns for a
ratio.
Methods¶
| Method | Meaning |
|---|---|
as_ms() |
the whole milliseconds in it, truncated toward zero |
as_seconds() |
the whole seconds in it, truncated toward zero |
as_hours() |
the whole hours in it, truncated toward zero |
as_days() |
the whole 24-hour days in it, truncated toward zero |
ceil_ms() |
milliseconds, rounded up for a positive duration, so that a short timeout never becomes 0 (which most timeouts treat as none) |
to_str() |
a short reading, such as 1h2m3s, 1.5s, 250ms, 12.5us, 40ns or 0s |
to_str writes hours and minutes only when the duration has them (a duration of
an hour or more always shows minutes and seconds, as in 1h0m0s), seconds with
a fraction when it has one, and below a second the largest unit that keeps the
number at 1 or more. A negative duration starts with -.
Sleeping¶
waits at least d, to the resolution of the system clock, and a signal doesn't
cut it short. A zero or negative duration returns at once.
Timestamps¶
A Time is a moment: whole seconds since 1970-01-01 UTC, negative before it,
and nanos from 0 to 999999999 on top. It has no time zone of its own, and
reads as UTC.
import "time"
let created = time.parse("2026-01-02T03:04:05+01:00")? or time.now()
print(created.to_str()) // 2026-01-02T02:04:05Z
print(created.utc().year) // 2026
print((time.now() - created).as_days()) // how many days ago
| Function | Returns |
|---|---|
now() |
the wall clock's time |
parse(s) |
the Time of an RFC 3339 timestamp, or none if s isn't one |
parse_date(s) |
midnight UTC of a YYYY-MM-DD date, or none if s isn't one |
parse takes what APIs send: 2026-01-02T03:04:05Z, with a fraction of a second
as in 05.25Z, and an offset as in 05+01:00. A t and a z may be lowercase,
as RFC 3339 allows. Digits past nanoseconds are dropped. It checks the calendar, so
2026-02-29 is none. A leap second, :60, is read as the first second after it,
since a Time has no way to hold one.
| Method | Meaning |
|---|---|
t + d |
the Time a Duration later |
a - b |
the Duration from b to a, which wraps past about 292 years, as a Duration does |
a == b, a < b and the like |
whether they're the same moment, or which comes first |
utc() |
a Utc with year, month (1 to 12), day, hour, minute and second |
to_str() |
RFC 3339 in UTC, with a fraction only if there is one, as in 2026-01-02T02:04:05.25Z |
Durations in other modules¶
The timeouts and deadlines of net/tcp, net/tls and the
HTTP client are Durations: Client(deadline: Duration(seconds: 15)).