Roc 语言 List.replace 越界语义与 REPL 快照测试:从 Err(OutOfBounds) 到快照工具链

原创2026-09-18 12:52:511,890 阅读

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)
    }

从源码可以提炼出三个值得注意的实现事实:

  1. 索引类型是 U64:List.replace 只接受无符号 64 位整数作为索引,因此"负索引"在类型层面就被拒绝,唯一需要处理的越界方向是"索引不小于列表长度"。
  2. 失败路径通过 Try 类型表达:返回类型为 Try({ list : List(a), prev : a }, [OutOfBounds, ..]),其中 .. 是开放标签,意味着调用方可以在错误标签上追加自己的变体。界内时返回 Ok 包裹的记录(含 list 与 prev 两个字段),越界时返回 Err(OutOfBounds)——快照断言正是针对这一分支。
  3. 边界检查与不安全操作分离: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) 分支。

登录后查看全文
roc