io extension: align with coding conventions

Three convention-compliance fixes that don't change behaviour:

1. Rename IOFMT_USER_CASES_ -> IOFMT_USER_CASE_ to match the singular
   sibling pattern (IOFMT_BITVEC_CASE_, IOFMT_INT_CASE_, IOFMT_FLOAT_CASE_).

2. Add SUCCESS:/FAILURE: lines to the IOFMT_USER_CASE_ doc block per the
   "every public function and macro" rule -- they describe the compile-
   time behaviour of the hook (registers user arms in IOFMT's _Generic;
   mis-typed arms surface as compile/link errors).

3. Rewrite _read_Point2D / _read_Bounds / _read_Region to use StrIter
   with the peek-then-Must idiom from the conventions doc (matching the
   in-tree _read_u8 / _read_Str shape) instead of bare Zstr pointer
   walks. The guide example is updated to match so users copy the
   conventional shape.

The Log.h include moves below Io.h (it transitively pulls Io.h, which
would lock in the empty-fallback IOFMT_USER_CASE_ before our override).
This constraint is now documented inline in the test and in the guide's
"A Minimal Example" section.

105-test suite still green.

Author: brightprogrammer

Docs/content/english/guides/extending-io-with-user-types.md

@@ -1,7 +1,7 @@
 ---
 title: "Extending IO with User-Defined Types"
 date: 2026-06-03
-description: "Plug your own types into WriteFmt / StrReadFmt / FReadFmt through the IOFMT_USER_CASES_ extension hook, with no call-site wrapper and full compile-time type safety."
+description: "Plug your own types into WriteFmt / StrReadFmt / FReadFmt through the IOFMT_USER_CASE_ extension hook, with no call-site wrapper and full compile-time type safety."
 authors:
   - siddharth-mishra
 tags:
@@ -19,7 +19,7 @@ For built-ins (`i32`, `f64`, `Str`, `Zstr`, `BitVec`, `Int`, `Float`, …) those
 WriteFmt("got {}", IO_WRAP(my_widget));  // not what we want
 ```
 
-`IOFMT_USER_CASES_` removes that wrapper. After a one-time hook in your project header, every call site reads exactly the same as if the type were built in:
+`IOFMT_USER_CASE_` removes that wrapper. After a one-time hook in your project header, every call site reads exactly the same as if the type were built in:
 
 ```c
 WriteFmt("got {}", my_widget);           // dispatches through your writer
@@ -32,9 +32,14 @@ Dispatch stays compile-time, type-safe (unknown types fail to match), and zero-o
 The TU layout has four blocks, in this order:
 
 ```c
-// 1. Headers that introduce your type's dependencies.
+// 1. Headers that introduce your type's dependencies and the iterator
+//    helpers your reader will use. NOTHING that transitively pulls in
+//    <Misra/Std/Io.h> belongs here -- if Io.h's empty-fallback for
+//    IOFMT_USER_CASE_ runs before our override, the override silently
+//    loses (the redefinition warning is the friendly outcome).
 #include <Misra/Std/Allocator/Default.h>
 #include <Misra/Std/Container/Str.h>
+#include <Misra/Std/Utility/StrIter.h>
 #include <Misra/Std/Zstr.h>
 #include <Misra/Types.h>
 
@@ -46,29 +51,51 @@ typedef struct {
 
 // 3. The extension hook -- one arm per user type, comma-terminated.
 //    MUST be defined before <Misra/Std/Io.h> is processed.
-#define IOFMT_USER_CASES_(x, addr) \
+#define IOFMT_USER_CASE_(x, addr) \
     Point2D : TO_TYPE_SPECIFIC_IO(Point2D, addr),
 
-// 4. The IO header, then your writer / reader definitions.
+// 4. The IO header (and any Io.h-pulling headers such as Log.h), then
+//    your writer / reader definitions.
 #include <Misra/Std/Io.h>
+#include <Misra/Std/Log.h>
 
 bool _write_Point2D(Str *o, FmtInfo *info, Point2D *p) {
     (void)info;
     return StrAppendFmt(o, "({}, {})", p->x, p->y);
 }
 
+// Readers walk the input through a StrIter rather than bare pointer
+// arithmetic -- matches the in-tree convention (`_read_u8`, `_read_Str`)
+// and means whitespace / delimiter handling can lean on the peek-then-
+// Must idiom. When delegating to a built-in reader like `_read_i32`,
+// hand it `StrIterDataAt(&si, StrIterIndex(&si))` and rebuild the
+// iterator from the Zstr it returns.
 Zstr _read_Point2D(Zstr i, FmtInfo *info, Point2D *p) {
     (void)info;
-    while (*i == ' ' || *i == '\t') i++;
-    if (*i != '(') return i;
-    i++;
+    StrIter si = StrIterFromZstr(i);
+    char    c  = 0;
+
+    while (StrIterPeek(&si, &c) && IS_SPACE(c)) StrIterMustNext(&si);
+    if (!StrIterPeek(&si, &c) || c != '(') {
+        return StrIterDataAt(&si, StrIterIndex(&si));
+    }
+    StrIterMustNext(&si);
+
     FmtInfo inner = {0};
-    i = _read_i32(i, &inner, &p->x);
-    while (*i == ' ' || *i == '\t' || *i == ',') i++;
-    i = _read_i32(i, &inner, &p->y);
-    while (*i == ' ' || *i == '\t') i++;
-    if (*i == ')') i++;
-    return i;
+    Zstr    rest  = _read_i32(StrIterDataAt(&si, StrIterIndex(&si)),
+                              &inner, &p->x);
+
+    si = StrIterFromZstr(rest);
+    while (StrIterPeek(&si, &c) && (IS_SPACE(c) || c == ',')) {
+        StrIterMustNext(&si);
+    }
+    rest = _read_i32(StrIterDataAt(&si, StrIterIndex(&si)),
+                     &inner, &p->y);
+
+    si = StrIterFromZstr(rest);
+    while (StrIterPeek(&si, &c) && IS_SPACE(c)) StrIterMustNext(&si);
+    if (StrIterPeek(&si, &c) && c == ')') StrIterMustNext(&si);
+    return StrIterDataAt(&si, StrIterIndex(&si));
 }
 ```
 
