std/time

std/time is a UTC-unified time library. All timestamps are milliseconds since the Unix epoch. Because Pluvial’s int is 49 bits wide, this range comfortably covers tens of thousands of years, and a single unit lets you write intuitive comparisons like elapsed(start) >= ms.

Importing

from std.time import now, monotonic, sleep, format_time, parse_time,
                     timestamp_to_parts, elapsed,
                     second, minute, hour, day

Functions

Function	Returns	Meaning
now()	int	current wall-clock time, ms since the Unix epoch
monotonic()	int	a monotonic clock reading in ms (independent of the wall clock; for timers)
sleep(ms)	(no value)	sleep for ms milliseconds
format_time(ms, fmt)	string	format a timestamp using a strftime-style format
parse_time(s, fmt)	Result<int>	parse a string into a timestamp (ms)
timestamp_to_parts(ms)	(int, int, int, int, int, int)	a tuple (year, month, day, hour, min, sec)
elapsed(start)	int	ms elapsed since start

Constants

Durations in milliseconds, exported as zero-argument functions:

Function	Value
second()	1000
minute()	60000
hour()	3600000
day()	86400000

Examples

int start = monotonic()
sleep(10)
println(elapsed(start) >= 10)            // true

println(format_time(0, "%Y-%m-%d"))      // "1970-01-01"

auto (y, mo, d, h, mi, se) = timestamp_to_parts(0)
println(y)                               // 1970

timestamp_to_parts returns a tuple, so you can destructure it directly — one of the first practical uses of tuples crossing a module boundary.

UTC and formatting

• Everything is UTC. format_time(0, "%Y-%m-%d") is "1970-01-01" in every timezone — the library does not depend on local time, so the Unix epoch does not drift.
• Formatting uses strftime-style specifiers such as %Y-%m-%d %H:%M:%S.
• Parsing supports %Y, %m, %d, %H, %M, %S plus literal byte matching, via a hand-rolled parser (chosen over POSIX strptime for portability). parse_time returns a Result<int> so a malformed input is an err.

The wall clock and monotonic clock are distinct: use now() for calendar time and monotonic() for measuring durations.

Building

std/time uses only the standard C library — no external dependencies. Windows is fully supported via platform shims.