企业官网建设流程全解析

List.fold_until是 roc 标准库中支持提前终止的折叠函数：它的步进函数通过返回Continue(state)或Break(state)来控制折叠是继续还是立即停止。本文以 roc 仓库中的 REPL 快照测试 list_fold_until_empty.md 为核心入口，深入讲解fold_until在空列表下的边界语义，并串联List、Dict、Set三类容器的对应实现，帮助读者准确掌握这一函数族的行为约定与性能特性。

一、从一条快照测试说起：空列表上的List.fold_until

在 roc 仓库的test/snapshots/repl/目录下，存在一组用于验证解释器（REPL）求值行为的快照测试。其中 list_fold_until_empty.md 完整记录了一次针对空列表调用List.fold_until的求值过程，其内容如下：

# META description=List.fold_until on an empty list returns the initial state unchanged type=repl

» List.fold_until([], 42, |acc, x| Continue(acc + x))

42.0 # PROBLEMS NIL

这份快照文件包含四个标准区块：

• META区块：以 ini 格式声明快照的描述信息与类型。type=repl表示这是一条 REPL 快照，走的是解释器求值路径（而非仅做类型检查的普通快照）；
• SOURCE区块：待求值的 roc 表达式，»是 REPL 提示符；
• OUTPUT区块：期望的输出结果，本例为42.0；
• PROBLEMS区块：编译/求值过程中产生的诊断报告序列化结果，NIL表示没有任何错误或警告。

该测试断言的核心语义是：对空列表调用fold_until，步进函数一次也不会被调用，函数直接返回初始状态init（即 42）。这既是List.fold的既有行为，也被List.fold_until完整继承——因为"没有元素可以折叠"，无论步进函数内部写的是Continue还是Break，它都根本没有机会执行。

值得注意的是输出显示为42.0而非42。这是 roc REPL 中数值字面量默认按F64处理并渲染的结果，属于展示层面的细节，并不影响"返回值与初始状态相等"这一语义结论。

二、fold_until的签名与核心语义：Continue/Break双态步进函数

fold_until的定义位于 roc 标准库内建模块 src/build/roc/Builtin.roc，其完整类型签名为：

fold_until : List(item), state, (state, item -> [Continue(state), Break(state)]) -> state

与普通List.fold相比，唯一的差异在于步进函数（step）的返回类型：它不再返回state，而是返回一个双态标签联合体[Continue(state), Break(state)]。语义约定如下：

• 返回Continue(new_state)：继续折叠，将new_state作为下一次步进的累加器；
• 返回Break(final_state)：立即终止折叠，跳过剩余所有元素，并以final_state作为整个表达式的结果。

依据 src/build/roc/Builtin.roc 中 List.fold_until 的实现（L4610-L4627），其底层逻辑是一个带break的循环：

fold_until = |list, init, step| { var $state = init for item in list { match step($state, item) { Continue(new_state) => { $state = new_state } Break(final_state) => { $state = final_state break } } } $state }

从源码结构看，其执行流程可以归纳为三点：

1. 初始化：局部可变变量$state被赋值为init；
2. 遍历匹配：对列表中的每个元素调用step，用match区分Continue与Break两种分支——Continue分支更新$state后继续循环，Break分支将$state覆盖为final_state并执行break跳出循环；
3. 返回：循环结束后返回当前的$state。当列表为空时，循环体一次都不执行，$state始终保持为init——这正是快照 list_fold_until_empty.md 断言42.0的底层原因。

同一语义在Dict与Set上的镜像实现

fold_until并非List独有，Dict与Set也提供了完全同构的接口：

• Dict.fold_until（Builtin.roc L6012-L6029）：签名fold_until : Dict(k, v), state, (state, k, v -> [Continue(state), Break(state)]) -> state，步进函数接收键值对，内部同样用match处理Continue/Break，遇到Break立即跳出对data.entries的遍历；
• Set.fold_until（Builtin.roc L6450-L6453）：签名fold_until : Set(item), state, (state, item -> [Continue(state), Break(state)]) -> state，其实现是直接委托给Dict.fold_until：

fold_until = |Set.(dict), init, step| Dict.fold_until(dict, init, |state, item, _| step(state, item))

因此在 roc 中，"空容器折叠返回初始状态"这条规则对List、Dict、Set三者统一成立。

三、对照实验：非空列表上的三种典型行为

为了让fold_until的语义边界更清晰，仓库 test/snapshots/repl/ 下还提供了三组对照快照，与空列表用例互为印证。

1. 全程Continue：退化为List.fold

快照 list_fold_until.md 记录了步进函数永远返回Continue的情形：

» List.fold_until([1, 2, 3, 4], 0, |acc, x| Continue(acc + x))

输出为10.0，即0 + 1 + 2 + 3 + 4。当Break从未出现时，fold_until的行为与List.fold完全一致，所有元素都会被累加。

2. 中途Break：提前终止并返回该时刻的状态

快照 list_fold_until_break_early.md 展示了提前终止的典型用法：

» List.fold_until([1, 2, 3, 4, 5], 0, |acc, x| if acc + x > 5 { Break(acc) } else { Continue(acc + x) })

输出为3.0。逐元素推演如下：acc=0+1=1→Continue(1)；acc=1+2=3→Continue(3)；到第三个元素时，acc + x = 3 + 3 = 6 > 5成立，于是返回Break(acc)，即Break(3)。注意这里返回的是当前累加器 3，而不是acc + x = 6——Break携带的载荷由调用者自行决定，本例子刻意选择了尚未并入当前元素的旧累加值。列表后两个元素（4、5）被完全跳过，最终结果为3.0。