@@ -104,7 +131,7 @@ Zstr _read_T (Zstr i, FmtInfo *info, T *self);
 | Field | Meaning |
 | --- | --- |
 | `Str *o` | Output sink for the writer. Append with `StrAppendFmt(o, …)`, `StrAppend(o, …)`, etc. |
-| `Zstr i` | Input cursor for the reader. Treat as `const char *` -- advance with `i++` or by returning a pointer further along. |
+| `Zstr i` | Input cursor for the reader. Wrap with `StrIterFromZstr(i)` and walk it through `StrIterPeek` / `StrIterMustNext`; return the post-parse position via `StrIterDataAt(&si, StrIterIndex(&si))`. |
 | `FmtInfo *info` | Parsed `{...}` spec (width, precision, flags). Ignore with `(void)info;` if you do not care. |
 | `T *self` | Pointer to the user value. The IOFMT machinery passes `&val` of the original argument. |
 | **Writer return** | `true` on success, `false` on allocation failure (the IO pipeline propagates). |
@@ -116,11 +143,11 @@ If you only need printing, define `_read_T` as a stub that returns `i` unchanged
 
 ## Include-Order Rule
 
-`IOFMT_USER_CASES_` works because of this fragment near the top of `<Misra/Std/Io.h>`:
+`IOFMT_USER_CASE_` works because of this fragment near the top of `<Misra/Std/Io.h>`:
 
 ```c
-#ifndef IOFMT_USER_CASES_
-#    define IOFMT_USER_CASES_(x, addr) /* empty -- override before include */
+#ifndef IOFMT_USER_CASE_
+#    define IOFMT_USER_CASE_(x, addr) /* empty -- override before include */
 #endif
 ```
 
@@ -129,11 +156,11 @@ If you `#include <Misra/Std/Io.h>` *before* defining the hook, the empty fallbac
 - `WriteFmt("{}", my_widget);` fails to compile with *"controlling expression type not compatible with any generic association"* -- this is the safe failure mode.
 - Or, if a built-in arm coincidentally matches (e.g. you wrap a single `i32`), the wrong writer runs silently.
 
-Practical rule: put the `#define IOFMT_USER_CASES_(...)` line in **a single project-wide header**, include nothing else in that header except what your types' declarations need, and include it before any other Misra IO surface in every TU that formats your types.
+Practical rule: put the `#define IOFMT_USER_CASE_(...)` line in **a single project-wide header**, include nothing else in that header except what your types' declarations need, and include it before any other Misra IO surface in every TU that formats your types.
 
 ## Forward Declarations Inside Writer Bodies
 
-If your writer calls `StrAppendFmt`, `WriteFmt`, etc. with arguments of its own user type *or any other type covered by `IOFMT_USER_CASES_`*, the `_Generic` arms inside that nested expansion need every user `_write_T` / `_read_T` symbol to be visible already. Two patterns work:
+If your writer calls `StrAppendFmt`, `WriteFmt`, etc. with arguments of its own user type *or any other type covered by `IOFMT_USER_CASE_`*, the `_Generic` arms inside that nested expansion need every user `_write_T` / `_read_T` symbol to be visible already. Two patterns work:
 
 ```c
 // Pattern A -- forward-declare both functions before either body.
@@ -155,7 +182,7 @@ Pattern A is the safe default once you have more than one user type.
 ## Recommended Layout: One `Io.h` / `Io.c` Pair per Project
 
 The mechanism above is per-TU, but the natural unit of organisation is the
-project: every TU that formats your types needs the same `IOFMT_USER_CASES_`
+project: every TU that formats your types needs the same `IOFMT_USER_CASE_`
 list visible, every `_write_T` / `_read_T` symbol needs to be linkable from
 those TUs, and every user type in the list needs its struct declaration in
 scope so the `_Generic` arm can mention it.
@@ -165,7 +192,7 @@ extension in a single project-internal pair:
 
 ```
 MyApp/Io.h    -- forward-declares every user type's _write_T / _read_T,
