1. 代码开发工具里的“一个字符”不是一块字节:从一次串口输出 0 说起
把一段统计中文标点符号数量的代码贴进 Arduino IDE,编译通过、烧录成功,串口监视器却打印出 0——这种场面我在代码开发工具里见过不止一次。问题通常不在板子,而在“一个字符”的理解:String.charAt(i) 返回的是一个字节,不是一整个汉字或标点;中文标点在 UTF-8 里占三个字节,拿单字节去和标点表比,等于拿半截钥匙去开整把锁。下面按实战走一遍:先看清编码和工具链的字符模型,再写一个按 UTF-8 码点遍历的统计函数,最后把五类常见翻车现场和一组可复现的测试用例摆出来。适合正在用 Arduino 处理中文串口日志、做文本预处理,或者刚接触 String API 的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具的编码账本:UTF-8、源文件与串口监视器要对齐
2.1 编辑器、编译器、串口监视器不是同一本账
很多人以为 String.length() 返回的就是“有几个字”,这是第一个要拆掉的假设。在 Arduino 这套代码开发工具里,至少有四个环节各自记账:编辑器负责把源文件按某种编码保存;编译器把字符串字面量原样变成字节序列放进程序;String 在运行时保存的是这串字节;串口监视器只是把收到的字节按某种编码显示出来。四个环节里任何一个对不上,你看到的“字”和程序里的“字节”就不是一回事。
我一般先做一件事:不管后面要写什么统计函数,先在 setup() 里把字符串的 length() 打出来。比如肉眼看着是“你好,世界!”六个字符,length() 可能打印 18 或者更多。这不是程序算错了,而是它老老实实告诉你:我存的是字节。把这个数看清楚,后面 charAt(i) 为什么一次只取到半个符号,就很容易理解了。
这里还有一个容易被忽略的点:String 的 length() 和 charAt() 都是按字节下标工作的。charAt(0) 拿到第一个字节,charAt(1) 拿到第二个字节,它不会自动跳过整个汉字。你写 for (int i = 0; i < str.length(); i++),循环次数等于字节数,不是字符数。对于纯英文日志,这个差别不明显;一旦日志里出现中文标点,循环就会在符号中间切一刀。
2.2 UTF-8 下中文标点的三字节结构
UTF-8 是一种变长编码。常见的 ASCII 字符占一个字节,首字节落在 0x00 到 0x7F;两字节序列的首字节落在 0xC0 到 0xDF;三字节序列的首字节落在 0xE0 到 0xEF;四字节序列的首字节落在 0xF0 到 0xF7。中文标点,包括逗号、句号、感叹号、问号、分号、冒号、引号、方括号、圆括号、书名号,常见做法都落在三字节区。也就是说,一个中文标点从 charAt 里取三次才能拼完整。
| 字符类别 | UTF-8 常见字节数 | charAt 一次拿到什么 |
strchr 能不能整字符比较 |
|---|---|---|---|
| 半角 ASCII | 1 | 一个完整字符 | 能,但只能比单字节 |
| 中文汉字 | 3 | 三分之一段字节 | 不能 |
| 中文标点 | 3 | 三分之一段字节 | 不能 |
| 四字节表情等 | 4 | 四分之一段字节 | 不能 |
这张表里最关键的是第三列:charAt 不是“取第 i 个字符”,而是“取第 i 个字节”。材料里那段最小实现用 strchr(punctuation, c) 判断,strchr 的第二个参数是单字节 char,它只能在标点字符串的字节流里找一个字节。中文标点由三个字节组成,你拿其中一个字节去查,查不到完整符号;反过来,某个汉字的某个字节如果恰好和标点表里的某个字节相同,又可能被误算进去。这就是后面所有统计偏差的根。
2.3 编码自检:把 length 和 hex dump 打出来
在写统计函数之前,我建议先加一段自检代码,把字符串的字节长度和每个字节的十六进制值打到串口。它不解决业务问题,但能让你后面少猜很多次。
cpp复制#include <Arduino.h>
void dumpBytes(const String& s) {
Serial.print("len=");
Serial.println(s.length());
for (int i = 0; i < (int)s.length(); i++) {
unsigned char b = (unsigned char)s.charAt(i);
if (b < 0x10) {
Serial.print('0'); // 补前导零,保证每字节两位
}
Serial.print(b, HEX);
Serial.print(' ');
}
Serial.println();
}
逻辑说明:s.length() 打印的是字节数;循环用 charAt(i) 逐字节取出,强制转换成 unsigned char 后再按十六进制输出;b < 0x10 时补一个 0,避免出现 A 这种一位十六进制,读起来对齐。参数说明:Serial.begin(9600) 要和串口监视器右下角的波特率一致;这里没有把 0x 前缀打出来,看到 EF BC 8C 这样的三字节组,就是典型的三字节 UTF-8 序列。
自检时重点看两件事。第一,len 和你肉眼数的字符数是否差了三倍左右;如果差得不多,反而要怀疑源文件不是 UTF-8 保存的,后面按三字节切分的假设会直接失效。第二,看首字节是否落在 0xE0 到 0xEF 之间,后续字节是否落在 0x80 到 0xBF 之间。只要这个结构对得上,后面按码点遍历才有意义。把这段自检放在 setup() 里,先跑一次,再动统计函数,比直接烧录猜问题要省时间。
3. 在代码开发工具里写统计函数:按 UTF-8 码点遍历而不是按 charAt 下标
3.1 标点集合怎么存:从一个大字符串改成数组
材料里的写法是把标点集中放在一个字符串里:
cpp复制const char* punctuation = ",。!?;:“”‘’【】()《》";
这个写法本身没错,字符集中、一眼能看全。问题出在查询方式:配合 strchr 使用时,它只能按字节查找,没法告诉你“我匹配到的是不是一个完整的中文标点”。我一般会把它改成数组,每个元素放一个完整符号,后面用 strcmp 做整串比较。
cpp复制const char* PUNCT[] = {
",", "。", "!", "?", ";", ":",
"“", "”", "‘", "’", "【", "】",
"(", ")", "《", "》"
};
逻辑说明:数组里每个元素都是一个完整的 UTF-8 字符串,长度固定为三字节加结尾的 '\0';统计时把候选的三字节片段拷进一个固定缓冲区,再和数组元素逐个 strcmp,相等才计数。参数说明:数组长度用 sizeof(PUNCT) / sizeof(PUNCT[0]) 计算,增删符号时不用同步改循环上限;源文件必须保持 UTF-8 保存,否则数组元素本身的字节就变了,后面怎么比都不对。
改成数组还有两个实际好处。第一,漏符号时容易发现:一行一个,扫一眼就知道少没少。第二,方便后面加测试用例:每个符号都能单独构造一条输入,不用在一长串里找位置。材料里的字符串适合“展示有哪些标点”,数组适合“程序逐个比对”,两者用途不一样。
3.2 为什么逐字节 strchr 会翻车
先把材料里的最小实现单独拿出来看。它能编译,在纯 ASCII 字符串上也能跑,但遇到中文标点就会出问题。
cpp复制int countByByte(const String& str) {
const char* punctuation = ",。!?;:“”‘’【】()《》";
int count = 0;
for (int i = 0; i < (int)str.length(); i++) {
char c = str.charAt(i);
if (strchr(punctuation, c) != NULL) {
count++;
}
}
return count;
}
逻辑说明:循环上限是 str.length(),也就是字节数;charAt(i) 每次取一个字节;strchr 在 punctuation 的字节流里查找这个单字节。参数说明:strchr 的第二个参数是 int,但实际按单字节字符处理,它不认识三字节的中文标点;str.length() 不是字符数,这两个事实叠在一起,结果就是“要么一个都数不到,要么把汉字的一部分数进去”。
我实际遇到的现象是串口打印 0。原因不复杂:中文标点的三个字节里,任何一个单独拿出来都不等于完整的标点字符串,strchr 找不到,计数自然不动。另一个反向现象是数字偏大:某些汉字的 UTF-8 字节序列里含有和标点表相同的单字节,strchr 一查到就加一,于是汉字被当成标点。两种现象根子相同,都是“拿字节当字符”。
3.3 按 UTF-8 码点遍历的统计函数
正式版本我写成“先判断首字节长度,再按长度跳步,三字节时取完整片段比对”。代码不长,但每一步都有原因。
cpp复制#include <Arduino.h>
#include <string.h>
// 根据 UTF-8 首字节判断这个码点占几个字节
int utf8Len(unsigned char lead) {
if (lead < 0x80) return 1; // ASCII
if ((lead & 0xE0) == 0xC0) return 2; // 两字节
if ((lead & 0xF0) == 0xE0) return 3; // 三字节,中文标点在这里
if ((lead & 0xF8) == 0xF0) return 4; // 四字节
return 1; // 非法首字节按 1 字节跳,避免死循环
}
int countChinesePunctuation(const String& str) {
int count = 0;
int i = 0;
int n = (int)str.length();
while (i < n) {
unsigned char lead = (unsigned char)str.charAt(i);
int len = utf8Len(lead);
if (len == 3 && i + 2 < n) {
char buf[4];
buf[0] = str.charAt(i);
buf[1] = str.charAt(i + 1);
buf[2] = str.charAt(i + 2);
buf[3] = '\0';
for (unsigned k = 0; k < sizeof(PUNCT) / sizeof(PUNCT[0]); k++) {
if (strcmp(buf, PUNCT[k]) == 0) {
count++;
break;
}
}
}
i += len; // 按整个码点前进,不按字节前进
}
return count;
}
逻辑说明:utf8Len 只看首字节,判断当前码点该跨几步;while 循环里先取首字节,算出 len,只有 len == 3 时才尝试拼出三字节候选;buf 是固定四字节缓冲,第三位放 '\0',避免 strcmp 读到缓冲区外;strcmp 相等才计数,并且 break 跳出内层循环,防止同一个符号被重复匹配。参数说明:lead 必须转成 unsigned char,否则高位字节在带符号 char 上可能变成负数,位运算判断会出错;i + 2 < n 是边界保护,最后剩下的一两个不完整字节直接跳过,不计数也不越界;i += len 是关键,遇到两字节、三字节、四字节都能整段跳过,不会在符号中间切一刀。
这里我特意没有用 str.substring(i, i + 3) 去取片段。substring 会创建临时 String,在循环里反复调用会往堆上不断申请和释放小块内存,跑久了容易出现内存碎片。固定 char buf[4] 不涉及动态分配,逻辑也更直白。这个取舍在短字符串上不明显,但在持续接收串口日志的场景里,差别会慢慢显出来。
3.4 接到 setup 里输出并核对预期
函数写完后,先别急着塞进业务逻辑,用材料里那条示例字符串跑一遍。setup() 里保留字节长度打印,再打印统计结果。
cpp复制void setup() {
Serial.begin(9600);
String s = "这是一个包含中文标点符号的字符串:,。!?;:“”‘’【】()《》";
Serial.print("字节长度=");
Serial.println(s.length());
Serial.print("中文标点符号的数量为:");
Serial.println(countChinesePunctuation(s));
}
void loop() {
// 空
}
逻辑说明:Serial.begin(9600) 打开串口,波特率和监视器保持一致;先打印 length(),确认这串文本的字节规模;再调用统计函数,把结果打到下一行。参数说明:示例串里冒号出现两次,其余符号各一次,按 16 个符号的集合逐个核对,预期结果是 17。如果打印出 0,先回去看 2.3 的 hex dump;如果打印出明显大于 17 的数,重点查标点数组里是不是混进了单字节符号,或者循环步进写成了 i++。
核对预期时不要只看最后那个数字。把 字节长度 和 中文标点符号的数量为 两行一起看:字节长度对得上、数量对不上,问题在比对逻辑;两个都对不上,问题在源文件编码或字符串本身。这个顺序能帮你少走很多弯路。
4. 代码开发工具的避坑清单:五类翻车现场与排查顺序
4.1 现象:串口打印 0,一个标点都没数到
原因:charAt 按字节返回,strchr 按单字节查找,中文标点却是三字节序列。三个字节各自都不等于完整标点,查找自然全部落空。这是材料里最小实现最典型的翻车方式,尤其在示例串全是中文标点时,结果直接是 0,很容易让人误判成板子或串口坏了。
解决:不要用 strchr 查中文标点。按 3.3 的做法,先用 utf8Len 判断首字节长度,三字节时拼出 buf,再用 strcmp 和标点数组整串比较。排查时先打印 length(),确认循环上限是字节数;再打印 hex dump,确认每个中文标点确实是 E? 开头的三字节组。两步都对,再改比对逻辑。
4.2 现象:数字比预期大,汉字被算成了标点
原因:还是单字节比对,但方向反过来了。某些汉字的 UTF-8 字节序列里含有和标点表相同的单字节,strchr 一查到就加一。比如一段原本只有两个标点的文本,统计结果多出几个,往往就是汉字贡献的“假阳性”。这种偏差不像 0 那么扎眼,但会把后面的判断带偏。
解决:把“按字节查找”改成“按码点取整串比较”。buf 里必须放完整的三字节,strcmp 必须比较完整字符串,不能拿 buf[0] 去查表。另外,标点数组里只放全角中文标点,不要混入半角逗号、半角感叹号;混进去以后,英文日志里的半角符号也会被统计,边界会变得模糊。半角要不要算,是业务规则,不是编码问题,规则要先定死。
4.3 现象:跑一会儿板子重启,或者统计结果开始飘
原因:循环里用了 String 的 substring、concat 之类会动态分配内存的接口。Arduino 的 String 在堆上申请空间,反复创建临时对象容易产生碎片;碎片积累到一定程度,下一次申请失败,表现可能是重启,也可能是某个变量被踩后结果不稳定。这种问题在短测试里不容易复现,接上持续串口日志后才会露头。
解决:统计函数内部不要创建临时 String。取三字节片段用固定 char buf[4],比较用 strcmp;如果输入本身是 const char*,直接用 strlen 和下标遍历,连 String 都不需要。确实要保留 String 入参时,用 const String& 避免拷贝。把“循环内不动态分配”当成一条硬规矩,比事后查内存碎片省事得多。
4.4 现象:串口监视器里中文乱码,统计数字却“看起来对”
原因:乱码不一定影响计数,但会影响你核对预期。常见来源有三个:源文件保存编码不是 UTF-8;串口监视器波特率和 Serial.begin() 不一致;复制粘贴过程中字符串被转成了别的编码。三个来源里任意一个出问题,你看到的“字”和程序里的字节就对不上,人工核对预期时很容易把对的当成错的。
解决:先把源文件统一按 UTF-8 保存,再确认 Serial.begin(9600) 和监视器右下角波特率一致。改完编码后重新编译、重新烧录,不要只按复位键。然后用 2.3 的 hex dump 看首字节结构,E? 开头、后续 8? 到 B? 的三字节组才是正常的中文标点。乱码修好之前,不要拿肉眼看到的字符数去推预期值。
4.5 现象:总数总是少一,其他都对
原因:标点集合漏了符号,或者全角、半角混用。材料里的标点字符串是手写的,手写集合最容易在增删时漏掉一个;如果某个符号在源文件里被输入法写成了半角版本,数组里放的是全角,比对时自然不相等。少一这种偏差很隐蔽,因为其他符号都正常,只有那一个不计数。
解决:把标点集合改成一行一个的数组,增删时肉眼可数;再给每个符号单独准备一条测试输入,跑一遍全量自检。第 5 章会给一组用例,其中就包括“半角标点不算”的边界。排查顺序我一般固定为:先看 length(),再看 hex dump,再看标点数组,最后看内存分配。按这个顺序走,大部分问题在第二步就能定位。
5. 用代码开发工具做回归:一组可复现的标点测试用例
5.1 一组能复现的用例
函数改完后,不要只跑材料里那一条示例串。下面这几条覆盖了空串、纯 ASCII、纯中文、混合标点和半角边界,可以直接抄进 setup() 逐条跑。
| 输入 | 预期 | 检查点 |
|---|---|---|
"" |
0 | 循环不进入,不越界 |
"abc, def!" |
0 | 半角逗号、感叹号不在集合 |
"你好世界" |
0 | 汉字不能被误判成标点 |
| 材料示例串 | 17 | 16 个符号,冒号出现两次 |
"你好,世界!" |
2 | 全角逗号、感叹号各一个 |
这张表里最值得保留的是第二行和第三行:一个验证“半角不算”,一个验证“汉字不误判”。很多统计偏差不是出在中文标点上,而是出在这两个边界上。把预期值写死,后面改标点数组时才有对照。
5.2 把自检挂到 setup 里
我一般写一个很小的 runCase,把实际值和人工核对值一起打出来,省得每次拿眼睛比对。
cpp复制void runCase(const String& s, int expect) {
int got = countChinesePunctuation(s);
Serial.print(got == expect ? "PASS" : "FAIL");
Serial.print(" expect=");
Serial.print(expect);
Serial.print(" got=");
Serial.println(got);
}
void setup() {
Serial.begin(9600);
runCase("", 0);
runCase("abc, def!", 0);
runCase("你好世界", 0);
runCase("这是一个包含中文标点符号的字符串:,。!?;:“”‘’【】()《》", 17);
runCase("你好,世界!", 2);
}
逻辑说明:runCase 只做一件事——调用统计函数,把实际结果和预期结果并排打印;got == expect 决定输出 PASS 还是 FAIL。参数说明:第二个参数 expect 是人工核对后的固定值,不要从函数结果反推;const String& 避免传参拷贝;波特率仍然保持 9600。每次改标点数组或改遍历逻辑,先把这几条跑一遍,再看业务日志。
从那以后我每次在 Arduino 里处理中文字符串,都先打印一遍 length() 和字节 dump,再写统计函数,最后用固定用例跑一遍自检。这个
