time
Dates, datetimes, durations, and instants, with wall-clock and monotonic time sources. Covers construction and decomposition, exact-time and calendar arithmetic, ISO 8601 / RFC 3339 / RFC 2822 / ICU-LDML parsing and formatting, timezone handling, RFC 5545 RRULE and cron recurrence rules, and mockable clocks for deterministic-time testing. Durations are signed nanosecond counts; date and datetime values come from the parse and construction functions.
time:now
[$time:now] -> datetime — Return the current wall-clock datetime from the host.
[?lib 'cx-stdlib/time']
[$time:now]
cx-err:CXER0271
time:today
[$time:today] -> date — Return the current wall-clock date from the host.
[?lib 'cx-stdlib/time']
[$time:today]
cx-err:CXER0271
time:instant-now
[$time:instant-now] -> instant — Return the current wall-clock instant (UTC-anchored timestamp).
[?lib 'cx-stdlib/time']
[$time:instant-now]
cx-err:CXER0271
time:monotonic-now
[$time:monotonic-now] -> int — Return a monotonic clock reading in nanoseconds, for measuring elapsed time.
[?lib 'cx-stdlib/time']
[?let [= $a [$time:monotonic-now]] [= $b [$time:monotonic-now]] [>= $b $a]]
cx-err:CXER0271
time:now-mock
[$time:now-mock] -> datetime — Pin the mock clock to a fixed datetime for deterministic-time testing.
[?lib 'cx-stdlib/time']
[$time:format-iso8601 [$time:now-mock [$time:datetime 2026 5 26 14 30 0]]]
'2026-05-26T14:30:00Z'
time:today-mock
[$time:today-mock] -> date — Pin the mock clock to a fixed date for deterministic-time testing.
[?lib 'cx-stdlib/time']
[$time:year [$time:today-mock [$time:date 2026 5 26]]]
2026
time:instant-now-mock
[$time:instant-now-mock] -> instant — Pin the mock clock to a fixed instant for deterministic-time testing.
[?lib 'cx-stdlib/time']
[$time:instant-now-mock 1000000000]
1000000000
time:mock-advance
[$time:mock-advance] -> null — Step the frozen mock clock forward by a duration.
[?lib 'cx-stdlib/time']
[$time:mock-advance [$time:duration-h 1]]
null
time:mock-set
[$time:mock-set] -> null — Re-pin the mock clock to an absolute instant.
[?lib 'cx-stdlib/time']
[$time:mock-set [$time:from-unix 1000]]
null
time:date
[$time:date] -> date — Construct a date from year, month, and day components.
[?lib 'cx-stdlib/time']
[$time:date 2026 5 26]
'2026-05-26'
time:datetime
[$time:datetime] -> datetime — Construct a UTC datetime from year, month, day, hour, minute, and second.
[?lib 'cx-stdlib/time']
[$time:datetime 2026 5 26 14 30 0]
'2026-05-26T14:30:00Z'
time:datetime-with-tz
[$time:datetime-with-tz] -> datetime — Construct a datetime from components interpreted in the named timezone.
[?lib 'cx-stdlib/time']
[$time:datetime-with-tz 2026 1 15 12 0 0 "America/New_York"]
'2026-01-15T12:00:00-05:00'
time:from-unix
[$time:from-unix] -> instant — Construct an instant from a Unix timestamp in seconds.
[?lib 'cx-stdlib/time']
[$time:from-unix 1000]
1000000000000
time:from-unix-ms
[$time:from-unix-ms] -> instant — Construct an instant from a Unix timestamp in milliseconds.
[?lib 'cx-stdlib/time']
[$time:from-unix-ms 1500]
1500000000
time:from-unix-ns
[$time:from-unix-ns] -> instant — Construct an instant from a Unix timestamp in nanoseconds.
[?lib 'cx-stdlib/time']
[$time:from-unix-ns 42]
42
time:epoch
[$time:epoch] -> instant — Return the Unix epoch instant (1970-01-01T00:00:00Z).
[?lib 'cx-stdlib/time']
[$time:epoch]
0
time:year
[$time:year] -> int — Extract the year component of a date or datetime.
[?lib 'cx-stdlib/time']
[$time:year [$time:parse-date "2026-05-26"]]
2026
time:month
[$time:month] -> int — Extract the month component (1-12) of a date or datetime.
[?lib 'cx-stdlib/time']
[$time:month [$time:parse-date "2026-05-26"]]
5
time:day
[$time:day] -> int — Extract the day-of-month component of a date or datetime.
[?lib 'cx-stdlib/time']
[$time:day [$time:parse-date "2026-05-26"]]
26
time:hour
[$time:hour] -> int — Extract the hour component (0-23) of a datetime.
[?lib 'cx-stdlib/time']
[$time:hour [$time:parse-datetime "2026-05-26T14:30:45Z"]]
14
time:minute
[$time:minute] -> int — Extract the minute component (0-59) of a datetime.
[?lib 'cx-stdlib/time']
[$time:minute [$time:parse-datetime "2026-05-26T14:30:45Z"]]
30
time:second
[$time:second] -> int — Extract the second component (0-59) of a datetime.
[?lib 'cx-stdlib/time']
[$time:second [$time:parse-datetime "2026-05-26T14:30:45Z"]]
45
time:nanosecond
[$time:nanosecond] -> int — Extract the sub-second nanosecond component of a datetime.
[?lib 'cx-stdlib/time']
[$time:nanosecond [$time:parse-datetime "2026-05-26T14:30:45.250Z"]]
250000000
time:weekday
[$time:weekday] -> atom — Return the day of the week as an atom, from :monday to :sunday.
[?lib 'cx-stdlib/time']
[$time:weekday [$time:parse-date "2026-05-26"]]
:tuesday
time:day-of-year
[$time:day-of-year] -> int — Return the 1-based day of the year (1-366).
[?lib 'cx-stdlib/time']
[$time:day-of-year [$time:parse-date "2026-01-01"]]
1
time:week-of-year
[$time:week-of-year] -> int — Return the week number of the year.
[?lib 'cx-stdlib/time']
[$time:week-of-year [$time:parse-date "2026-01-05"]]
2
time:timezone-offset
[$time:timezone-offset] -> int — Return the offset from UTC in seconds for a datetime.
[?lib 'cx-stdlib/time']
[$time:timezone-offset [$time:parse-datetime "2026-01-15T12:00:00-05:00"]]
-18000
time:to-unix
[$time:to-unix] -> int — Convert a datetime to a Unix timestamp in seconds.
[?lib 'cx-stdlib/time']
[$time:to-unix [$time:parse-datetime "1970-01-01T00:16:40Z"]]
1000
time:to-unix-ms
[$time:to-unix-ms] -> int — Convert a datetime to a Unix timestamp in milliseconds.
[?lib 'cx-stdlib/time']
[$time:to-unix-ms [$time:parse-datetime "1970-01-01T00:00:01Z"]]
1000
time:to-unix-ns
[$time:to-unix-ns] -> int — Convert a datetime to a Unix timestamp in nanoseconds.
[?lib 'cx-stdlib/time']
[$time:to-unix-ns [$time:parse-datetime "1970-01-01T00:00:01Z"]]
1000000000
time:add
[$time:add] -> any — Add a duration to a date, datetime, or instant, advancing real elapsed time.
[?lib 'cx-stdlib/time']
[$time:add [$time:parse-datetime "2026-05-26T14:00:00Z"] [$time:duration-h 2]]
'2026-05-26T16:00:00Z'
time:subtract
[$time:subtract] -> any — Subtract a duration from a date, datetime, or instant, rewinding real elapsed time.
[?lib 'cx-stdlib/time']
[$time:subtract [$time:parse-datetime "2026-05-26T14:00:00Z"] [$time:duration-h 2]]
'2026-05-26T12:00:00Z'
time:diff
[$time:diff] -> duration — Return the duration from the second time to the first.
[?lib 'cx-stdlib/time']
[$time:diff [$time:parse-datetime "2026-05-26T14:00:00Z"] [$time:parse-datetime "2026-05-26T13:00:00Z"]]
3600000000000
time:add-days
[$time:add-days] -> date — Advance a date by a number of calendar days.
[?lib 'cx-stdlib/time']
[$time:add-days [$time:parse-date "2026-05-26"] 10]
'2026-06-05'
time:add-months
[$time:add-months] -> date — Advance a date by a number of calendar months, clamping to end-of-month.
[?lib 'cx-stdlib/time']
[$time:add-months [$time:parse-date "2026-01-31"] 1]
'2026-02-28'
time:add-months-strict
[$time:add-months-strict] -> date — Advance a date by calendar months, raising rather than clamping a non-existent day.
[?lib 'cx-stdlib/time']
[$time:add-months-strict [$time:parse-date "2026-01-31"] 1]
cx-err:CXER3300
time:add-years
[$time:add-years] -> date — Advance a date by a number of calendar years, clamping to end-of-month.
[?lib 'cx-stdlib/time']
[$time:add-years [$time:parse-date "2024-02-29"] 1]
'2025-02-28'
time:add-hours
[$time:add-hours] -> datetime — Advance a datetime by a number of hours of real elapsed time.
[?lib 'cx-stdlib/time']
[$time:add-hours [$time:parse-datetime "2026-05-26T22:00:00Z"] 5]
'2026-05-27T03:00:00Z'
time:add-minutes
[$time:add-minutes] -> datetime — Advance a datetime by a number of minutes of real elapsed time.
[?lib 'cx-stdlib/time']
[$time:add-minutes [$time:parse-datetime "2026-05-26T14:00:00Z"] 90]
'2026-05-26T15:30:00Z'
time:add-seconds
[$time:add-seconds] -> datetime — Advance a datetime by a number of seconds of real elapsed time.
[?lib 'cx-stdlib/time']
[$time:add-seconds [$time:parse-datetime "2026-05-26T14:00:00Z"] 75]
'2026-05-26T14:01:15Z'
time:duration-ms
[$time:duration-ms] -> duration — Build a duration from a count of milliseconds.
[?lib 'cx-stdlib/time']
[$time:duration-ms 100]
100000000
time:duration-s
[$time:duration-s] -> duration — Build a duration from a count of seconds.
[?lib 'cx-stdlib/time']
[$time:duration-s 5]
5000000000
time:duration-m
[$time:duration-m] -> duration — Build a duration from a count of minutes.
[?lib 'cx-stdlib/time']
[$time:duration-m 2]
120000000000
time:duration-h
[$time:duration-h] -> duration — Build a duration from a count of hours.
[?lib 'cx-stdlib/time']
[$time:add [$time:parse-datetime "2026-05-26T14:00:00Z"] [$time:duration-h 2]]
'2026-05-26T16:00:00Z'
time:duration-d
[$time:duration-d] -> duration — Build a duration from a count of days.
[?lib 'cx-stdlib/time']
[$time:duration-d 1]
86400000000000
time:duration-parts
[$time:duration-parts] -> element — Decompose a duration into days, hours, minutes, seconds, and nanoseconds.
[?lib 'cx-stdlib/time']
[$time:duration-parts [$time:parse-duration "1d2h30m45s"]]
[duration-parts days=1 hours=2 minutes=30 seconds=45 nanoseconds=0]
time:duration-total-ms
[$time:duration-total-ms] -> int — Return the duration as a total count of milliseconds.
[?lib 'cx-stdlib/time']
[$time:duration-total-ms [$time:duration-s 3]]
3000
time:duration-total-s
[$time:duration-total-s] -> int — Return the duration as a total count of seconds.
[?lib 'cx-stdlib/time']
[$time:duration-total-s [$time:duration-h 2]]
7200
time:duration-total-h
[$time:duration-total-h] -> float — Return the duration as a fractional count of hours.
[?lib 'cx-stdlib/time']
[$time:duration-total-h [$time:duration-h 2]]
2.0
time:duration-add
[$time:duration-add] -> duration — Add two durations.
[?lib 'cx-stdlib/time']
[$time:duration-add [$time:duration-s 1] [$time:duration-s 2]]
3000000000
time:duration-sub
[$time:duration-sub] -> duration — Subtract the second duration from the first.
[?lib 'cx-stdlib/time']
[$time:duration-sub [$time:duration-s 5] [$time:duration-s 2]]
3000000000
time:duration-mul
[$time:duration-mul] -> duration — Multiply a duration by an integer factor.
[?lib 'cx-stdlib/time']
[$time:duration-mul [$time:duration-s 2] 3]
6000000000
time:duration-div
[$time:duration-div] -> duration — Divide a duration by an integer divisor; raises on division by zero.
[?lib 'cx-stdlib/time']
[$time:duration-div [$time:duration-s 6] 3]
2000000000
time:parse-date
[$time:parse-date] -> date — Parse an ISO 8601 date string into a date value.
[?lib 'cx-stdlib/time']
[$time:year [$time:parse-date "2026-05-26"]]
2026
time:parse-datetime
[$time:parse-datetime] -> datetime — Parse an ISO 8601 datetime string into a datetime value.
[?lib 'cx-stdlib/time']
[$time:hour [$time:parse-datetime "2026-05-26T14:30:45Z"]]
14
time:parse-instant
[$time:parse-instant] -> instant — Parse an ISO 8601 string into an instant normalized to UTC.
[?lib 'cx-stdlib/time']
[$time:parse-instant "1970-01-01T00:00:01Z"]
1000000000
time:parse-duration
[$time:parse-duration] -> duration — Parse an ISO 8601 duration or shorthand string into a duration value.
[?lib 'cx-stdlib/time']
[$time:duration-parts [$time:parse-duration "1d2h30m45s"]]
[duration-parts days=1 hours=2 minutes=30 seconds=45 nanoseconds=0]
time:parse-rfc3339
[$time:parse-rfc3339] -> datetime — Parse an RFC 3339 timestamp string into a datetime value.
[?lib 'cx-stdlib/time']
[$time:parse-rfc3339 "2026-05-26T14:30:00Z"]
'2026-05-26T14:30:00Z'
time:parse-rfc2822
[$time:parse-rfc2822] -> datetime — Parse an RFC 2822 email-style date string into a datetime value.
[?lib 'cx-stdlib/time']
[$time:parse-rfc2822 "Tue, 26 May 2026 14:30:00 +0000"]
'2026-05-26T14:30:00Z'
time:parse-with-format
[$time:parse-with-format] -> datetime — Parse a string into a datetime using an ICU/LDML pattern.
[?lib 'cx-stdlib/time']
[$time:parse-with-format "2026-05-26 14:30:00" "yyyy-MM-dd HH:mm:ss"]
'2026-05-26T14:30:00Z'
time:parse-strftime
[$time:parse-strftime] -> datetime — Parse a string into a datetime using strftime tokens, for ingesting external output.
[?lib 'cx-stdlib/time']
[$time:parse-strftime "2026-05-26 14:30:00" "%Y-%m-%d %H:%M:%S"]
'2026-05-26T14:30:00Z'
time:format-iso8601
[$time:format-iso8601] -> string — Format a date or datetime as a canonical ISO 8601 string.
[?lib 'cx-stdlib/time']
[$time:format-iso8601 [$time:parse-datetime "2026-05-26T14:30:00Z"]]
'2026-05-26T14:30:00Z'
time:format-rfc3339
[$time:format-rfc3339] -> string — Format a datetime as an RFC 3339 timestamp string.
[?lib 'cx-stdlib/time']
[$time:format-rfc3339 [$time:parse-datetime "2026-05-26T14:30:00Z"]]
'2026-05-26T14:30:00Z'
time:format-rfc2822
[$time:format-rfc2822] -> string — Format a datetime as an RFC 2822 email-style date string.
[?lib 'cx-stdlib/time']
[$time:format-rfc2822 [$time:parse-datetime "2026-05-26T14:30:00Z"]]
'Tue, 26 May 2026 14:30:00 +0000'
time:format-with-format
[$time:format-with-format] -> string — Format a date or datetime using an ICU/LDML pattern at the root locale.
[?lib 'cx-stdlib/time']
[$time:format-with-format [$time:parse-datetime "2026-05-26T14:30:00Z"] "yyyy-MM-dd HH:mm:ss"]
'2026-05-26 14:30:00'
time:format-duration
[$time:format-duration] -> string — Format a duration as a shorthand string such as 1d2h30m45s.
[?lib 'cx-stdlib/time']
[$time:format-duration [$time:parse-duration "1d2h30m45s"]]
'1d2h30m45s'
time:format-relative
[$time:format-relative] -> string — Format a datetime relative to a reference time, such as 2 hours ago.
[?lib 'cx-stdlib/time']
[$time:format-relative [$time:parse-datetime "2026-05-26T12:00:00Z"] [$time:parse-datetime "2026-05-26T14:00:00Z"]]
'2 hours ago'
time:timezone
[$time:timezone] -> element — Look up an IANA timezone by name, returning its offset and DST status.
[?lib 'cx-stdlib/time']
[$time:timezone "America/New_York"]
[timezone name='America/New_York' offset=-18000 dst=true]
time:to-timezone
[$time:to-timezone] -> datetime — Convert a datetime to the wall-clock time in the named timezone.
[?lib 'cx-stdlib/time']
[$time:to-timezone [$time:parse-datetime "2026-01-15T17:00:00Z"] "America/New_York"]
'2026-01-15T12:00:00-05:00'
time:to-utc
[$time:to-utc] -> datetime — Convert a datetime to its equivalent in UTC.
[?lib 'cx-stdlib/time']
[$time:to-utc [$time:parse-datetime "2026-01-15T12:00:00-05:00"]]
'2026-01-15T17:00:00Z'
time:utc-now
[$time:utc-now] -> datetime — Return the current wall-clock datetime in UTC.
[?lib 'cx-stdlib/time']
[$time:timezone-offset [$time:utc-now]]
cx-err:CXER0271
time:system-timezone
[$time:system-timezone] -> string — Return the host's configured timezone identifier.
[?lib 'cx-stdlib/time']
[>= [$time:timezone-offset [$time:datetime-with-tz 2026 1 15 12 0 0 [$time:system-timezone]]] -86400]
cx-err:CXER0271
time:list-timezones
[$time:list-timezones] -> [sequence string] — List the available IANA timezone identifiers.
[?lib 'cx-stdlib/time']
[$time:list-timezones]
('UTC', 'Etc/UTC', 'America/New_York', 'America/Chicago', 'America/Denver', 'America/Los_Angeles', 'Europe/London', 'Europe/Paris', 'Europe/Berlin', 'Asia/Tokyo', 'Asia/Kolkata', 'Australia/Sydney')
time:is-leap-year
[$time:is-leap-year] -> bool — Report whether the given year is a leap year.
[?lib 'cx-stdlib/time']
[$time:is-leap-year 2024]
true
time:is-before
[$time:is-before] -> bool — Report whether the first time is chronologically before the second.
[?lib 'cx-stdlib/time']
[$time:is-before [$time:parse-date "2026-01-01"] [$time:parse-date "2026-12-31"]]
true
time:is-after
[$time:is-after] -> bool — Report whether the first time is chronologically after the second.
[?lib 'cx-stdlib/time']
[$time:is-after [$time:parse-date "2026-12-31"] [$time:parse-date "2026-01-01"]]
true
time:is-same
[$time:is-same] -> bool — Report whether two times denote the same instant, regardless of offset.
[?lib 'cx-stdlib/time']
[$time:is-same [$time:parse-datetime "2026-05-26T14:00:00Z"] [$time:parse-datetime "2026-05-26T16:00:00+02:00"]]
true
time:is-same-day
[$time:is-same-day] -> bool — Report whether two datetimes fall on the same calendar day.
[?lib 'cx-stdlib/time']
[$time:is-same-day [$time:parse-datetime "2026-05-26T01:00:00Z"] [$time:parse-datetime "2026-05-26T23:00:00Z"]]
true
time:days-in-month
[$time:days-in-month] -> int — Return the number of days in the given month of the given year.
[?lib 'cx-stdlib/time']
[$time:days-in-month 2024 2]
29
time:recurrence
[$time:recurrence] -> element — Build and eagerly validate a recurrence rule from a frequency, anchor, timezone, and options.
[?lib 'cx-stdlib/time']
[$time:recurrence :yearly '2026-01-01T09:00:00' 'UTC' {by-month: 2 by-month-day: 30}]
cx-err:CXER3323
time:validate-rule
[$time:validate-rule] -> element — Run the full validation check on a recurrence rule, raising on a fault.
[?lib 'cx-stdlib/time']
[$time:validate-rule [recurrence freq=:weekly anchor='2026-06-01T09:00:00' tz='UTC' count=2 until='2026-12-01T00:00:00']]
cx-err:CXER3323
time:is-valid-rule
[$time:is-valid-rule] -> bool — Report whether a recurrence rule is valid, never raising.
[?lib 'cx-stdlib/time']
[$time:is-valid-rule [recurrence freq=:monthly anchor='2026-01-01T09:00:00' tz='UTC' [by-day [nth 3 :thursday]]]]
true
time:parse-rrule
[$time:parse-rrule] -> element — Parse an RFC 5545 RRULE string into a recurrence rule, given an anchor and timezone.
[?lib 'cx-stdlib/time']
[$time:format-rrule [$time:parse-rrule 'FREQ=MONTHLY;BYDAY=3TH' '2026-01-01T09:00:00' 'UTC']]
'FREQ=MONTHLY;BYDAY=3TH'
time:format-rrule
[$time:format-rrule] -> string — Serialize a recurrence rule to its RFC 5545 RRULE string form.
[?lib 'cx-stdlib/time']
[$time:format-rrule [$time:parse-rrule 'FREQ=MONTHLY;BYDAY=3TH' '2026-01-01T09:00:00' 'UTC']]
'FREQ=MONTHLY;BYDAY=3TH'
time:parse-cron
[$time:parse-cron] -> element — Parse a 5- or 6-field cron expression or @macro into a recurrence rule.
[?lib 'cx-stdlib/time']
[$time:format-cron [$time:parse-cron '30 9 * * 1' 'UTC']]
'30 9 * * 1'
time:format-cron
[$time:format-cron] -> element — Serialize a recurrence rule to a cron string, raising if cron cannot express it.
[?lib 'cx-stdlib/time']
[$time:format-cron [$time:parse-cron '30 9 * * 1' 'UTC']]
'30 9 * * 1'
time:next-occurrence
[$time:next-occurrence] -> datetime — Return the first occurrence of a rule strictly after the given time.
[?lib 'cx-stdlib/time']
[$time:next-occurrence [recurrence freq=:daily anchor='2026-06-01T09:00:00' tz='UTC' count=5] '2026-06-02T09:00:00']
'2026-06-03T09:00:00Z'
time:occurrences-in
[$time:occurrences-in] -> [sequence datetime] — Return a rule's occurrences within a half-open window, in ascending order.
[?lib 'cx-stdlib/time']
[$time:occurrences-in [recurrence freq=:daily anchor='2026-06-01T09:00:00' tz='UTC' count=3] '2026-06-01T00:00:00' '2026-06-10T00:00:00']
('2026-06-01T09:00:00Z', '2026-06-02T09:00:00Z', '2026-06-03T09:00:00Z')
time:nth-occurrence
[$time:nth-occurrence] -> datetime — Return the nth occurrence of a rule, counting 1-based from the anchor.
[?lib 'cx-stdlib/time']
[$time:nth-occurrence [recurrence freq=:weekly interval=2 anchor='2026-06-01T00:00:00' tz='UTC' [by-day :monday :wednesday :friday]] 4]
'2026-06-15T00:00:00Z'
time:rule-freq
[$time:rule-freq] -> atom — Return the base frequency atom of a recurrence rule.
[?lib 'cx-stdlib/time']
[$time:rule-freq [$time:parse-rrule 'FREQ=MONTHLY;BYDAY=3TH' '2026-01-01T09:00:00' 'UTC']]
:monthly
time:rule-bound
[$time:rule-bound] -> element — Return a rule's bound — a count, an until datetime, or absence if infinite.
[?lib 'cx-stdlib/time']
[$time:rule-bound [recurrence freq=:daily anchor='2026-06-01T09:00:00' tz='UTC' count=3]]
[count 3]
time:rule-is-finite
[$time:rule-is-finite] -> bool — Report whether a recurrence rule produces a finite number of occurrences.
[?lib 'cx-stdlib/time']
[$time:rule-is-finite [recurrence freq=:daily anchor='2026-06-01T09:00:00' tz='UTC' count=3]]
true