-                 defines IOFMT_USER_CASES_, then #include <Misra/Std/Io.h>
+                 defines IOFMT_USER_CASE_, then #include <Misra/Std/Io.h>
 MyApp/Io.c    -- defines the bodies for every _write_T / _read_T
 ```
 
@@ -180,7 +207,7 @@ keep them next to each type's own module, and it will compile and link.
 But maintenance gets harder fast:
 
 - **Macro drift.** Each TU that calls `WriteFmt(..., my_t)` needs
-  `IOFMT_USER_CASES_` defined with `my_t`'s arm. If one TU's hook lags
+  `IOFMT_USER_CASE_` defined with `my_t`'s arm. If one TU's hook lags
   behind, that TU silently fails to match (compile error if you're lucky,
   wrong-arm dispatch if a built-in coincidentally matches the type).
 - **Forward-declaration sprawl.** Pattern A (forward-declare every
@@ -200,16 +227,16 @@ to their data.
 
 ## Composing Across Libraries
 
-`IOFMT_USER_CASES_` is a single preprocessor symbol. If two libraries both want to publish IO-able types, the consumer's chain has to thread them together. The usual idiom is *rename-then-extend*:
+`IOFMT_USER_CASE_` is a single preprocessor symbol. If two libraries both want to publish IO-able types, the consumer's chain has to thread them together. The usual idiom is *rename-then-extend*:
 
 ```c
 // LibB/Io.h
-#include "LibA/Io.h"          // already defined IOFMT_USER_CASES_
+#include "LibA/Io.h"          // already defined IOFMT_USER_CASE_
 
-#define IOFMT_USER_CASES_PREV_ IOFMT_USER_CASES_
-#undef  IOFMT_USER_CASES_
-#define IOFMT_USER_CASES_(x, addr)            \
-    IOFMT_USER_CASES_PREV_(x, addr)           \
+#define IOFMT_USER_CASE_PREV_ IOFMT_USER_CASE_
+#undef  IOFMT_USER_CASE_
+#define IOFMT_USER_CASE_(x, addr)            \
+    IOFMT_USER_CASE_PREV_(x, addr)           \
     LibBType : TO_TYPE_SPECIFIC_IO(LibBType, addr),
 
 #include <Misra/Std/Io.h>
@@ -219,7 +246,7 @@ Each library header in the chain accepts whatever the previous one defined and e
 
 ## What You Lose vs Built-Ins
 
-| Aspect | Built-in (`i32`, `Str`, …) | User type via `IOFMT_USER_CASES_` |
+| Aspect | Built-in (`i32`, `Str`, …) | User type via `IOFMT_USER_CASE_` |
 | --- | --- | --- |
 | Call-site syntax | `WriteFmt("{}", x)` | `WriteFmt("{}", x)` (identical) |
 | Type checking | Compile-time, no `default` arm | Same |
@@ -228,11 +255,11 @@ Each library header in the chain accepts whatever the previous one defined and e
 | Spec parsing (`{:.2}` etc.) | Honored by the runtime, applied by the writer | Same `FmtInfo` reaches your writer; honoring it is your responsibility |
 | Type erasure | None | `void *` cast inside the function entry; the macro ensures the cast is correct by construction |
 
-The single cost is that the writer / reader bodies receive `void *` data (the function-pointer cast in `TO_TYPE_SPECIFIC_IO_IMPL` widens to `void *` for storage and the call site re-narrows). The narrowing back to `T *` is type-safe because the `_Generic` arm and the symbol name are bound at the same point: the only way for the wrong pointer to reach `_write_T` is if you mis-spell the type tag in `IOFMT_USER_CASES_`, which the compiler would reject anyway.
+The single cost is that the writer / reader bodies receive `void *` data (the function-pointer cast in `TO_TYPE_SPECIFIC_IO_IMPL` widens to `void *` for storage and the call site re-narrows). The narrowing back to `T *` is type-safe because the `_Generic` arm and the symbol name are bound at the same point: the only way for the wrong pointer to reach `_write_T` is if you mis-spell the type tag in `IOFMT_USER_CASE_`, which the compiler would reject anyway.
 
 ## Known Limitations
 
