Skip to content

Commit 57f634f

Browse files
committed
feat(format): D-470 — the %t/%T date/time conversion family (UTC/English, AD-052)
Smell-audited: 2: the tz/locale question got an AD, not an ad-hoc pick — AD-052 records why UTC+English is the ONE deterministic rendering (cljw ships no tz/locale database per D-462; the JVM's own %t output is host-env-dependent), pinned by e2e; corpus deliberately NOT used (host clj is JST/ja — goldens would be locale-dependent). formatTimeSub covers time (H k I l M S L N p z Z s Q), date (Y y C m d e j B b h A a), and composites (R T r D F c); args accept java.util.Date or Long epoch-ms (Java semantics); %T upper-cases the rendering. Every numeric conversion verified byte-for-byte against `TZ=UTC clj`. En-route fix: Zig's signed `{d:0>N}` prints an explicit `+` — padNum renders the sign manually. The stale "no width/flags yet" error template corrected. e2e phase14_format 41->48 cases. D-470 discharged.
1 parent 9665b2c commit 57f634f

5 files changed

Lines changed: 165 additions & 7 deletions

File tree

‎.dev/accepted_divergences.yaml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -883,3 +883,19 @@ accepted:
883883
ARE byte-usable in cljw). Record: `private/notes/2026-06-25-D472-bytes-da-fork.md`.
884884
derives_from: "AD-019 (type-erased arrays — no per-array component type, so byte-array is runtime-indistinguishable from any other array) + F-004 (uniform 8-byte Value) + F-005 (no primitive specialization) + F-011 (the common positive guard `(bytes? (byte-array n))` matches clj true exactly; only non-byte arrays diverge) + F-013 (no bespoke per-array type-tag mechanism added to fake a distinction the representation does not carry)."
885885
pin: "test/e2e/phase14_arity_parity.sh — `AD-051 (bytes? byte-array)`/`AD-051 (bytes? int-array)`/`AD-051 (bytes? object-array)` lock cljw's over-broad `true` (incl. the int/object-array cases where clj returns false). The clj-IDENTICAL cases (byte-array→true, string/nil/vector→false) are corpus-pinned in test/diff/clj_corpus/clojure_1_11_additions.txt."
886+
- id: "AD-052"
887+
summary: "format's `%t` date/time conversions render in UTC with fixed English names (month/day/am-pm) and a fixed `+0000`/`UTC` zone; the JVM renders in the process's default TIME ZONE and LOCALE (a JST/ja machine shows shifted hours and 金曜日/2月/午後)."
888+
example: '(format "%tH" 0) => cljw "00" (UTC) / clj-on-JST "09" ; (format "%ta" 1234567890123) => cljw "Fri" / clj-on-ja "金"'
889+
why: |-
890+
cljw ships no tz database and no locale data (edge/wasm target — D-462
891+
recorded tz-DB as out of scope). Java's Formatter %t uses the JVM default
892+
TimeZone + Locale, both host-environment-dependent, so the JVM's own
893+
output is not even stable across machines. cljw picks the one rendering
894+
that IS deterministic everywhere: UTC + English (= the JVM's behaviour
895+
under TZ=UTC LANG=en, the CI-conventional environment). Numeric
896+
conversions (%tY %tm %td %tH %tM %tS %tL %tj %ts %tQ %tD %tF %tT %tR
897+
%tr) match a TZ=UTC JVM byte-for-byte — verified against `TZ=UTC clj`
898+
2026-07-07. Name conversions (%ta %tA %tb %tB %tp) match an
899+
English-locale JVM.
900+
derives_from: "ADR-0059 no-JVM (no host tz/locale database dependency) + F-011 (the deterministic-environment rendering matches TZ=UTC/en JVM exactly; only the host-env-dependent rendering diverges) + D-462 (tz database out of scope for the edge/wasm target)."
901+
pin: "test/e2e/phase14_format.sh — the `%t` cases pin the UTC/English renderings (epoch-0 hour 00, Fri/Feb names, +0000 zone)."

