Per-field chrono format wrappers: glz::date_format and glz::epoch_count (#2658)

* Add per-field chrono format wrappers: glz::date_format and glz::epoch_count

Decouple the wire format from the chrono type (issue #2640) with two JSON
field wrappers usable inside glz::object():

  - glz::date_format<&T::m, "%Y-%m-%d %H:%M:%S"> renders a system_clock
    time_point or year_month_day with a hand-rolled, compile-time-validated
    strftime subset (%Y %m %d %H %M %S %F %T %%). UTC wall-clock; %S is integer
    seconds (sub-second truncated by design).
  - glz::epoch_count<&T::m, Duration> renders a system_clock time_point as a
    numeric Unix count, the per-field counterpart to glz::epoch_time.

Both follow the established wrapper precedents (float_format's NTTP format_str,
quoted_t's full custom read+write) and are JSON-only: marked glaze_reflect=false
so binary backends fail to compile rather than silently miscode.

Format string parsing/formatting is hand-rolled (no std::chrono::parse/format)
reusing the existing write_digits/parse_digits primitives, for consistent
behavior across the compiler matrix. utc_time and binary backends are
intentionally out of scope for this MVP.

- Extract format_str NTTP into glaze/core/format_str.hpp (shared with float_format)
- Add strftime-subset helpers to chrono_detail in glaze/core/chrono.hpp
- New header glaze/json/chrono_format.hpp; wired via glaze/chrono.hpp
- Tests in tests/chrono_test and docs in docs/chrono.md

* Harden per-field chrono wrappers after review

Review-driven guards, tests, and docs for glz::date_format / glz::epoch_count.
No behavioral regressions for valid inputs.

- epoch_count: validate the Duration unit (is_duration) alongside the member
  type via a shared validate_epoch_count() guard, so a non-duration unit gives
  a friendly message instead of a cascade out of `typename Duration::rep`.
- date_format: reject an invalid/default year_month_day on write
  (constraint_violated) so the writer never emits a string its own reader
  rejects, and an out-of-range month/day cannot slip past write_digits<2>.
- date_format: skip the ensure_space reservation on the write_unchecked fast
  path (matches to<JSON, num_t>); correct the buffer-size comments (%F, not %T,
  is the widest token at 5 bytes per source char).
- docs: correct the backend-scope wording (text/JSON-family only; TOML also
  fails to compile; NDJSON/stencil work) and document the epoch_count integer
  input contract.
- tests: compile-time validator assertions plus runtime coverage for year
  boundaries, pre-1970 instants, the %% literal, sub-second read-back, the
  epoch_count cross-precision duration_cast, and the invalid-ymd write guard.

* Fix MSVC overflow building far-future instants in date_format

MSVC's std::chrono::hours and minutes use a 32-bit rep, so reconstructing a
far-future instant as `sys_days{ymd} + hours + minutes + seconds` overflows
the intermediate minutes count (days * 24 * 60 exceeds INT_MAX, ~4.2e9 at year
9999) and silently wraps to a bogus instant. libc++/libstdc++ use a 64-bit rep,
so the year-boundary test passed there but failed on the msvc/clang-cl jobs,
emitting 1833-11-15T19:43:59 for 9999-12-31T23:59:59.

Anchor the day at seconds precision (sys_seconds) before folding in the
time-of-day so the whole chain is computed in 64 bits, in both the date_format
reader and the test's input construction.

* Switch per-field chrono wrappers to value-based call syntax

date_format and epoch_count now take the member pointer as a value argument:

  glz::date_format(&T::start, "%Y-%m-%d %H:%M:%S")
  glz::epoch_count<std::chrono::milliseconds>(&T::logged)

Previously the member pointer and (for date_format) the format string were
non-type template parameters. Carrying the format as a runtime std::string_view
keys the view type on the member type alone, so fields that differ only in their
format string no longer each instantiate a fresh date_format_t / to / from /
closure. On a synthetic struct of N same-typed members with distinct formats this
removed ~40% of the wrapper's template instantiations and made the per-distinct-
format compile cost ~flat (it tracks a single shared format). date_format's
strftime walk was already runtime, so codegen is unchanged.

The strftime pattern stays a compile-time literal: a consteval guard in the
date_format() factory still rejects unsupported tokens, a missing calendar date,
and time tokens on a year_month_day field. float_format keeps its NTTP form
because it relies on std::format's compile-time format checking.

The reader keeps the seconds-anchored reconstruction (sys_seconds) so far-future
years stay exact under MSVC's 32-bit chrono hours/minutes rep.

* Report date_format compile errors without throw (-fno-exceptions safe)

The consteval date_format() validator used throw to turn an invalid format
string into a compile error. throw is ill-formed under -fno-exceptions even
inside an immediate function, so the chrono_test build (which compiles with
-fno-exceptions -fno-rtti) failed across the GCC/Clang matrix.

Replace the throws with calls to non-constexpr marker functions on the error
branches: when a branch is constant-evaluated the call makes the immediate
invocation non-constant, producing a hard compile error whose diagnostic names
the marker. Same compile-time rejection of unsupported tokens, a missing date,
and time tokens on a year_month_day field, now without relying on exceptions.

* docs: surface per-field chrono wrappers in the wrapper catalog

date_format and epoch_count were documented only in chrono.md and were absent
from docs/wrappers.md, the canonical wrapper list where the sibling float_format
lives, so a user browsing wrappers would not find them. Add both there (with the
glaze/chrono.hpp include note and a link to the chrono docs).

Also round out the chrono.md section: add a read/round-trip example for
date_format (previously only the write side was shown) and document the
write-side constraint_violated error for out-of-range years / non-ok dates.

Author: stephenberry

.gitignore

@@ -65,3 +65,4 @@ pr_description.md
 /exterior
 pr.md
 /tmp/
+tmp/

docs/chrono.md

@@ -180,6 +180,94 @@ struct Event {
 };
 ```
 
+## Per-Field Format Customization
+
+The clock type alone decides the default representation (ISO 8601 for `system_clock`, numeric count for `steady_clock`, and so on). When a single field needs a different shape, the per-field wrappers below decouple the *format* from the *type*. They are applied inside `glz::object(...)` within a `glz::meta<T>` specialization and require `#include "glaze/chrono.hpp"`.
+
+### `glz::date_format` — custom strftime-subset pattern
+
+`glz::date_format(&T::member, "pattern")` serializes a `system_clock` time point (or a `year_month_day`) using a `strftime`-style pattern instead of ISO 8601:
+
+```cpp
+#include "glaze/chrono.hpp"
+
+struct Event {
+    std::chrono::system_clock::time_point start{};
+    std::chrono::sys_days day{};
+};
+
+template <>
+struct glz::meta<Event> {
+    using T = Event;
+    static constexpr auto value = glz::object(
+        "start", glz::date_format(&T::start, "%Y-%m-%d %H:%M:%S"),  // "2026-06-18 12:34:56"
+        "day",   glz::date_format(&T::day,   "%Y/%m/%d"));          // "2026/06/18"
+};
+```
+
+The wrapper is bidirectional: the same pattern parses the value back on read.
+
+```cpp
+Event e{};
+e.start = std::chrono::sys_days{std::chrono::year{2026} / 6 / 18} + std::chrono::hours{12} +
+          std::chrono::minutes{34} + std::chrono::seconds{56};
+
+std::string json = glz::write_json(e).value();   // {"start":"2026-06-18 12:34:56","day":"..."}
+
+Event parsed{};
+auto ec = glz::read_json(parsed, json);           // parsed.start == e.start
+```
+
+The member pointer and pattern are passed as ordinary arguments (not template parameters), so fields that share a member type but differ in format do not each spin up a fresh set of template instantiations. The pattern is still a compile-time literal and is validated at compile time.
+
+Supported conversion specifiers (locale-independent by design):
+
+| Token | Meaning              | Token | Meaning                |
+|-------|----------------------|-------|------------------------|
+| `%Y`  | year (4 digits)      | `%H`  | hour, 24-hour (2)      |
+| `%m`  | month (2 digits)     | `%M`  | minute (2 digits)      |
+| `%d`  | day (2 digits)       | `%S`  | second (2 digits)      |
+| `%F`  | `%Y-%m-%d`           | `%T`  | `%H:%M:%S`             |
+| `%%`  | literal `%`          |       |                        |
+
+The pattern is validated at compile time:
+
+- An unsupported token (e.g. `%A`, `%j`, `%z`) is a hard compile error.
+- The pattern must contain a full calendar date (`%Y %m %d`, or `%F`); a time-only pattern cannot reconstruct an absolute time point and is rejected.
+- A `year_month_day` field rejects time tokens (`%H %M %S %T`).
+
+Notes and limitations (MVP scope):
+
+- **Times are treated as UTC wall-clock.** There is no timezone token; the decomposed fields are UTC, matching the ISO 8601 writer.
+- **The four-digit-year range still applies.** As with the ISO 8601 writers, a year outside `[0000, 9999]` (or a non-`ok()` `year_month_day`) fails to serialize with `error_code::constraint_violated` rather than emitting wrap-around digits.
+- **`%S` writes integer seconds only.** Sub-second precision is truncated on write (the format you typed has nowhere to put it), so round-tripping a finer-than-seconds value through a `%S` pattern is lossy by design. Use the default ISO 8601 representation when you need sub-second fidelity. Explicit-width fraction tokens (`%3S`/`%6S`/`%9S`) are a planned extension.
+- **Text/JSON-family backends only.** `date_format` is a textual wrapper that routes through the JSON serializer, so it also works for the JSON-family text outputs (NDJSON, stencil/mustache). Serializing a field that uses it to a backend with its own native encoding (BEVE, CBOR, MsgPack, BSON, or TOML) is a compile error (an undefined `glz::to<Format, …>`) rather than a silent miscoding.
+
+### `glz::epoch_count` — per-field Unix timestamp
+
+`glz::epoch_count<Duration>(&T::member)` serializes a `system_clock` time point as a numeric Unix timestamp in units of `Duration`. It is the per-field counterpart to the `glz::epoch_time` storage wrapper, letting one field be an epoch count while others stay ISO 8601:
+
+```cpp
+#include "glaze/chrono.hpp"
+
+struct Reading {
+    std::chrono::system_clock::time_point observed{};   // ISO 8601 (default)
+    std::chrono::sys_time<std::chrono::milliseconds> logged{};
+};
+
+template <>
+struct glz::meta<Reading> {
+    using T = Reading;
+    static constexpr auto value = glz::object(
+        "observed", &T::observed,                                       // "2026-06-18T12:34:56Z"
+        "logged",   glz::epoch_count<std::chrono::milliseconds>(&T::logged));  // 1781786096789
+};
+```
+
+Unlike `glz::epoch_time<Duration>` (a storage type you declare your member as), `glz::epoch_count` wraps an ordinary `system_clock` time-point member in place, so you can keep the field's native type. Like `date_format`, it routes through the JSON serializer (so it also works for NDJSON and stencil output) and is a compile error under the native-encoding backends (BEVE, CBOR, MsgPack, BSON, TOML).
+
+The count is read as a JSON integer: exponent form (`1e3` → `1000`) is accepted, while fractional values (`1.5`) and quoted numbers (`"1500"`) are rejected with `error_code::parse_error`.
+
 ## Complete Example
 
 ```cpp
@@ -264,6 +352,8 @@ TOML has native datetime types (not quoted strings). When using `glz::write_toml
 - `hh_mm_ss<Duration>` → TOML Local Time (`10:30:45.123`)
 - Durations and other time points → Numeric values
 
+> The per-field `glz::date_format` / `glz::epoch_count` wrappers are JSON-text-only and do **not** compile under `glz::write_toml`. Native (unwrapped) chrono members serialize as TOML datetimes as shown above; only the per-field format wrappers are restricted.
+
 See [TOML Documentation](./toml.md#datetime-support) for full details.
 
 ## CBOR Datetime Support

docs/wrappers.md

@@ -34,8 +34,15 @@ glz::custom<&T::read, &T::write> // Calls custom read and write std::functions,
 glz::manage<&T::x, &T::read_x, &T::write_x> // Calls read_x() after reading x and calls write_x() before writing x
 glz::as_array<&T::member> // Treat a reflected/member-annotated type as a positional array for read and write
 glz::flatten_map<&T::member> // Flatten map-like containers into a JSON array [key..., value, ...]
+
+// Per-field std::chrono wrappers (require #include "glaze/chrono.hpp"; JSON-text backends only)
+glz::date_format(&T::time_point, "%Y-%m-%d %H:%M:%S") // Format a system_clock time point or year_month_day with a strftime-subset pattern
+glz::epoch_count<std::chrono::milliseconds>(&T::time_point) // Write a system_clock time point as a numeric Unix timestamp in the given units
 ```
 
+> [!NOTE]
+> Unlike the wrappers above, `glz::date_format` and `glz::epoch_count` take the member pointer as a value argument rather than a non-type template parameter, and they live in `#include "glaze/chrono.hpp"`. See [std::chrono Support](chrono.md#per-field-format-customization) for the supported tokens, compile-time validation, and limitations.
+
 ## Associated glz::opts
 
 `glz::opts` is the compile time options struct passed to most of Glaze functions to configure read/write behavior. Many wrappers are associated with compile time options that can be set via a custom options struct inheriting from `glz::opts`.

include/glaze/chrono.hpp

@@ -7,5 +7,6 @@
 // Includes all necessary headers for chrono serialization
 
 #include "glaze/core/chrono.hpp"
+#include "glaze/json/chrono_format.hpp"
 #include "glaze/json/read.hpp"
 #include "glaze/json/write.hpp"