3. 首元素即Break：立即短路，等价于只看第一个元素

快照 list_fold_until_break_first.md 覆盖了最极端的提前终止情形：

» List.fold_until([10, 20, 30], 0, |acc, x| Break(acc + x))

输出为10.0。步进函数无条件返回Break(acc + x)，因此第一个元素上即触发break，20、30从未被访问，结果等价于0 + 10。这验证了实现中break语句的位置：Break分支在处理当前元素后立即跳出，剩余元素不参与计算。

小结：三类行为与空列表的统一性

四条快照共同刻画了fold_until的完整语义边界：只要存在Break，遍历立即停止；若始终没有Break（包括列表为空的情形），则行为与普通fold完全一致。

四、为什么需要fold_until：与List.fold的性能权衡

在 src/build/roc/Builtin.roc 的文档注释（L4599-L4609）中，roc 官方给出了选择fold_until而非fold的明确指引：

Same asList.fold, except you can stop folding early.

并补充了性能细节：相比List.fold，fold_until在可能访问更少的元素（从而提升性能）的同时，会让每一步的耗时略长——每个元素上多了一次match分支判断与标签联合体的构造/解构开销。但该额外成本"极其微小"，只要能够跳过哪怕少量元素，就很容易被抵消。因此官方建议：

如果提前返回Break的情况预计会很常见，那么使用fold_until通常在性能上优于List.fold。

这一特性让fold_until天然适合"提前命中即终止"的扫描型场景，例如：

• 阈值累加：累加到超过某阈值就停止（正是Dict.fold_until文档注释中 Builtin.roc L6001-L6011 给出的expect示例，累加水果数量到>= 30即返回Break(count + qty)）；
• 元素查找：在遍历中命中目标元素后立即返回，避免扫描整个列表；
• 尽早失败：在流式数据处理中遇到非法状态立刻中止折叠。

相应的，Dict.fold_until的语义注释（Builtin.roc L6001）也明确指出它与Dict.fold的关系：同样可以提前停止折叠，且Dict的fold_until快照测试 dict_fold_until.md 验证了"步进函数返回Break则提前终止、否则完整折叠"的双路径行为，以及d.len()不受折叠影响的事实。

五、如何在 REPL 中验证与调试：快照测试的运行方式

上述讨论均基于仓库中实际存在的 REPL 快照，读者可以直接在本地复现验证。快照测试的机制与用法记录在 test/snapshots/README.md：

• 快照测试通过捕获每个编译/求值阶段（词法分析、解析、规范化、类型检查等）的输出，验证编译器行为是否符合预期，并在编译器行为意外变化时帮助检测回归；
• 快照文件中的PROBLEMS区块存放诊断报告的规范 S-expression 序列化结果，NIL表示没有报告；REPL 快照（type=repl）还会在OUTPUT区块记录解释器求值结果；
• 生成/更新快照的命令为：

# 生成全部快照 zig build run-snapshot-tool # 仅更新指定快照 zig build run-snapshot-tool -- <file_path> # 依据诊断结果更新期望输出 zig build run-snapshot-tool -- <file_path> --update-expected # 调试 REPL 求值过程（打印解释器追踪信息） zig build run-snapshot-tool -- <repl_snapshot.md> --trace-eval

其中--trace-eval专门用于调试 REPL 快照：它只对type=repl的单个快照文件生效，调试构建默认开启追踪输出，发布构建则需要追加-Dtrace-eval=true启用。读者可以尝试将 list_fold_until_empty.md 的SOURCE中42改成其他初始值（例如7），再运行快照工具，观察OUTPUT区块随之变化，从而亲手验证"空列表返回初始状态"的语义。

在交互式 REPL 中，读者也可以直接输入等价表达式进行验证：

» List.fold_until([], 42, |acc, x| Continue(acc + x))

输出应为42.0；将初始值改为7，输出即为7.0——空列表下步进函数永远不可达，结果只由init决定。

六、总结

围绕快照 list_fold_until_empty.md 展开的完整分析可以收敛为以下结论：

1. 空列表语义：List.fold_until([], init, step)不调用步进函数，直接返回init，这是Continue/Break双态机制在"零元素"下的自然推论，也与其底层实现（Builtin.roc L4610-L4627 的初始化-循环-返回结构）严格一致；
2. 提前终止语义：步进函数返回Break(state)的瞬间，折叠立即停止，剩余元素不再访问，函数以Break载荷作为最终结果；Continue(state)则驱动折叠继续；
3. 与fold的关系：当Break始终不出现时，fold_until与List.fold行为等价；选择fold_until的本质是"用每步极小的match开销，换取提前终止时跳过大量元素带来的性能收益"；
4. 统一性：List、Dict、Set三类容器共享同一套fold_until语义（Set直接委托Dict实现），空容器返回初始状态的规则三者通用；
5. 可验证性：以上所有结论均可通过test/snapshots/repl/下的系列快照与 test/snapshots/README.md 提供的zig build run-snapshot-tool命令在本地复现验证。

对 roc 开发者而言，掌握fold_until的空列表边界与提前终止语义，是在遍历中实现"阈值扫描""命中即停"等高效逻辑的基础；而理解快照测试的组织方式，则能帮助你在改动编译器或标准库时，快速定位并验证此类语义是否发生回归。