std.time

import std.time

time.now()            # Unix milliseconds
time.now_iso()        # "2026-07-30T09:12:44Z"
time.monotonic()      # for measuring elapsed time
time.format(ms, "%Y-%m-%d")
time.parse("2026-07-30T09:12:44Z")
time.parse_format("30/07/2026", "%d/%m/%Y")

Two clocks, and they are not interchangeable

now() is the wall clock - Unix milliseconds. Use it for timestamps: when something happened, what to store, what to show a person. It can jump backwards when the system clock is corrected or adjusted by NTP.

The two clocks use different units. now() returns milliseconds since the epoch; monotonic() returns seconds since an arbitrary start. Mixing them up is a factor-of-1000 error that looks plausible in a log, so check which one a duration came from before labelling it.

monotonic() never goes backwards. Use it for durations:

start = time.monotonic()
do_work()
elapsed = time.monotonic() - start        # seconds, as a float
elapsed_ms = elapsed * 1000

Measuring with now() can produce a negative duration, which is a bug that appears rarely and confusingly. Measure with monotonic, timestamp with now.

Formatting and parsing

format(ms, pattern) and parse_format(text, pattern) use strftime-style patterns. parse reads ISO 8601, and now_iso() produces it.

Prefer ISO 8601 for anything stored or transmitted: it sorts lexicographically, carries its timezone, and is unambiguous - unlike 30/07/2026, which means two different dates depending on the reader.

A pattern with an unknown specifier is an ordinary error, catchable with try - worth knowing when the pattern comes from a config file or a flag rather than from source.

Determinism

Wall-clock values in program output make it untestable. Where output is asserted - tests, examples, anything compared - either avoid a timestamp or inject it, so the comparison does not depend on when it ran.

std.log deliberately adds no automatic timestamp for the same reason. Add time.now() as a field when you want one.

Calendars

This module is timestamps, formatting and monotonic timing. For calendar arithmetic - adding months, weekday names, date components, durations - use the datetime package.