Roc 语言 List.replace 越界语义与 REPL 快照测试:从 Err(OutOfBounds) 到快照工具链
Roc 语言 List.replace 越界语义与 REPL 快照测试:从 Err(OutOfBounds) 到快照工具链
Roc 是一门快速、友好、函数式的语言。本文以仓库快照测试 test/snapshots/repl/list_replace_oob.md 为线索,剖析 List.replace 在越界索引下的返回语义——Err(OutOfBounds),并深入讲解 Roc 编译器 REPL 快照测试的文件格式、运行方式与底层实现,帮助读者掌握"如何通过快照验证标准库边界行为"的完整方法论。
快照文件在说什么:一个越界场景的完整断言
test/snapshots/repl/list_replace_oob.md 是一份类型为 repl 的编译器快照测试,全文只有四个小节,却完整描述了一个可复现的 REPL 行为:
# META
~~~ini
description=List.replace on out-of-bounds index returns Err(OutOfBounds)
type=repl
~~~
# SOURCE
~~~roc
» List.replace([10, 20, 30], 5, 99)
~~~
# OUTPUT
Err(OutOfBounds)
# PROBLEMS
NIL
逐段解读其语义:
- META 段:声明该快照的描述信息与测试类型。
type=repl表示这是针对 REPL 求值的快照,而非普通的编译诊断快照(后者通常为file、snippet、expr等类型,见 test/snapshots/README.md)。 - SOURCE 段:以
»开头的行是 REPL 提示符输入。此处向 REPL 提交表达式List.replace([10, 20, 30], 5, 99)——对长度为 3 的列表,在索引 5 处替换元素。 - OUTPUT 段:REPL 求值后输出的结果。本快照断言输出为
Err(OutOfBounds),即越界替换不产生部分结果,而是通过Err携带的OutOfBounds标签显式报告失败。 - PROBLEMS 段:
NIL表示编译过程没有产生任何诊断报告(severity、source regions 等均为空)。这一点非常关键:List.replace越界不是编译期错误,而是合法的运行期错误值,类型检查器与求值器全程无告警地完成了求值。
与之对照,仓库中的姊妹快照 list_replace.md 验证了界内场景:List.replace([10, 20, 30], 1, 99) 输出 Ok({ list: [10.0, 99.0, 30.0], prev: 20.0 })——注意 REPL 求值器在本版本中将数值渲染为浮点形式,且成功路径会同时返回更新后的列表与被替换掉的旧值。
List.replace 的真实签名与实现:Try 类型与边界检查
快照断言的背后是标准库的真实实现。List.replace 定义在 src/build/roc/Builtin.roc 中:
## Replaces the item at the given index, returning both the updated list
## and the value that was replaced.
## ```roc
## expect [10, 20, 30].replace(1, 99) == Ok({ list: [10, 99, 30], prev: 20 })
## expect [10, 20, 30].replace(5, 99) == Err(OutOfBounds)
## ```
replace : List(a), U64, a -> Try({ list : List(a), prev : a }, [OutOfBounds, ..])
replace = |list, index, new_value|
if index < List.len(list) {
Ok(list_replace_unsafe(list, index, new_value))
} else {
Err(OutOfBounds)
}
从源码可以提炼出三个值得注意的实现事实:
- 索引类型是
U64:List.replace只接受无符号 64 位整数作为索引,因此"负索引"在类型层面就被拒绝,唯一需要处理的越界方向是"索引不小于列表长度"。 - 失败路径通过
Try类型表达:返回类型为Try({ list : List(a), prev : a }, [OutOfBounds, ..]),其中..是开放标签,意味着调用方可以在错误标签上追加自己的变体。界内时返回Ok包裹的记录(含list与prev两个字段),越界时返回Err(OutOfBounds)——快照断言正是针对这一分支。 - 边界检查与不安全操作分离:
replace先做index < List.len(list)的显式检查,通过后才调用list_replace_unsafe执行底层替换。换句话说,OutOfBounds是语言层面主动兜底的错误值,而不是底层内存越界产生的未定义行为——这正是快照能稳定断言Err(OutOfBounds)的前提。
同类函数的边界语义一致性
List.replace 的越界处理并非孤例。在 Builtin.roc 同一区域,标准库的索引类函数遵循完全一致的约定:
set:List(a), U64, a -> Try(List(a), <a href="https://link.gitcode.com/i/84e093f96b6d95ec402e507b343ed618" target="_blank">OutOfBounds, ..]),越界返回Err(OutOfBounds),对应快照 [list_set_oob.md;update:先检查越界,再通过list_map_prepare_reuse等复用机制就地更新;swap:Try(List(a), [OutOfBounds, ..]),同样在越界时返回Err(OutOfBounds);get_wrap则是例外——它取模回绕(index % len),空列表才返回Err(ListWasEmpty)。
这种"显式边界检查 + Err(OutOfBounds)"的模式,让标准库在 REPL 与编译两种环境下对越界行为给出完全一致、可预测的结果,也正是 REPL 快照能够覆盖并锁定这些边界语义的原因。
快照测试体系:如何运行与更新这类断言
type=repl 快照属于仓库快照测试体系的一部分。根据 test/snapshots/README.md 的说明,快照通过捕获编译各阶段(tokenization、解析、canonicalization、类型检查乃至 REPL 求值)的输出来验证编译器行为,防止行为意外回归。
常用命令如下(需使用 Zig 构建):
# 生成/校验全部快照
zig build run-snapshot-tool
# 仅更新指定快照(例如本文讨论的越界用例)
zig build run-snapshot-tool -- test/snapshots/repl/list_replace_oob.md
# 用当前实际输出覆盖快照中的期望值(谨慎使用,用于确认行为变更符合预期)
zig build run-snapshot-tool -- test/snapshots/repl/list_replace_oob.md --update-expected
# 调试 REPL 求值过程,输出解释器 trace
zig build run-snapshot-tool -- test/snapshots/repl/list_replace_oob.md --trace-eval
需要特别说明两点:
--trace-eval只对type=repl快照有效,且只能作用于单个快照文件;trace 输出在 debug 构建下默认启用,release 构建需通过-Dtrace-eval=true打开。- 当
OUTPUT与 REPL 实际求值结果不一致时,快照测试即失败,从而在改动求值器、类型检查或标准库实现时,第一时间暴露对Err(OutOfBounds)这类边界行为的破坏。
如何为你的场景扩展验证
理解了格式之后,你可以依据同一套约定构造更多边界断言。以 List.replace 为例,值得补充验证的场景包括:
- 首尾边界:
List.replace([10, 20, 30], 0, 99)与List.replace([10, 20, 30], 2, 99)应返回Ok; - 恰好越界一位:
List.replace([10, 20, 30], 3, 99)应返回Err(OutOfBounds)(索引等于长度即越界,index < List.len(list)为假); - 空列表:
List.replace([], 0, 99)同样返回Err(OutOfBounds); - 大索引:
List.replace([10, 20, 30], 18446744073709551615, 99)(U64最大值)应稳定返回Err(OutOfBounds),而不是崩溃或回绕。
对每个场景,将表达式放入 SOURCE 段、期望值写入 OUTPUT 段、编译诊断(通常为 NIL)写入 PROBLEMS 段,即可沉淀为一条可回归的 REPL 快照。
小结
从一行 » List.replace(<a href="https://link.gitcode.com/i/8fcaccc516bffddb8a34f542d7754651" target="_blank">10, 20, 30], 5, 99) 出发,本文还原了 Roc 中"越界替换返回 Err(OutOfBounds)"这一语义的完整证据链:REPL 快照 [list_replace_oob.md 断言输出,标准库 Builtin.roc 通过 index < List.len(list) 显式检查并返回 Err,快照测试体系 则保证了这一行为在编译器演进中不被悄然改变。对于希望在 Roc 中编写健壮代码的开发者而言,记住一点即可:涉及索引的列表操作(replace、set、update、swap)都以 Try 返回值报告越界,务必在调用方处理 Err(OutOfBounds) 分支。