-- **One hook per TU.** Multiple `#define IOFMT_USER_CASES_` in the same TU is a redefinition warning unless you use the rename-extend pattern above.
+- **One hook per TU.** Multiple `#define IOFMT_USER_CASE_` in the same TU is a redefinition warning unless you use the rename-extend pattern above.
 - **No spec-string dispatch.** `WriteFmt("{Widget:.2}", x)` does not look up "Widget" anywhere; the type tag lives at the C-type level. Your writer interprets the spec freely via `FmtInfo`.
 - **Header-only.** The hook controls macro expansion; you cannot register a type from a `.c` file alone -- consumers' TUs need the macro visible.
 - **No partial implementations.** Even a write-only user type must have a `_read_T` symbol (a trivial stub that returns `i` is fine). The constraint is symbol resolution, not call coverage.

Include/Misra/Std/Io.h

@@ -245,7 +245,7 @@ Float:
 /// `TO_TYPE_SPECIFIC_IO(T, addr)`.
 ///
 /// EXAMPLE (per-TU or per-project header):
-///   #define IOFMT_USER_CASES_(x, addr)
+///   #define IOFMT_USER_CASE_(x, addr)
 ///       MyWidget : TO_TYPE_SPECIFIC_IO(MyWidget, addr),
 ///       OtherT   : TO_TYPE_SPECIFIC_IO(OtherT,   addr),
 ///   #include <Misra/Std/Io.h>
@@ -258,9 +258,21 @@ Float:
 /// See `Docs/.../extending-io-with-user-types.md` for the full guide,
 /// including the multi-library chain-extension pattern.
 ///
+/// SUCCESS: Once defined before `<Misra/Std/Io.h>` is processed in a TU,
+///          every listed type becomes an explicit `_Generic` arm in
+///          `IOFMT(x)` for that TU; subsequent `WriteFmt` / `StrReadFmt`
+///          / `FReadFmt` / `BufReadFmt` calls dispatch user values
+///          through the matching `_write_T` / `_read_T` symbols with
+///          the same compile-time selection as in-tree types.
+/// FAILURE: Cannot fail at the macro-expansion layer. Mis-typed arms or
+///          missing `_write_T` / `_read_T` symbols surface as compile or
+///          link errors at the call site; a user value whose type is
+///          not listed produces the standard `_Generic`
+///          "no matching association" diagnostic.
+///
 /// TAGS: I/O, Generic, Extension, Macro
-#ifndef IOFMT_USER_CASES_
-#    define IOFMT_USER_CASES_(x, addr) /* empty -- override before include */
+#ifndef IOFMT_USER_CASE_
+#    define IOFMT_USER_CASE_(x, addr) /* empty -- override before include */
 #endif
 
 ///
@@ -285,7 +297,7 @@ Float:
             (x),                                                                                                       \
             TypeSpecificIO: (x),                                                                                       \
             Str: TO_TYPE_SPECIFIC_IO(Str, &(x)),                                                                       \
-            IOFMT_FLOAT_CASE_(x, &(x)) IOFMT_INT_CASE_(x, &(x)) IOFMT_BITVEC_CASE_(x, &(x)) IOFMT_USER_CASES_(x, &(x)) \
+            IOFMT_FLOAT_CASE_(x, &(x)) IOFMT_INT_CASE_(x, &(x)) IOFMT_BITVEC_CASE_(x, &(x)) IOFMT_USER_CASE_(x, &(x))  \
                 Zstr: TO_TYPE_SPECIFIC_IO(Zstr, &(x)),                                                                 \
             char *: TO_TYPE_SPECIFIC_IO(Zstr, &(x)),                                                                   \
             unsigned char: TO_TYPE_SPECIFIC_IO(u8, &(x)),                                                              \
@@ -310,7 +322,7 @@ Float:
             TypeSpecificIO: (x),                                                                                       \
             Str: TO_TYPE_SPECIFIC_IO(Str, (void *)&(x)),                                                               \
             IOFMT_FLOAT_CASE_(x, (void *)&(x)) IOFMT_INT_CASE_(x, (void *)&(x)) IOFMT_BITVEC_CASE_(x, (void *)&(x))    \
-                IOFMT_USER_CASES_(x, (void *)&(x)) Zstr: TO_TYPE_SPECIFIC_IO(Zstr, (void *)&(x)),                      \
+                IOFMT_USER_CASE_(x, (void *)&(x)) Zstr: TO_TYPE_SPECIFIC_IO(Zstr, (void *)&(x)),                       \
             char *: TO_TYPE_SPECIFIC_IO(Zstr, (void *)&(x)),                                                           \
             unsigned char: TO_TYPE_SPECIFIC_IO(u8, (void *)&(x)),                                                      \
             unsigned short: TO_TYPE_SPECIFIC_IO(u16, (void *)&(x)),                                                    \