# clock/format
Format an epoch-seconds value as a string. Positional form
`[clock/format time ?format? ?timezone?]`; spec-map form
`[clock/format time %{ :format "…" :timezone "…" :locale "…" }]`.
## Syntax
[clock/format $t] # default ISO-8601, local tz [clock/format $t "%Y-%m-%d"] # positional format [clock/format $t "%Y-%m-%d" "UTC"] # format + timezone [clock/format $t %{ :format "%A, %B %d" :timezone "UTC" }] # spec-map form
## Parameters
- `$t` — epoch seconds (number)
- format — optional format string (string); default `"%Y-%m-%dT%H:%M:%S%z"`
- timezone — optional `"UTC"`, `"local"`, or `+HHMM` offset (string on the
positional form; see Timezones)
- spec-map keys:
- `:format` — format string
- `:timezone` — timezone
- `:locale` — locale name (English-only MVP — `""`, `"en"`, `"en_US"`)
## Format specifiers
| Spec | Meaning | Spec | Meaning |
|------|---------|------|---------|
| `%Y` | 4-digit year | `%j` | Day of year 001–366 |
| `%y` | 2-digit year (windowed 1938–2037) | `%u` | Weekday 1=Mon..7=Sun |
| `%C` | Century | `%w` | Weekday 0=Sun..6=Sat |
| `%m` | Month 01–12 | `%s` | Epoch seconds |
| `%d` | Day of month 01–31 | `%p` | AM/PM uppercase |
| `%e` | Day of month, space-padded | `%P` | am/pm lowercase |
| `%H` | Hour 00–23 (24-hour) | `%A` `%a` | Full / abbreviated weekday |
| `%I` | Hour 01–12 (12-hour) | `%B` `%b` `%h` | Full / abbreviated month |
| `%M` | Minute 00–59 | `%z` | Timezone offset `+HHMM` |
| `%S` | Second 00–59 | `%Z` | Timezone offset (alias of `%z`) |
| `%%` | Literal `%` | `%n` `%t` | Newline / tab |
Composite specifiers are expanded before formatting:
| Spec | Expansion |
|------|-----------|
| `%T` | `%H:%M:%S` |
| `%R` | `%H:%M` |
| `%D` | `%m/%d/%y` |
| `%F` | `%Y-%m-%d` |
| `%r` | `%I:%M:%S %p` |
| `%+` | `%a %b %e %H:%M:%S %Y` |
## Timezones
| Form | Example | Notes |
|------|---------|-------|
| `"UTC"` / `:UTC` / `"Z"` | `"UTC"` | Fixed UTC. |
| `"local"` / `"localtime"` / omitted | `"local"` | Defer to libc `localtime_r`. |
| Numeric offset | `"+0530"`, `"-0800"`, `"+053045"` | 4 or 6 digits with sign. |
Olson identifiers (`"America/New_York"`) are reserved for a future extension —
the API is designed to accept them unchanged when zoneinfo support lands.
## Examples
[clock/format [clock/seconds]] # → "2026-09-25T10:56:50-0300" [clock/format 0 "%Y-%m-%d %H:%M:%S" "UTC"] # → "1970-01-01 00:00:00" [clock/format 0 "%A, %B %d %Y" "UTC"] # → "Thursday, January 01 1970" [clock/format 0 "%T %D" "UTC"] # → "00:00:00 01/01/70"
## Returns
Formatted string.
## See Also
`clock/scan` (the inverse), `clock/seconds`, `clock/add`