【C++三方组件】utfcpp：UTF-8 字符串处理避坑

【摘要】：一个字符串 size() 返回 9，「字符数」却是 5------中文场景的第一课：字节不是字符。utfcpp 用一个头文件给出 UTF-8 的瑞士军刀：合法性检测（GBK 字节直接拒检，实测）、字符计数、非法序列替换、按码点遍历、UTF-8/16/32 互转。Why 拆三问：为什么必须先问编码再处理字符串、解码失败时替换与抛异常两种策略怎么选、std::u32string 凭什么才是真正的「字符数组」。文末与 ICU 的轻重对照。

【关键词】：utfcpp、UTF-8、编码、码点、GBK、字符计数

【版本基准】：utfcpp 4.2.0（Boost 软件许可证）｜C++17｜文中输出均为 g++ 13.1 实测

1. What：`size()` 骗了你

std::string zh = "中文abc";------zh.size() 是 9 （中文各 3 字节 + abc），但屏幕上的字符是 5 。凡是「截前 10 个字符」「按字符数对齐」「校验用户名长度」的需求，拿 size() 当字符数用，中文场景全线失准。再狠一点的坑：把 GBK 编码的旧数据当 UTF-8 读------字没变，字节全错，下游 JSON 序列化直接非法。

utfcpp 是这类问题的最小答案：头文件 + 约 50 个 API 的 UTF-8 工具箱，检测、计数、修复、转换一应俱全。

2. 项目接入

json 复制代码

// vcpkg：vcpkg.json
{ "dependencies": [ "utfcpp" ] }

也可以直接拷 utf8.h 与 utf8/ 目录进工程------零依赖纯头文件，#include "utf8.h" 即用。

3. 核心概念：编码是字符串的隐藏协议

UTF-8 是变长编码 ：ASCII 字符 1 字节、常用汉字 3 字节（码点 U+4E2D--U+9FFF 段）、表情符号 4 字节。于是任何 char 序列都有两个身份------字节数 （size()）与字符数 （码点数），二者只在纯 ASCII 时相等。utfcpp 的 API 全部围绕「把字符数的事从字节数里解出来」：distance 数字符、is_valid 验协议、next 按码点步进、utf8to32 展开成真字符数组。

4. How：五个高频操作（实测）

核心 API 一张表（按使用频率排）：

家族	API	回答的问题
检测	`is_valid` / `find_invalid`	这串字节是合法 UTF-8 吗 / 坏在哪
计数	`distance`	到底有几个字符
修复	`replace_invalid`	脏数据清洗成合法序列
遍历	`utf8::iterator` / `next` / `peek_next`	按码点步进
互转	`utf8to16/32`、`utf16to8`、`utf32to8`	三种表示互搬

cpp## 复制代码

```cpp
#include "utf8.h"
std::string zh = "中文abc";

// 1. 字节数 vs 字符数
utf8::distance(zh.begin(), zh.end());   // 5

// 2. 合法性检测------GBK 字节当场现形
std::string gbk = "\xd6\xd0\xce\xc4";   // "中文"的 GBK 编码
utf8::is_valid(zh.begin(), zh.end());   // true
utf8::is_valid(gbk.begin(), gbk.end()); // false

// 3. 修复非法序列（替换为 '?'）
std::string fixed;
utf8::replace_invalid(gbk.begin(), gbk.end(),
                      std::back_inserter(fixed), '?');

// 4. 展开为码点数组------"真正的字符"
std::u32string u32 = utf8::utf8to32(zh);
// U+4E2D(中) U+6587(文) U+0061(a) ...

// 5. UTF-8 <-> UTF-16 互转（对接 Windows API）
std::u16string u16 = utf8::utf8to16(zh);
utf8::utf16to8(u16);                    // 原样回得来

实测输出：

text 复制代码

bytes=9 chars=5
utf8_valid=1 gbk_valid=0
fixed_bytes=4
cp0=U+4E2D cp1=U+6587 cp2=U+0061
roundtrip=1 u16len=5

第 2 行是本篇最有价值的一行：同一串汉字，UTF-8 字节合法、GBK 字节非法------不通过检测就处理，等于不看协议就解析报文。

5. Why：三个追问

① 为什么必须先问编码？ 因为「字符串」在内存里只是字节，编码是解释字节的隐藏协议------协议错了，长度、比较、切片全部失真，而且失真得悄无声息 （GBK 字节多数能「显示」出来，只是乱码）。所以处理外来数据的第一步是 is_valid 把协议问清------这与第 3 篇 RapidJSON「先判类型再取值」是同一条纪律：别对来路不明的数据做假设。

② 解码失败，替换还是抛异常？ utfcpp 给了两种姿态：replace_invalid 把非法序列换成占位符（数据清洗、容错展示）；带校验的接口（utf8::next 的 checked 版本、utf8to32 遇非法字节）抛 utf8::invalid_utf8 异常（严格协议，宁可失败不可错数据）。选择标准与第 8 篇 FlatBuffers 的 Verifier 同构：展示场景要容错，数据链路要严格。

③ std::u32string 凭什么是「真字符数组」？ 因为 UTF-32 定长四字节一码点------u32str.size() 就是字符数、下标就是第 N 个字符、「截前 10 个字符」终于有了直译。代价是内存（ASCII 场景 ×4）。日常处理留在 UTF-8（省内存、生态通用），需要按字符做算法时临时展开成 u32，做完再 utf32to8 折回去。

6. 坑与最佳实践（实测依据）

size() 永远是字节数 ------所有「按字符」的需求都得过 distance 或 u32 展开。
旧系统对接先检测 ：GBK/GB18030 数据混入是中文环境最常见的脏数据源，入口处 is_valid 一道闸（实测 GBK 必被拒）。
Windows 控制台输出中文是另一层坑（代码页问题），不在 utfcpp 职责内------下一篇 Boost.Nowide 专治这个。
utf8::iterator 适配器可以像普通迭代器一样遍历码点，但每次解引用都做解码------热路径先转 u32 再遍历。
需要完整 Unicode 规范化（NFC/NFD）、大小写映射时，utfcpp 不够------那是 ICU 的领地（§7）。

7. 选型对比

	utfcpp	ICU4C	std::codecvt
体量	一个头文件	数十 MB	标准库
定位	校验/计数/互转	完整 Unicode 规范	C++11 转码（多数实现已弃用）
依赖	零	重	零
甜区	入口检测与轻处理	本地化/排序/规范化	不建议新代码使用

一句话：入口处一个 utfcpp 挡脏数据，重本地化才请 ICU。

8. 延伸与联动

第 2 篇 nlohmann/json 的 \u4e2d 转义、第 10 篇 fmt 的字节透传立场，都预设了「内部一律 UTF-8」------本篇是这条主线的检测工具。
下一篇 Boost.Nowide 把「UTF-8 everywhere」推进到 Windows 的程序入口：argv、文件名、控制台。〔关联第 13 篇〕

参考：nemtrif/utfcpp 4.2.0（Boost 软件许可证）。文中字节/字符计数、GBK 拒检、替换与互转结果均为本机实测（g++ 13.1）。

【C++三方组件】utfcpp：UTF-8 字符串处理避坑