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

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

【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc

本文以 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的完整行为契约：

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), [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)。

【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc