Roc 语言 List.swap 越界索引行为解析:从 REPL 快照测试看 Err(OutOfBounds) 的完整语义

原创2026-09-18 13:25:541,750 阅读

Roc 语言 List.swap 越界索引行为解析:从 REPL 快照测试看 Err(OutOfBounds) 的完整语义

本文以 Roc 语言标准库中 List.swap 的越界索引快照测试为切入点,系统讲解 List.swap 的交换语义、OutOfBounds 错误标签(tag)的返回时机,以及 REPL 快照测试(type=repl)如何作为编译器行为契约锁定这些细节。读完本文,你将掌握 List.swap 的完整调用方式与边界条件,理解 Try(List(a), [OutOfBounds, ..]) 返回值在实际代码中如何安全处理,并能亲自运行与更新 REPL 快照测试来验证编译器行为。

一、快照文档本身:一次越界交换的完整测试记录

关联文档 list_swap_oob.md 是 Roc 编译器的 REPL 快照测试文件。它用四段标记完整记录了一次“越界交换”的求值过程:

# META
~~~ini
description=List.swap with an out-of-bounds index returns Err(OutOfBounds)
type=repl
~~~
# SOURCE
~~~roc
» List.swap([10, 20, 30], 0, 5)
~~~
# OUTPUT
Err(OutOfBounds)
# PROBLEMS
NIL

逐段解读:

  • META:description 用一句话概括本快照的断言目标——"List.swap with an out-of-bounds index returns Err(OutOfBounds)";type=repl 声明这是一个 REPL 求值类快照,快照工具会以 REPL 交互方式执行 SOURCE 中的表达式(» 是 REPL 提示符)。
  • SOURCE:在 REPL 中求值 List.swap([10, 20, 30], 0, 5)。注意 0 是合法索引,但 5 已超出三元素列表的索引范围 0..2。
  • OUTPUT:期望求值结果为 Err(OutOfBounds)——即交换失败,且错误类型是 OutOfBounds 标签。
  • PROBLEMS:NIL 表示该表达式在类型检查阶段不产生任何诊断报告。它从编译到求值全程类型正确,错误完全发生在运行时语义层面,这正说明越界行为是被类型系统接受、由运行时显式报告的既定语义,而不是编译错误。

二、对照快照:同一函数的三个行为剖面

在 test/snapshots/repl 目录下,List.swap 共有三份快照,恰好覆盖了正常、边界、越界三种情况,可以互相印证:

快照文件 调用 输出 语义
list_swap.md List.swap([10, 20, 30, 40], 0, 3) Ok([40.0, 20.0, 30.0, 10.0]) 交换首尾元素成功
list_swap_same_index.md List.swap([10, 20, 30], 1, 1) Ok([10.0, 20.0, 30.0]) 两个索引相同,交换为空操作(no-op)
list_swap_oob.md List.swap([10, 20, 30], 0, 5) Err(OutOfBounds) 任一索引越界即整体失败

这三份快照共同勾勒出 List.swap 的完整行为契约:

  1. 两个索引都合法(index < List.len(list))时,返回 Ok,元素交换发生;
  2. 索引相同是合法且无害的,结果列表不变;
  3. 只要有一个索引越界,整体返回 Err(OutOfBounds)——这是本篇文章核心快照所锁定的行为;
  4. 输出中的 40.0、10.0 等浮点写法,是 Roc 默认数字类型 F64 在 REPL 输出中的正常表示,与交换逻辑无关。

三、源码级剖析:swap 的实现与越界判定

List.swap 的标准库实现位于 Builtin.roc:

## Exchanges the items at the two given indices.
## ```roc
## expect [10, 20, 30, 40].swap(0, 3) == Ok([40, 20, 30, 10])
##
## expect [10, 20, 30].swap(0, 5) == Err(OutOfBounds)
## ```
swap : List(a), U64, U64 -> Try(List(a), [OutOfBounds, ..])
swap = |list, index_1, index_2| {
    len = List.len(list)
    if index_1 < len and index_2 < len {
        Ok(list_swap_unsafe(list, index_1, index_2))
    } else {
        Err(OutOfBounds)
    }
}

逐行解读实现要点:

  • 类型签名:List(a), U64, U64 -> Try(List(a), [OutOfBounds, ..])。三个参数分别是列表、两个 U64 类型的索引;返回值是 Try,成功为 Ok(List(a)),失败为 Err(OutOfBounds)。注意错误标签写为 [OutOfBounds, ..]——这是“开放标签联合”(open tag union),表示 swap 至少可能产生 OutOfBounds,调用方可以用 is、? 等语法处理,也可以继续补充其他错误标签。
  • 越界判定是“双索引与”逻辑:if index_1 < len and index_2 < len,两个索引都必须落在 [0, len) 区间内才执行交换;任一索引越界,整体返回 Err(OutOfBounds)。这与快照 List.swap([10, 20, 30], 0, 5) 的行为完全一致:index_1 = 0 合法,index_2 = 5 越界,于是走 else 分支返回 Err(OutOfBounds)。
  • 底层原语:成功路径调用的是带 unsafe 后缀的低层内建函数 list_swap_unsafe。它假定索引已被上层验证合法,因此不再做边界检查——安全边界由 swap 这个公开函数负责把关。list_swap_unsafe 通过 LowLevel.zig 枚举中的 list_swap 与 LowLevelBuiltins.zig 中的注册表绑定到运行时原语,并在 LowLevel.zig 处被标注为对第一个参数(列表)要求运行时唯一性(runtimeUniqueness(argMask(&.{0}))),即原地交换要求列表引用唯一、无别名。
  • 配套断言:swap 文档注释中的两个 expect 断言与三份快照一一对应(Ok 交换成功 / Err(OutOfBounds) 越界失败),标准库自测与 REPL 快照形成双重验证。

安全边界:swap 与 list_swap_unsafe 的分工

这种“公开函数做边界检查 + 内部 unsafe 原语做裸操作”的分层在 Roc 标准库中是一致的设计模式。对比同文件中的 replace 与 update:它们同样先以 index < List.len(list) 做边界判断,合法时再调用 list_replace_unsafe / list_map_* 等 unsafe 原语,越界则返回 Err(OutOfBounds)。也就是说,OutOfBounds 是标准库索引类操作统一的错误标签,调用者可以放心地用同一套 match 分支处理 swap、replace、update、get、insert 等函数的越界情况。

四、如何在真实代码中安全处理 swap 的越界结果

快照展示的 Err(OutOfBounds) 不是抽象的语法展示,而是每个调用 List.swap 的 Roc 程序都必须面对的真实分支。以下是在实际业务代码中的典型处理方式:

handle_swap = |list, i, j| {
    when List.swap(list, i, j) is
        Ok(swapped) -> swapped       # 交换成功,使用新列表
        Err(OutOfBounds) -> list     # 越界:保持原列表不变
}

更稳健的写法是结合 Try 的传播机制:如果外层函数本身就是返回 Try 的,可以用 ? 运算符让越界错误沿调用链自然传播,由最外层的调用者统一处理:

swap_or_propagate = |list, i, j| {
    swapped = List.swap(list, i, j)?   # 越界时提前返回 Err(OutOfBounds)
    Ok(swapped)
}

同时,由于索引类型是 U64(无符号),swap 不存在“负索引”问题——但反过来也意味着你不能用 -1 表示“最后一个元素”,所有索引都必须是显式的非负整数。这种设计让越界判定的 index < len 检查极其干净:只需检查上界,无需担心负数下界。

五、运行与更新 REPL 快照测试

这份快照文件不是一个孤立的文档,而是可以实际驱动编译器测试的工具输入。根据 test/snapshots/README.md 的说明,快照测试通过 Zig 构建系统运行:

# 更新单个快照(例如本文分析的越界 swap 快照)
zig build run-snapshot-tool -- test/snapshots/repl/list_swap_oob.md

# 生成/更新全部快照
zig build run-snapshot-tool

# 调试 REPL 求值过程(跟踪解释器执行)
zig build run-snapshot-tool -- test/snapshots/repl/list_swap_oob.md --trace-eval

要点说明:

  • --update-expected 参数可从当前 PROBLEMS 重新生成期望输出;对 REPL 快照而言,OUTPUT 部分由求值器实际运行 SOURCE 得出,快照工具负责比对或更新;
  • --trace-eval 只对 type=repl 的快照生效,且一次只能指定单个快照文件;Debug 构建默认开启 trace,Release 构建需以 -Dtrace-eval=true 显式开启;
  • 快照的价值在于锁定行为契约:当编译器或标准库改动导致 List.swap 越界不再返回 Err(OutOfBounds) 时,这份快照会在测试中立刻报错,从而捕获回归。快照体系中还有 type=file、snippet、expr 等类型用于诊断语义的快照,以及 reporting/ 目录下固定渲染输出格式的快照,本文件属于 REPL 求值行为一类。

六、总结:从一份快照看到的完整语义闭环

List.swap([10, 20, 30], 0, 5) 返回 Err(OutOfBounds) 这一结果,背后是一条完整的证据链:

  1. 公开语义:swap 的类型签名 Try(List(a), <a href="https://link.gitcode.com/i/b68f26b174b6005637fa72729f343405" target="_blank">OutOfBounds, ..]) 在类型层面宣告了越界失败的可能性([Builtin.roc);
  2. 实现逻辑:index_1 < len and index_2 < len 的双重边界检查决定了失败条件(Builtin.roc);
  3. 运行时支撑:list_swap_unsafe 原语要求列表唯一引用、负责裸交换(LowLevel.zig);
  4. 测试契约:REPL 快照将上述语义固化为可回归验证的期望输出(list_swap_oob.md)。

无论你是 Roc 语言学习者想理解 Try 与开放标签联合的实战形态,还是编译器开发者想了解快照测试如何守护行为契约,List.swap 的越界路径都是一个小而完整的范例:索引越界不是崩溃,也不是编译错误,而是一个被类型系统正式建模、被运行时显式报告、被测试快照严格锁定的 Err(OutOfBounds)。

登录后查看全文
roc