Date-Time Support

Since 0.7, Guardian Tcl includes an experimental dt command providing a modern date-time manipulation API that is aware of calendars, time zones, and similar complexifiers. It is a powered by (and designed around) the Rust Jiff library, which in turn is heavily inspired by JavaScript Temporal.

Warning

The Guardian dt command is highly experimental and may change significantly as I figure out what an ergonomic, modern Tcl date/time API looks like.

Date Object Types

The dt commands operate on multiple types of date/time objects (referred to below as dto). The supported types map to different Jiff objects, and are as follows:

zoned: An instant in time with an associated time zone. This is the most complete date/time type, and corresponds to jiff::Zoned. The time zone may be a fixed offset, or it may be a transition-aware time zone such as America/New_York.
datetime: A date and time without an associated time zone. It is ambiguous whether such times are local or UTC, and interpretation is determined by context and/or command options.
date: A date without a time. Represented in ISO format (e.g., 2026-10-09).
time: A time without a date. Represented as HH:MM:SS[.SS…]
timestamp: An instant in time, represented as seconds since the epoch UTC or an ISO Zulu date-time. Integer and floating-point numbers are interpreted as timestamps when passed to dt commands.

The dt commands interpret strings as the most precise object they can successfully parse into. When serialized as strings, they are normalized to the corresponding ISO format as implemented by Jiff.

Note

There is not currently any mechanism to work with local timestamps (seconds since the epoch local time).

Current Time

dt now: Obtain the current time as a zoned.

Query / Extraction

dt type dto: Query the type of date object stored in dto.
dt date dto: Extract the date part of dto.
dt time dto: Extract the time part of dto.
dt timestamp dto: Convert dto to a Unix timestamp (seconds since the epoch).
dt year dto: Extract the year from dto.
dt month dto: Extract the month from dto.
dt day dto: Extract the day from dto.
dt week dto: Extract the ISO week-date week number from dto.
dt weekday dto: Extract the weekday of dto.
dt is complete dto: Query whether dto is a complete specification of an exact point in time. Timestamps and zoned date-times are complete;, dates, times, and unzoned date-time objects are not complete.
dt is span obj: Query whether obj is a span.
dt same month dto1 dto2: Query whether dto1 and dto2 occur in the same month (and year).
dt same week dto1 dto2: Query whether dto1 and dto2 occur in same year and ISO (Monday-based) week.

Display and Formatting

dt format fmt dto: Format dto according to fmt. The format specifier fmt uses the syntax of [jiff::fmt::strtime][strtime], which is mostly compatible with Unix strftime. Truly locale-aware formatting is not yet supported.
dt rfc2822 ?-local? dto: Display the date/time dto in RFC 2822 (HTTP / e-mail header) format. With ?-local?, converts to local time first. To display the current local time in RFC 2822, you can write dt rfc2822 -local now.
dt friendly dto: Display a “friendly” version of dto (or a span), intended for human consumption. This format has no stability guarantees, although the friendly version of a span is the same as Jiff’s, and will round-trip for commands like dt add.

[strtime]

Parsing / Normalization

dt parse ?flags? str

Parse a date-time, ensuring it is valid and possibly converting it. The supported flags are:

-local: Parse into local time, yielding a zoned. Zoned and timestamp inputs are translated to the system’s local time, and unzoned date-time inputs are interpreted as local time and turned into zoned. Bare dates and times are unchanged.
-utc: Like -local, but interprets or translates to UTC instead of the system’s local time.
-span: Parse a span (such as 1mo or 2h50m) instead of a date/time. This validates that the object is properly interpretable as a span by Jiff, and pre-parses it into a jiff::Span for subsequent use by other commands like dt add.
-format fmt: Parse a date according to fmt, which is a [jiff::fmt::strtime][strtime] format string.

Manipulation

dt add dto span

Add the specified span to dto. The base date can be any supported date/time object, although not all date and span combinations are possible (e.g., adding a month to a time will fail).

dt adjust dto how args

Adjust the specified dto to a different day. how specifies the kind adjustment, and args provides additional information. The following combinations of how and args are supported:

next weekday, prev weekday: Change to the next or previous weekday (mon, tue, etc.)
[+-]N weekday: Advance (or step back) by N weekdays, e.g. +2 mondays
first weekday, last weekday: Adjust to the first or last weekday of the date’s month. second, third, etc. (up to fifth) are also accepted.

Examples:

# adjust to 2026-10-12
dt adjust 2026-10-10 next monday
# find US Thanksgiving - Nov. 26
dt adjust 2026-11-01 fourth thursday

dt subtract dto rhs

Subtract rhs (either a span or a DTO) from a DTO, yielding a DTO or a span.

Keyboard shortcuts