codec

HEX Codec

codec_hex 是任意字节与十六进制文本之间的最小编码层，只依赖 core。启用：

基础 API xrtHexEncode / xrtHexDecode 采用统一的查询与写入契约：output == NULL && capacity == 0 只校验并返回所需长度；编码目标容量必须额外包含末尾零，解码目标是任意二进制，不要求哨兵。两者都不分配内存，允许输出与输入从同一地址开始，其他部分重叠被拒绝。所有显式指针范围会在读取前检查地址回绕；容量不足时，别名检查只覆盖调用方声明的输出容量，因此缓冲区之后的独立长度字段仍能接收精确需求值。

编码默认使用小写 a-f，XHEX_UPPER 改用大写。解码同时接受大小写，默认严格拒绝任何非 HEX 字符和奇数个数字；XHEX_IGNORE_SPACE 可显式忽略 SP、HT、VT、FF、CR、LF，适合读取分行或分组后的展示文本。编码器拒绝解码专用标志，解码器也拒绝编码专用标志。

旧版 lib/string.h 的 HEX 资产已迁移到该层：显式零长度不再触发 strlen，编码长度先检查溢出，解码先完整验证再写入，失败不会发布半个结果。

Base64 Codec

codec_base64 是字符串、PEM、WebSocket、HTTP 认证、XID 与序列化模块共用的基础编码层。它只依赖 core，不与字符串对象或网络对象绑定。启用：

xbase64config 的零初始化值表示 RFC 4648 标准字母表、规范 = 填充和严格输入：

• XBASE64_URL：使用 URL-safe 的 -、_ 字母表。
• XBASE64_NO_PADDING：编码不写 =，解码严格拒绝 =。
• XBASE64_IGNORE_SPACE：解码时忽略 RFC 7468 定义的 SP、HT、VT、FF、CR 和 LF，供 PEM/MIME 使用；编码器拒绝该标志。
• XBASE64_OPTIONAL_PADDING：编码仍写规范填充，解码同时接受完整、部分或缺失的末尾填充；不能与 XBASE64_NO_PADDING 同时使用。
• Alphabet：可选的 64 字符自定义可见 ASCII 字母表。字符必须唯一且不能包含 =；不能与 XBASE64_URL 同时使用。

解码器严格拒绝：非末尾填充、超过两个填充或不匹配的填充数量；非规范的末尾残余位；不属于字母表的字符；默认模式下的空白或无填充文本；无填充模式下长度余一的文本。

Percent Codec

codec_percent 是 URI 字节转义的纯编解码层。它不解析 URL，不拆 Query，也不实现 application/x-www-form-urlencoded 的加号规则，因此这些上层协议可以独立裁剪并共用同一个基础实现。启用：

编码器始终直接保留 RFC 3986 unreserved 字节 ALPHA / DIGIT / "-" / "." / "_" / "~"，其他字节使用大写 %HH。extraSafe 可按 URL 组件额外保留 reserved 字符：path segment 用空集合；完整 path 可传 /；已知结构安全的 authority 子层可传 :@。%、空白、控制字符、反斜杠和非 ASCII 字节不能声明为安全字符。

解码器接受大小写十六进制数字，并严格要求每个 % 后紧跟两个十六进制数字。它只负责 percent 语法，不把 + 转换为空格；后者只属于 form-urlencoded。

示例与测试

• examples/codec/hex/main.c / tests/codec/test_hex*.c
• examples/codec/base64/main.c / tests/codec/test_base64*.c
• examples/codec/percent/main.c / tests/codec/test_percent*.c
• examples/codec/tour/main.c —— 三族缓冲版与流式族巡览

测试覆盖 RFC 4648 向量、URL-safe、自定义字母表、PEM 空白、无填充、原地编解码、格式原子性、长度溢出、6000 组确定性变异、无分配路径与 OOM。