‎.dev/debt.yaml‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -344,11 +344,6 @@ active:
344344
workload type-checks java.util host collections, or alongside a host-supertype
345345
refactor. Cross-ref class_name.zig matchUserType, ADR-0116, ADR-0102.
346346
last_reviewed: "2026-06-20"
347-
- id: "D-470"
348-
status: "open (2026-06-20, clj-diff format probe). `clojure.core/format` does NOT support the `%t`/`%T` date/time conversion family: `(format \"%tY\" (java.util.Date. 0))` → cljw 'unsupported directive %t' vs clj '1970'. The `%t` family is ~40 sub-conversions (%tY year / %tm month / %td day / %tH hour / %tM min / %tS sec / %tF ISO-date / %tT ISO-time / %tc full / %tj day-of-year / %tB %tb month-name / %ta %tA weekday / %tp am-pm / %tI %tl 12h / %tR %tr / %tD / %tZ %tz zone / %ts epoch-sec / %tQ epoch-ms …) over a Date/Calendar/Long/TemporalAccessor arg. The rest of the format flag/conversion surface is COMPLETE (D-216 discharged 2026-06-03 + a 2026-06-20 verify-sweep re-confirmed: heap-Long %d, unsigned-64 %x, # alternate, float +/space/(/, flags, %S/%H, %.Ns, %s-nil→null all match clj; %h/%H hashcode = AD-009). LOW priority — `%t` printf-style date formatting is rare in idiomatic Clojure (date code uses java.time formatters / clojure.instant, not (format \"%tY\" …)). Take up on a real consumer; mechanise via the format_surface corpus (anti-D-177) when landed. The zone sub-directives (%tZ/%tz) would also need the user/ADR-owned tz-DB (cf. D-462 ZonedDateTime)."
349-
category: "clj-parity"
350-
barrier: "none — bounded but sizable (~40 sub-conversions + Date/Long/Temporal arg dispatch); a focused unit when a consumer needs it. Zone sub-directives gated on the tz-DB (D-462)."
351-
last_reviewed: "2026-06-20"
352347
- id: "D-471"
353348
status: "open (2026-06-20, IO probe — surfaced while fixing spit options). `slurp`/`spit` accept ONLY a string PATH for the file arg; clj routes the arg through the `clojure.java.io/Coercions` + `IOFactory` protocols, so `(spit (clojure.java.io/file \"/tmp/x\") c)` / `(slurp (clojure.java.io/file …))` (a java.io.File), and a `java.net.URL`/`URI`/`Reader`/`Writer`/`InputStream` arg, all work in clj. cljw raises 'spit: expected string, got host_instance'. The file_io.zig primitive docstring already acknowledges this ('restricted to the file-path overload; the URL / Reader / Writer overloads arrive when java.net.URL / java.io.Reader land'). SAME-CYCLE PROGRESS (2026-06-20): spit's `& options` (`:append` truthy→append via new file_io.appendAll, `:encoding` UTF-8 no-op) + content `(str …)`-coercion (non-string content rendered via print.writeStrValue; string fast-path) ARE now done + clj-verified (e2e phase16_clojure_java_io spit_append_options). REMAINING = the PATH-arg Coercions: accept a java.io.File host_instance (extract its path — cljw File already stores one) for slurp/spit (the common, tractable sub-case); URL/URI/Reader/Writer/stream args are gated on those types landing (lower value). LOW-MODERATE priority — `(spit (io/file …) …)` is moderately common in real code; take up as a focused unit (extract File path + a coerce-to-path helper shared by slurp+spit). DRAIN 2026-06-25: the File-arg sub-case LANDED — a coerceToPath(rt, v) helper in lang/primitive/file_io.zig accepts a .string directly OR a java.io.File host_instance (extracts its state[0] path); R4-clean, identifying the File by descriptor identity via rt.types + host_instance (NOT importing the runtime/java/io surface — the uriQ pattern). Both slurp and spit consult it; a non-File/non-string still raises. clj-verified ((spit (io/file p) c) + (slurp (io/file p)) round-trip + multi-segment File); e2e phase16_clojure_java_io slurp_spit_file_arg. REMAINING (lower value, NOT the common case): URL / URI / Reader / Writer / InputStream args route through clj IOFactory (slurp a Reader reads the stream) — a bigger unit gated on routing slurp/spit through the stream surface; take up when a consumer needs a non-File Coercions arg."
354349
category: "clj-parity"
@@ -6474,6 +6469,12 @@ discharged:
64746469
barrier: "DISCHARGED (was: ns attr-map skipped at analysis)."
64756470
last_reviewed: "2026-07-07"
64766471

