Zhex separates calendar dates and local times from instants. A Duration measures elapsed nanoseconds; a TimeZone names a zone, and a ZonedDateTime combines a zone with an instant. Format these values explicitly with to-string.
let zone = timezone.load "America/New_York" try
let start = zoned.new(date.new(2024, 3, 9), time.new(12, 0, 0), zone)
let elapsed = duration.parse "24h" try
print(zoned.to-string(zoned.add-days(start, 1)))
print(zoned.to-string(zoned.add-duration(start, elapsed)))
The first result is noon the next day; the second is 1 p.m. because the daylight-saving change skips an hour. See the complete temporal example.
| Operation | Result | Use |
|---|---|---|
date.new(year, month, day) |
Date |
Construct a Gregorian date in years 1–9999. |
date.parse(text) |
Result<Date, Error> |
Parse YYYY-MM-DD. |
date.to-string(date) |
String |
Format a date. |
date.add-days(date, days) |
Date |
Move by calendar days. |
time.new(hour, minute, second) |
Time |
Construct a local time; leap seconds are not supported. |
time.parse(text) |
Result<Time, Error> |
Parse HH:MM:SS with optional fractional seconds up to nine digits. |
time.to-string(time) |
String |
Format local time. |
duration.new(nanoseconds) |
Duration |
Construct from nanoseconds; the Duration range is the signed 64-bit nanosecond span, and wider Ints fail temporal-range. |
duration.parse(text) |
Result<Duration, Error> |
Parse elapsed units such as ns, us, µs, ms, s, m, and h. |
duration.to-string(duration) |
String |
Format elapsed duration. |
instant.now() |
Instant |
Read the current instant. |
instant.parse(text) |
Result<Instant, Error> |
Parse RFC 3339 with an explicit offset. |
instant.to-string(instant) |
String |
Format in UTC with nanosecond precision as needed. |
instant.add-duration(instant, duration) |
Instant |
Move by elapsed time. |
timezone.load(name) |
Result<TimeZone, Error> |
Load UTC or a named IANA zone. Empty and Local are rejected. |
timezone.name(zone) |
String |
Return the zone name. |
zoned.new(date, time, zone) |
ZonedDateTime |
Resolve a local date and time in a zone. |
zoned.to-string(value) |
String |
Format local date, time, offset, and zone name. |
zoned.instant(value) |
Instant |
Extract the instant. |
zoned.in-zone(value, zone) |
ZonedDateTime |
Preserve the instant in another zone. |
zoned.add-days(value, days) |
ZonedDateTime |
Move by local calendar days. |
zoned.add-duration(value, duration) |
ZonedDateTime |
Move by elapsed time. |
When clocks repeat a local time, construction selects the earlier instant. When a local time falls in a gap, it shifts forward by the actual gap, including non-hour transitions. Adding zero calendar days preserves the original instant, including the later occurrence of a repeated time. Named-zone data is bundled as a fallback when system zone data is unavailable.
Ordinary numeric construction and arithmetic validate their inputs and raise source-located runtime diagnostics for invalid components or out-of-range results. Parsing and zone lookup are recoverable Results: use try or catch. Time and instant parsing reject leap seconds and excess fractional precision. Instant inputs need an explicit offset; output uses UTC. The supported range is years 1 through 9999 for both local and UTC representations.
Zoned display uses an RFC 3339-style local timestamp followed by [zone name]. Some historical zones used offsets containing seconds; their display includes ±HH:MM:SS to preserve the actual offset. This extended zoned display is not an instant.parse input. Temporal values have no implicit conversion, direct print or equality, or JSON encoding; use explicit formatting.