Time API

Real-time clocks, system datetime queries, parsing and conversion helpers, and timezone information.

Overview

Time is a global singleton registered at VM startup; all methods are invoked as Time.method(...). It is a map-shaped singleton whose methods are closures bound at VM startup. It covers four jobs: reading clocks, querying the current system datetime, converting between unix timestamps, ISO 8601 strings, and datetime maps, and reporting the local timezone.

Conventions

All numeric values are passed and returned as Zym numbers: unix timestamps, ticks, minute offsets, and millisecond counts. Timestamps are truncated to int64 internally.

utc, useSpace, and weekday are required booleans; passing a non-bool raises a runtime error. Bad argument types produce a Zym runtime error of the form Time.method(args) expects a <type>.

Datetime strings follow ISO 8601: YYYY-MM-DDTHH:MM:SS by default, or YYYY-MM-DD HH:MM:SS when useSpace is true.

Datetime Maps

Methods that return or accept a datetime map use the keys below. Date-only and time-only variants return only the relevant subset.

Real-Time Clocks

Returns the unix timestamp from the system clock, in seconds with sub-second precision.

Returns the process CPU time in seconds, measured via clock() / CLOCKS_PER_SEC.

Returns monotonic milliseconds since process start.

Returns monotonic microseconds since process start.

var started = Time.ticksMsec()

// ... do some work ...

print("elapsed: %n ms", Time.ticksMsec() - started)

System Datetime

These methods read the current system time. Each takes a required utc boolean: true returns UTC, false returns local time.

Returns the current datetime as a map with year, month, day, weekday, hour, minute, second, and dst.

Returns the current date as a map with year, month, day, weekday, and dst.

Returns the current time of day as a map with hour, minute, and second.

Returns the current datetime as an ISO 8601 string.

• useSpace (boolean) — true separates date and time with a space instead of T

Returns the current date as a YYYY-MM-DD string.

Returns the current time as an HH:MM:SS string.

print("%s", Time.datetimeString(false, true))   // "2026-08-08 14:05:09" (local)
print("%s", Time.dateString(true))              // "2026-08-08" (UTC)

var dt = Time.datetime(true)
print("year=%n month=%n day=%n", dt.year, dt.month, dt.day)

From a Unix Timestamp

These methods convert a unix timestamp into datetime maps and strings. ts is seconds since the Unix epoch (UTC).

Converts a unix timestamp to a datetime map.

Converts a unix timestamp to a date map.

Converts a unix timestamp to a time map.

Formats a unix timestamp as an ISO 8601 datetime string.

• useSpace (boolean) — true separates date and time with a space instead of T

Formats a unix timestamp as a YYYY-MM-DD string.

Formats a unix timestamp as an HH:MM:SS string.

var ts = Time.now()
print("%s", Time.datetimeStringFromUnix(ts, false))
print("%s", Time.dateStringFromUnix(ts))  // "2026-08-08"

Parsing & Conversion

Parses an ISO 8601 datetime string and returns the unix timestamp as a number.

• s (string) — ISO 8601 datetime string

Parses an ISO 8601 datetime string into a datetime map.

• s (string) — ISO 8601 datetime string
• weekday (boolean) — true includes the weekday field in the result

Converts a datetime map to a unix timestamp. The map may carry any subset of the datetime keys; missing fields default to 0, January, and day 1.

Formats a datetime map as an ISO 8601 string. As with unixFromDatetime, missing fields default to 0, January, and day 1.

• useSpace (boolean) — true separates date and time with a space instead of T

Timezone

Returns the local timezone as a map with bias (offset from UTC in minutes) and name.

Formats a minute offset as a signed ±HH:MM string.

• minutes (number) — offset from UTC in minutes

var tz = Time.timezone()
print("%s %s", tz.name, Time.offsetString(tz.bias))  // e.g. "CET +01:00"

Examples

Clocks and Current Time

var started = Time.ticksMsec()
print("now unix: %n", Time.now())
print("local:    %s", Time.datetimeString(false, true))
print("utc:      %s", Time.datetimeString(true, false))

var dt = Time.datetime(true)
print("year=%n month=%n day=%n", dt.year, dt.month, dt.day)

System.sleep(250)
print("elapsed: %n ms", Time.ticksMsec() - started)

Timestamp Round-Trip

// Parse an ISO 8601 string into a unix timestamp
var ts = Time.unixFromDatetimeString("2026-08-08T12:30:00")
print("unix: %n", ts)

// Back to strings
print("%s", Time.datetimeStringFromUnix(ts, true))  // space-separated form
print("%s", Time.timeStringFromUnix(ts))            // "HH:MM:SS"

// Into a map, weekday included
var dt = Time.datetimeFromDatetimeString("2026-08-08T12:30:00", true)
print("weekday: %n", dt.weekday)  // 6 (Saturday)

// A partial map fills in the rest
var s = Time.datetimeStringFromDatetime({"year": 2027}, false)
print("%s", s)  // "2027-01-01T00:00:00"