Skip to content

Date/Time Transforms

Normative reference

See the Transforms reference for the normative definition of each transform below, plus worked examples.

kBars represents a date-time as its own value kind, distinct from a number or a string. Three transforms move between numbers/strings and this representation; the arithmetic transforms (plus, minus, at_least, at_most) also accept a date-time input — see Math Transforms.

Name Arguments Description
as_date_time: unit? ("milliseconds" default, or "seconds") Converts a numeric epoch timestamp to a date-time.
parse_date_time: format? treatAsLocal? Parses a date-time string. See Format names below. treatAsLocal ("true"/"false", default "false") interprets a timezone-naive string as local time instead of UTC.
format_date_time: format? zone? Formats a date-time to a string. zone is an IANA/TimeZone.of-recognized zone id (default "UTC").

Format names

Both parse_date_time and format_date_time accept the same format vocabulary:

Format Meaning
"iso8601" / "rfc3339" (default) ISO-8601 / RFC 3339, e.g. 2026-07-10T12:00:00Z. Parsing also accepts a bare LocalDateTime or LocalDate string, interpreted in the given (or default UTC) zone.
"rfc1123" / "rfc2822" RFC 1123, e.g. Fri, 10 Jul 2026 12:00:00 GMT.
anything else A kotlinx.datetime Unicode format pattern, e.g. "yyyy-MM-dd".

An unparseable string, or an invalid format pattern, is a soft failure (UnparseableInput) yielding null. An unrecognized zone id is likewise a soft failure.

@env/now

Every render includes a default now property — a date-time value captured when the render started — so it flows straight into these transforms with no setup:

{{ @env/now | format_date_time: "yyyy-MM-dd" }}

See Environment Properties for the @env namespace this and every other property lives in.

Examples

{{ 1752148800000 | as_date_time | format_date_time: "yyyy-MM-dd" }}

{{ "2026-07-10" | parse_date_time: "yyyy-MM-dd" | format_date_time: "rfc1123" }}

{{ @env/now | plus: 7 | format_date_time: "yyyy-MM-dd" }}    {{! a week from now }}

{{ startDate | minus: endDate }}    {{! signed day count between two date-times }}

Where to next