更多 C++ 文章见《修远之路（C++集萃）》专栏
cppcodec 是一个基于 CRTP 静态多态 + 编译期查表策略的 Header-Only 编解码框架，统一封装 Base16/Hex、Base32、Base64 三族算法的多种 RFC 变体。
通过编译期生成 256 项查表 + CRTP 静态分派 + SFINAE 容器适配，cppcodec 提供一个"接口统一、零依赖、编译期安全"的编解码库。其核心能力矩阵：
| 能力 | 适用场景 | 不适用场景 |
|---|---|---|
| Base64 RFC4648 / URL-safe 编解码 | JWT、MIME、Data URI | 需流式（streaming）增量编解码 |
| Base32 RFC4648 / Crockford / Hex 编解码 | 人工可读标识符、短链接 | 大文件分块编解码 |
| Hex (Upper/Lower) 编解码 | 十六进制摘要、MAC 地址 | 需要奇数长度半字节处理 |
| 自定义容器结果输出 | 嵌入式环境零堆分配 | 需要运行时动态切换编解码算法 |
整体架构与流程
核心模块职责：
| 模块 | 核心职责 | 输入→输出 |
|---|---|---|
codec<CodecImpl> | 统一公共 API，管理缓冲区生命周期 | 原始字节/字符串 → 编码结果 |
stream_codec<Codec, Variant> | Block/Tail 编解码调度，Padding 生成/校验 | 字节流 → 字母索引流 → 编码字符 |
base64/base32/hex | 特定算法的位打包/解包逻辑 | 二进制块 ↔ 字母索引数组 |
CodecVariant(Policy) | 字母表定义、Padding 规则、规范化策略 | 索引↔字符映射 |
data::access | 容器无关的读写适配 | 任意容器 ↔ 统一put/init/finish |
执行时序
编码流程（Encode）
解码流程（Decode）
解码需要对输入数据流进行严格的状态校验（包括非字母表字符检测、Padding 位置与数量校验）。
底层原理与设计
抽象与机制
状态映射表
解码性能瓶颈在于 —— 将输入字符映射为字母表索引：
- 传统实现使用
switch-case或strchr，每次解码一个字符需要 O(AlphabetSize) 次比较 - cppcodec 利用
constexpr在编译期生成一张 256 项的查找表，覆盖所有可能的char值。
查表项并不只存储普通的索引值，其内部通过特定的编译期常数来标示字符的语义状态：
| 返回值范围 | 语义状态 | 详细说明 |
|---|---|---|
| 0 - 63 | 有效索引 | 表示该字符是合法的 Base64 字符。返回值即为该字符对应的 6-bit 二进制数值（例如 ‘A’->0, ‘B’->1 … ‘/’->63）。 |
| 特定负值/标记 | Padding (填充) | 对应代码中的stream_codec::is_padding。表示遇到了填充字符（通常是=）。读取到此状态时，需要停止常规拼接并进行末尾处理。 |
| 特定负值/标记 | Invalid (非法) | 对应代码中的stream_codec::is_invalid。表示该字符完全不在 Base64 的字母表内（比如空格、换行或其他特殊符号）。解码器应报错或直接跳过。 |
实现路径为：index_if_in_alphabet通过模板递归在编译期遍历字母表构建逆映射，make_lookup_table利用参数包展开生成lookup_table_t<256>数组；解码时单次数组下标访问即完成字符状态转换。
CRTP 静态多态
类层次为：
codec<CodecImpl> ← 公共 API 层 └─ CodecImpl = stream_codec<Codec, Variant> ← 调度层 └─ Codec = base64/base32/hex ← 算法层 └─ Variant = base64_rfc4648/... ← 策略层codec<CodecImpl>通过CodecImpl::encode()/CodecImpl::decode()静态调用子类实现，避免了virtual函数的间接跳转开销。所有调用在编译期确定，编译器可内联整个调用链。
模板递归展开
enc<N>模板通过递归特化将编码循环展开为编译期确定的连续函数调用序列。例如 Base64 的enc<4>::block展开为：
enc<4> → enc<3> → enc<2> → enc<1> → enc<0> (终止)每次递归调用Codec::index<I>(src)提取一组 bit 并通过CodecVariant::symbol()映射为字符。编译器将此展开为无循环、无分支的直线代码（straight-line code），配合CPPCODEC_ALWAYS_INLINE强制内联属性，实现零开销抽象。
SFINAE 容器适配
data::access模块利用探测手法（Detection Idiom）和重载决议优先级，在编译期检测结果容器的底层 API 能力，从而自动选择最优写入策略。其核心原理是定义具有不同泛型优先级的重载函数：
C++
// 伪代码示例：重载决议优先级标志template<size_t I>structpriority_tag:priority_tag<I-1>{};template<>structpriority_tag<0>{};// 路径 1：高优先级，探测容器是否具有连续可写的 data() 指针和 size()template<typenameT>autocreate_state_impl(T&c,priority_tag<2>)->direct_data_access_result_state<...>;