6472+
- id: "D-470"
6473+
status: "DISCHARGED 2026-07-07. `format` gained the full `%t`/`%T` date/time conversion family (formatTimeSub in primitive/core.zig): time H k I l M S L N p z Z s Q / date Y y C m d e j B b h A a / composites R T r D F c — args accept java.util.Date or Long epoch-ms (Java semantics). RENDERING IS UTC + ENGLISH + `+0000` (AD-052): cljw ships no tz/locale database (edge/wasm target, D-462), and the JVM's own %t output is host-env-dependent — cljw picks the TZ=UTC/en JVM rendering, verified byte-for-byte against `TZ=UTC clj` for every numeric conversion (2009-02-13 23:31:30 / 02/13/09|11:31:30 PM|044|… / epoch-0 row). Zig gotcha fixed en route: signed `{d:0>N}` prints an explicit `+` — padNum() renders sign manually. %T upper-cases the whole rendering. e2e phase14_format +7 cases (48 total; the AD-052 pin); the stale `no width/flags yet` error template was corrected. Corpus intentionally NOT used (host clj is JST/ja — the sweep would record locale-dependent goldens)."
6474+
category: "clj-parity"
6475+
barrier: "DISCHARGED (was: format %t family unimplemented)."
6476+
last_reviewed: "2026-07-07"
6477+
64776478
conventions: |-
64786479
- Structure: two top-level lists — `active:` and `discharged:`. Active entries carry id / status / category / barrier (+ optional quality_floor / last_reviewed); discharged entries carry id / discharged_at / resolution. Edit as YAML (no Markdown table to align).
64796480
- New debt: grep `.dev/debt.yaml` for class-overlap before adding (per `.claude/rules/debt_dedup.md`).

‎src/lang/primitive/core.zig‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ const env_mod = @import("../../runtime/env.zig");
1313
const iref = @import("../../runtime/iref.zig");
1414
const higher_order = @import("higher_order.zig");
1515
const tagged_literal_mod = @import("../../runtime/tagged_literal.zig");
16+
const date_mod = @import("../../runtime/time/date.zig");
17+
const instant_mod = @import("../../runtime/time/instant.zig");
1618
const Env = env_mod.Env;
1719
const error_mod = @import("../../runtime/error/info.zig");
1820
const error_catalog = @import("../../runtime/error/catalog.zig");
@@ -946,6 +948,109 @@ fn formatFloatArg(val: Value, loc: SourceLocation) error_mod.ClojureWasmError!f6
946948
};
947949
}
948950

