Roc 语言 U8.from_str 解析失败语义:从 REPL 快照测试到 BadNumStr 底层实现
Roc 语言 U8.from_str 解析失败语义:从 REPL 快照测试到 BadNumStr 底层实现
本文围绕 Roc 仓库中 num_from_str_u8_failure.md 这一 REPL 快照测试,系统讲解 U8.from_str 在遇到越界数值、负数、非法字符、空串、小数格式等输入时统一返回 Err(BadNumStr) 的失败语义,并深入到 src/build/roc/Builtin.roc 中的公开 API 定义与 src/builtins/num.zig 中的 Zig 运行时解析实现,帮助读者理解 Roc 整数字符串解析的完整调用链,并掌握在 REPL 中验证类型转换错误行为的测试方法。
快照测试文档的结构与定位
该文档是 Roc 编译器测试套件中的一份 REPL 快照(snapshot),位于 test/snapshots/repl/ 目录下。这类文件以 # META、# SOURCE、# OUTPUT、# PROBLEMS 四个区块组织,完整记录了一次 REPL 会话的输入与期望输出,起到"可执行文档"的作用——既可作为测试用例驱动编译器验证,也可作为开发者理解语言行为的参考手册。
该文档的 META 区块声明如下:
description=U8.from_str failure cases
type=repl
其中 description 概括了本快照的测试主题——U8.from_str 的失败(failure)用例;type=repl 指明这是一份 REPL 会话快照,即以下 # SOURCE 中每一行以 » 开头的表达式都会在交互式 REPL 中逐条求值。
U8.from_str 的公开 API 与返回值语义
在 Roc 内置模块定义 src/build/roc/Builtin.roc 中,U8.from_str 的类型签名是:
from_str : Str -> Try(U8, [BadNumStr])
其文档注释明确指出:from_str 用于从字符串解析 U8 值,当字符串无法被解析为合法的 U8 时返回 Err(BadNumStr)。BadNumStr 是 Roc 内建错误标签(tag),专门用于表示"字符串不是合法的数字"这一失败情形。
值得区分的是,同模块中还定义了另一个入口 from_numeral:
from_numeral : Numeral -> Try(U8, [InvalidNumeral(Str)])
from_numeral = |numeral| from_numeral_with(numeral, |str| u8_from_str(str))
文档注释明确说明:from_numeral 是编译器在数字字面量被赋予 U8 类型时使用的钩子,普通业务代码解析用户输入应优先使用 U8.from_str。这一区分体现了 Roc 对"字面量常量"与"运行时用户文本"两种解析场景的分工:字面量由编译期处理,而 from_str 面向运行时输入。
从源码结构还可以看到,U8.from_str 并非特例——i8_from_str、u16_from_str、i16_from_str、u32_from_str 等一整套整型解析函数(见 src/build/roc/Builtin.roc)都遵循相同的 Str -> Try(类型, [BadNumStr]) 签名,失败语义保持一致。
五个失败用例逐条剖析
快照的 # SOURCE 区块共包含五条 REPL 输入,# OUTPUT 显示它们全部求值为 Err(BadNumStr)。下面结合 U8 类型本身的取值范围(0 到 255,文档注释中明确给出)逐一分析每种失败原因:
1. 数值越界:U8.from_str("256")
» U8.from_str("256")
Err(BadNumStr)
256 超出了 U8 可表示的最大值 255,属于溢出(overflow)。字符串本身是完全合法的十进制数字,但无法放入 8 位无符号整数,因此解析失败。这是文档注释中 0 到 255 范围约束的直接体现。
2. 符号与无符号冲突:U8.from_str("-1")
» U8.from_str("-1")
Err(BadNumStr)
-1 是合法数字字符串,但 U8 是无符号类型,负号在数学上无法映射到任何 U8 值。注意这与 I8.from_str("-1") 的成功行为形成对比——带符号类型(如 I8)允许负数,而无符号类型遇到负号一律报错。
3. 非法字符:U8.from_str("hello")
» U8.from_str("hello")
Err(BadNumStr)
"hello" 不包含任何数字字符,属于非法输入(invalid character)。Roc 的整数解析不允许任何非数字字符混入(不包含隐式忽略空白或字母的处理),因此直接失败。
4. 空字符串:U8.from_str("")
» U8.from_str("")
Err(BadNumStr)
空字符串没有任何数字可供解析。从底层实现看,空输入会在解析入口处即被判定为非法字符(详见下文 parseIntNoFmt 对 bytes.len == 0 的处理),而不是被解释为 0——这一点对于处理用户留空的表单输入等场景非常关键。
5. 小数格式:U8.from_str("12.5")
» U8.from_str("12.5")
Err(BadNumStr)
"12.5" 虽然包含合法数字,但含小数点,是小数而非整数。from_str 只接受整数字面量语法,小数点属于非法字符。想要解析小数应使用 Dec.from_str 等浮点/十进制类型对应的解析函数。
小结
| 输入 | 失败原因 | 结果 |
|---|---|---|
"256" |
超出 U8 上限 255(溢出) | Err(BadNumStr) |
"-1" |
无符号类型不允许负号 | Err(BadNumStr) |
"hello" |
非法字符 | Err(BadNumStr) |
"" |
空字符串 | Err(BadNumStr) |
"12.5" |
小数格式,非整数 | Err(BadNumStr) |
底层实现:Zig 运行时的整数解析
U8.from_str 在编译后最终落到 Zig 运行时 src/builtins/num.zig 的 parseIntFromStr:
pub fn parseIntFromStr(comptime T: type, buf: RocStr) NumParseResult(T) {
const bytes = buf.asSlice();
const parsed = if (hasExplicitRadix(bytes))
parseIntNoFmt(T, bytes)
else if (decimal_parse.parseInt(T, bytes)) |value|
value
else
error.InvalidCharacter;
if (parsed) |success| {
return .{ .errorcode = 0, .value = success };
} else |_| {
return .{ .errorcode = 1, .value = 0 };
}
}
可以看到两条解析路径:带显式进制前缀(0x/0b/0o,由 hasExplicitRadix 检测,见 num.zig)时走 parseIntNoFmt,否则走十进制专用解析器 decimal_parse.parseInt。无论哪条路径,一旦失败都会映射为错误码 1,最终由 Roc 侧包装为 Err(BadNumStr)。
parseIntNoFmt(见 num.zig)的细节与快照中的五个失败用例一一对应:
- 空串检查:
if (bytes.len == 0) return error.InvalidCharacter;——对应from_str("")的失败; - 符号处理:允许
-/+前缀,但无符号分支中if (negative and magnitude != 0) return error.Overflow;——对应from_str("-1")的失败; - 溢出检查:通过
parseMagnitude以目标类型上限(std.math.maxInt(T))为阈值累加,超出即溢出——对应from_str("256")的失败; - 按基数逐字符解析:非法字符直接返回
InvalidCharacter——对应from_str("hello")与from_str("12.5")中小数点导致的失败。
这种"全部失败情形统一折叠为 BadNumStr"的设计,使得调用方只需匹配一个错误标签即可处理所有解析异常,例如:
when U8.from_str(raw_input) is
Ok(value) -> value
Err(BadNumStr) -> 0 # 兜底默认值
成功路径与边界对比
快照只覆盖失败用例,但 U8.from_str 的文档注释(Builtin.roc)给出了成功路径与失败路径的对照示例:
expect U8.from_str("42") == Ok(42)
expect U8.from_str("-1") == Err(BadNumStr)
"42" 在 0~255 范围内,解析成功并包装为 Ok(42);"-1" 则是本文快照中已覆盖的失败用例。两相对照即可勾勒出完整语义:输入必须是可被精确解析为 0~255 整数的十进制(或带 0x/0b/0o 前缀的)数字字符串,否则一律 Err(BadNumStr)。此外,同目录下的其他整型快照(如 I8.from_str 对应测试)可进一步印证带符号类型的差异化行为。
快照测试的作用与扩展方式
type=repl 快照是 Roc 编译器回归测试体系的一部分:# SOURCE 中的表达式在 REPL 中求值,# OUTPUT 声明期望输出,# PROBLEMS 区块为 NIL 表示该快照当前无已知问题、不期望出现任何编译警告或错误。这类快照的价值在于:
- 回归守护:任何未来改动若导致
U8.from_str失败行为变化(例如"-1"被意外解析成功、空串被解析为0),快照比对都会立即失败; - 行为文档:以可执行的、确定性的方式记录了错误语义,比纯文字描述更精确;
- 可复制验证:读者在本地构建 Roc 后,在 REPL 中逐条输入快照中的表达式,即可复现完全一致的输出。
总结
通过这份 REPL 快照,可以完整掌握 Roc 中 U8.from_str 的解析失败语义:越界("256")、无符号负号("-1")、非法字符("hello")、空串("")与小数格式("12.5")五种典型非法输入统一返回 Err(BadNumStr),其背后是 num.zig 中空串预检、符号判定、基数检测与上限溢出检查的层层把关。理解这套语义,对编写健壮的输入校验逻辑、理解 Roc 的 Try 错误处理模型以及为编译器贡献新的解析测试都很有帮助。