951+
const month_names = [_][]const u8{ "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December" };
952+
const day_names = [_][]const u8{ "Thursday", "Friday", "Saturday", "Sunday", "Monday", "Tuesday", "Wednesday" }; // epoch day 0 = Thu
953+
954+
/// One `%t<sub>` date/time sub-conversion over UTC-decomposed epoch millis
955+
/// (Java Formatter's date/time suffix table). Composites (R T r D F c) are
956+
/// built from the primitives recursively.
957+
/// Zero-padded decimal print of a possibly-negative i64 — Zig's `{d:0>N}`
958+
/// prints an explicit `+` for signed types, which Java's Formatter never does.
959+
fn padNum(tw: *std.Io.Writer, v: i64, comptime width: u8) anyerror!void {
960+
var x = v;
961+
if (x < 0) {
962+
try tw.writeByte('-');
963+
x = -x;
964+
}
965+
try tw.print(std.fmt.comptimePrint("{{d:0>{d}}}", .{width}), .{@as(u64, @intCast(x))});
966+
}
967+
968+
fn formatTimeSub(tw: *std.Io.Writer, sub: u8, ms: i64, loc: SourceLocation) anyerror!void {
969+
const days = @divFloor(ms, 86_400_000);
970+
const civ = instant_mod.civilFromDays(days);
971+
const ms_of_day = @mod(ms, 86_400_000);
972+
const h24: u32 = @intCast(@divFloor(ms_of_day, 3_600_000));
973+
const minute: u32 = @intCast(@mod(@divFloor(ms_of_day, 60_000), 60));
974+
const second: u32 = @intCast(@mod(@divFloor(ms_of_day, 1000), 60));
975+
const milli: u32 = @intCast(@mod(ms_of_day, 1000));
976+
const h12: u32 = if (@mod(h24, 12) == 0) 12 else @mod(h24, 12);
977+
switch (sub) {
978+
'H' => try padNum(tw, h24, 2),
979+
'k' => try padNum(tw, h24, 1),
980+
'I' => try padNum(tw, h12, 2),
981+
'l' => try padNum(tw, h12, 1),
982+
'M' => try padNum(tw, minute, 2),
983+
'S' => try padNum(tw, second, 2),
984+
'L' => try padNum(tw, milli, 3),
985+
'N' => try padNum(tw, @as(i64, milli) * 1_000_000, 9),
986+
'p' => try tw.writeAll(if (h24 < 12) "am" else "pm"),
987+
'z' => try tw.writeAll("+0000"), // UTC (no tz database; see the %t arm note)
988+
'Z' => try tw.writeAll("UTC"),
989+
's' => try padNum(tw, @divFloor(ms, 1000), 1),
990+
'Q' => try padNum(tw, ms, 1),
991+
'Y' => try padNum(tw, civ.y, 4),
992+
'y' => try padNum(tw, @mod(civ.y, 100), 2),
993+
'C' => try padNum(tw, @divFloor(civ.y, 100), 2),
994+
'm' => try padNum(tw, civ.m, 2),
995+
'd' => try padNum(tw, civ.d, 2),
996+
'e' => try padNum(tw, civ.d, 1),
997+
'j' => try padNum(tw, days - instant_mod.daysFromCivil(civ.y, 1, 1) + 1, 3),
998+
'B' => try tw.writeAll(month_names[@intCast(civ.m - 1)]),
999+
'b', 'h' => try tw.writeAll(month_names[@intCast(civ.m - 1)][0..3]),
1000+
'A' => try tw.writeAll(day_names[@intCast(@mod(days, 7))]),
1001+
'a' => try tw.writeAll(day_names[@intCast(@mod(days, 7))][0..3]),
1002+
'R' => {
1003+
try formatTimeSub(tw, 'H', ms, loc);
1004+
try tw.writeByte(':');
1005+
try formatTimeSub(tw, 'M', ms, loc);
1006+
},
1007+
'T' => {
1008+
try formatTimeSub(tw, 'R', ms, loc);
1009+
try tw.writeByte(':');
1010+
try formatTimeSub(tw, 'S', ms, loc);
1011+
},
1012+
'r' => {
1013+
try formatTimeSub(tw, 'I', ms, loc);
1014+
try tw.writeByte(':');
1015+
try formatTimeSub(tw, 'M', ms, loc);
1016+
try tw.writeByte(':');
1017+
try formatTimeSub(tw, 'S', ms, loc);
1018+
try tw.writeByte(' ');
1019+
try tw.writeAll(if (@divFloor(ms_of_day, 3_600_000) < 12) "AM" else "PM");
1020+
},
1021+
'D' => {
1022+
try formatTimeSub(tw, 'm', ms, loc);
1023+
try tw.writeByte('/');
1024+
try formatTimeSub(tw, 'd', ms, loc);
1025+
try tw.writeByte('/');
1026+
try formatTimeSub(tw, 'y', ms, loc);
1027+
},
1028+
'F' => {
1029+
try formatTimeSub(tw, 'Y', ms, loc);
1030+
try tw.writeByte('-');
1031+
try formatTimeSub(tw, 'm', ms, loc);
1032+
try tw.writeByte('-');
1033+
try formatTimeSub(tw, 'd', ms, loc);
1034+
},
1035+
'c' => {
1036+
// "Sat Nov 04 12:02:33 UTC 1999" (Java %tc shape, UTC).
1037+
try formatTimeSub(tw, 'a', ms, loc);
1038+
try tw.writeByte(' ');
1039+
try formatTimeSub(tw, 'b', ms, loc);
1040+
try tw.writeByte(' ');
1041+
try formatTimeSub(tw, 'd', ms, loc);
1042+
try tw.writeByte(' ');
1043+
try formatTimeSub(tw, 'T', ms, loc);
1044+
try tw.writeAll(" UTC ");
1045+
try formatTimeSub(tw, 'Y', ms, loc);
1046+
},
1047+
else => {
1048+
const sb = [_]u8{ '%', 't', sub };
1049+
return error_catalog.raise(.format_spec_invalid, loc, .{ .spec = sb[0..] });
1050+
},
1051+
}
1052+
}
1053+
9491054
pub fn formatFn(rt: *Runtime, env: *Env, args: []const Value, loc: SourceLocation) anyerror!Value {
9501055
if (args.len == 0 or args[0].tag() != .string)
9511056
return error_catalog.raise(.type_arg_not_string, loc, .{ .fn_name = "format", .actual = if (args.len == 0) "nil" else @tagName(args[0].tag()) });
@@ -1131,6 +1236,32 @@ pub fn formatFn(rt: *Runtime, env: *Env, args: []const Value, loc: SourceLocatio
11311236
const cn = std.unicode.utf8Encode(args[src].asChar(), &cbuf) catch 0;
11321237
try tw.writeAll(cbuf[0..cn]);
11331238
},
1239+
// `%t<X>`/`%T<X>` date/time conversions (D-470). Arg = a
1240+
// java.util.Date or a Long (epoch millis, Java semantics).
1241+
// Rendered in UTC: cljw ships no tz database (edge/wasm target),
1242+
// so the JVM's default-locale-TZ rendering is an accepted
1243+
// divergence (AD — corpus-unfixable, e2e pins the UTC values).
1244+
't', 'T' => {
1245+
if (i >= fmt.len) return error_catalog.raise(.format_spec_invalid, loc, .{ .spec = "%t" });
1246+
const sub = fmt[i];
1247+
i += 1;
1248+
const ms: i64 = if (date_mod.isDate(rt, args[src]))
1249+
date_mod.epochMsOf(args[src])
1250+
else if (args[src].tag() == .integer)
1251+
args[src].asInteger()
1252+
else
1253+
return error_catalog.raise(.arg_value_invalid, loc, .{ .fn_name = "format", .expected = "Date or Long (epoch ms) for %t", .actual = @tagName(args[src].tag()) });
1254+
try formatTimeSub(tw, sub, ms, loc);
1255+
if (conv == 'T') {
1256+
// %T upper-cases the whole rendering (Java Formatter).
1257+
const lower = tmp.writer.buffered();
1258+
const upper = try rt.gpa.alloc(u8, lower.len);
1259+
defer rt.gpa.free(upper);
1260+
for (lower, 0..) |ch, k| upper[k] = std.ascii.toUpper(ch);
1261+
tmp.clearRetainingCapacity();
1262+
try tw.writeAll(upper);
1263+
}
1264+
},
11341265
else => {
11351266
const sb = [_]u8{ '%', conv };
11361267
return error_catalog.raise(.format_spec_invalid, loc, .{ .spec = sb[0..] });

‎src/runtime/error/catalog.zig‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1148,7 +1148,7 @@ pub fn entry(comptime code: Code) Entry {
11481148
.format_spec_invalid => .{
11491149
.kind = .type_error,
11501150
.phase = .eval,
1151-
.template = "format: unsupported directive '{[spec]s}' (supported: %s %d %f %.Nf %x %% %n; no width/flags yet)",
1151+
.template = "format: unsupported directive '{[spec]s}'",
11521152
},
11531153
.format_args_insufficient => .{
11541154
.kind = .type_error,

‎test/e2e/phase14_format.sh‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,9 +86,19 @@ assert_eq 'h_hex' "$("$BIN" -e '(format "%h" "abc")')" '"b3dd93
8686
assert_eq 'H_hex' "$("$BIN" -e '(format "%H" "abc")')" '"B3DD93FA"'
8787
assert_eq 'h_nil' "$("$BIN" -e '(format "%h" nil)')" '"null"'
8888

89+
# %t date/time family (D-470). AD-052 pins: UTC + English names + "+0000"
90+
# zone (cljw ships no tz/locale database; matches a TZ=UTC/en JVM exactly).
91+
assert_eq 't_F_T' "$("$BIN" -e '(format "%tF %tT" 1234567890123 1234567890123)')" '"2009-02-13 23:31:30"'
92+
assert_eq 't_epoch0' "$("$BIN" -e '(format "%tY/%tm/%td %tH:%tM:%tS.%tL" 0 0 0 0 0 0 0)')" '"1970/01/01 00:00:00.000"'
93+
assert_eq 't_names' "$("$BIN" -e '(format "%ta %tA %tb %tB %tp %tz %tZ" 0 0 0 0 0 0 0)')" '"Thu Thursday Jan January am +0000 UTC"'
94+
assert_eq 't_comp' "$("$BIN" -e '(format "%tD|%tr|%tj|%ts|%tQ" 1234567890123 1234567890123 1234567890123 1234567890123 1234567890123)')" '"02/13/09|11:31:30 PM|044|1234567890|1234567890123"'
95+
assert_eq 't_date' "$("$BIN" -e '(format "%tF" (java.util.Date. 86400000))')" '"1970-01-02"'
96+
assert_eq 'T_upper' "$("$BIN" -e '(format "%TA" 0)')" '"THURSDAY"'
97+
assert_has 't_badsub' "$("$BIN" -e '(format "%tq" 0)' 2>&1)" 'unsupported directive'
98+
8999
# errors
90100
assert_has 'badtype' "$("$BIN" -e '(format "%d" "x")' 2>&1)" 'expected an integer'
91101
assert_has 'fewargs' "$("$BIN" -e '(format "%d")' 2>&1)" 'not enough arguments'
92102
assert_has 'badconv' "$("$BIN" -e '(format "%q" 1)' 2>&1)" 'unsupported directive'
93103
assert_has 'fmtstr' "$("$BIN" -e '(format 42)' 2>&1)" 'expected string'
94-
echo "OK — phase14_format smoke (41 cases) green"
104+
echo "OK — phase14_format smoke (48 cases) green"

0 commit comments

Comments
 (0)