企业官网建设流程全解析

Roc 语言标准库中的Dict.fold_until允许在对字典的键值对做归约折叠时提前终止：步进函数通过返回Break(state)或Continue(state)标签值来控制是"就此停止"还是"继续折叠"。本篇以仓库中的 REPL 测试快照 test/snapshots/repl/dict_fold_until.md 为主干，结合 src/build/roc/Builtin.roc 中的标准库源码实现，逐步拆解其类型签名、运行语义、底层循环实现，以及与List.fold_until、Set.fold_until的关联，读完你可以直接在自己的 Roc 代码中熟练使用这一提前终止折叠模式。

从 REPL 测试快照说起

该快照是 Roc 编译器中用于验证 REPL 求值行为的"快照测试"文件，格式分为三部分：META（描述与测试类型）、SOURCE（在 REPL 中逐行输入并执行的 Roc 代码）、OUTPUT（对应的期望输出）。其description一句话概括了被测行为：

Dict.fold_untilfolds until the step returns Break, and full folds otherwise （Dict.fold_until在步进函数返回 Break 时停止折叠，否则进行完整折叠）

快照中的 REPL 交互如下：

» d = Dict.empty().insert("alice", 10.I64).insert("bob", 20).insert("charlie", 30) » d.fold_until(0, |acc, _k, v| if acc + v >= 20 { Break(acc + v) } else { Continue(acc + v) }) » d.fold_until(0, |acc, _k, v| Continue(acc + v)) » d.len()

对应的期望输出依次为：

assigned `d` --- 30 --- 60 --- 3

这四行代码构成了理解Dict.fold_until的最小完整演示：构建字典、带条件的提前终止折叠、无终止的全量折叠、以及折叠后字典原状不受影响的验证。下面逐段展开。

构建测试字典：Dict.empty 与链式 insert

第一行d = Dict.empty().insert("alice", 10.I64).insert("bob", 20).insert("charlie", 30)在 REPL 中执行后输出assigned \d`，表示变量d` 已绑定。它使用了三个标准库 API：

• Dict.empty()：返回空字典，签名见 src/build/roc/Builtin.roc 的empty : () -> Dict(_k, _v)；
• Dict.insert(dict, key, value)：插入键值对，若键已存在则覆盖旧值，签名见 src/build/roc/Builtin.roc 的insert : Dict(k, v), k, v -> Dict(k, v)，并要求k满足is_eq与to_hash约束（哈希表实现的必然前提）；
• 方法链（.语法）把每次插入后的新字典传给下一次调用——Roc 中字典是不可变（持久化）数据结构，每次insert都返回新的Dict，这也是为什么后续折叠不会改变d本身。

注意10.I64这一写法：它把第一个值显式标注为 64 位有符号整数，从而把整个字典的值类型确定为I64。后续的20、30会被统一推断为I64，因此后续 REPL 输出是整型字面量30、60、3（不带小数点）。与之对比，同目录下的 test/snapshots/repl/dict_fold.md 使用默认十进制数字类型，其输出为6.0这样的浮点形式——这是 REPL 对数字字面量的显示差异，不影响折叠语义本身。

核心语义：Break 提前终止，Continue 继续累加

第二次输入展示了fold_until的提前终止能力：

d.fold_until(0, |acc, _k, v| if acc + v >= 20 { Break(acc + v) } else { Continue(acc + v) })

步进函数接收三个参数：当前累计状态acc、键_k（此处用下划线前缀表示不使用）、值v。它返回一个标签联合值：当累计值达到 20 的阈值时返回Break(acc + v)终止折叠，否则返回Continue(acc + v)继续。REPL 输出30。

从结果反推（结合该测试运行时的哈希种子下的遍历顺序）：先访问到"alice"（值 10），0 + 10 < 20，返回Continue(10)，状态推进为 10；随后访问到"bob"（值 20），10 + 20 = 30 >= 20，此时返回Break(30)，折叠立即停止。最终30正是提前终止那一刻携带的状态值。

第三次输入验证了"全量折叠"路径：

d.fold_until(0, |acc, _k, v| Continue(acc + v))

步进函数永远返回Continue，等价于普通折叠，把所有三个值累加得到10 + 20 + 30 = 60。这印证了快照description中 "full folds otherwise" 的表述。

第四次输入d.len()输出3，确认字典键值对数量未受两次折叠影响——折叠是只读遍历，不会修改原字典。

类型签名：state 在 Continue 与 Break 之间流动

Dict.fold_until的完整签名位于 src/build/roc/Builtin.roc：

fold_until : Dict(k, v), state, (state, k, v -> [Continue(state), Break(state)]) -> state

逐段解读：

• 第一个参数是要遍历的Dict(k, v)；
• 第二个参数state是初始状态（本例为0），类型完全由调用处决定，可以是数字、字符串、列表、记录乃至任意自定义类型；
• 第三个参数是步进函数(state, k, v -> [Continue(state), Break(state)])：接收当前状态、键、值，返回一个二选一的标签联合[Continue(state), Break(state)]。两个标签都携带一个state类型的新状态；
• 返回类型state：无论是否提前终止，最终结果都是折叠结束时的最新状态。

标签联合（tag union）是 Roc 的核心语言特性，这里的[Continue(state), Break(state)]就是一种典型的"控制流编码"用法：与Bool相比，它让每个分支都能携带数据（新的状态），Continue与Break之间的语义差异完全由消费方（即fold_until的实现）解释。

源码实现：一个 for 循环 + match 的优雅折叠

在 src/build/roc/Builtin.roc 中，Dict.fold_until的实现非常直白：

fold_until = |dict, init, step| match dict { HashMap(data) => { var $state = init for (key, value) in data.entries { match step($state, key, value) { Continue(new_state) => { $state = new_state } Break(final_state) => { $state = final_state break } } } $state } }

关键点如下：

1. Dict的底层表示是HashMap(data)记录，其中data.entries是以元组(key, value)为元素的列表，for (key, value) in data.entries完成解构遍历；
2. var $state = init是可变变量的声明，配合循环体内的$state = new_state完成状态推进；
3. 每次迭代用match检查步进函数返回值：Continue(new_state)更新状态并进入下一轮；Break(final_state)先记录最终状态，再执行break跳出循环；
4. 循环结束后返回$state。注意Break分支的$state = final_state赋值是有意义的：即使步进函数在Break中携带了与当前状态不同的值，也会被如实返回。

break语句本身的语义在 docs/langref/loops.md 中有说明：它立即退出最内层循环。这正是fold_until实现"提前终止"的底层机制——所谓"提前终止折叠"，本质上就是在标准库内部对这个for循环执行了一次break。

与 Dict.fold 的对比：多一个控制通道

普通折叠 src/build/roc/Builtin.roc 的签名与实现是：

fold : Dict(k, v), state, (state, k, v -> state) -> state fold = |dict, init, step| match dict { HashMap(data) => { var $state = init for (key, value) in data.entries { $state = step($state, key, value) } $state } }

两者唯一的结构性差异在于步进函数的返回类型：fold的步进函数直接返回新状态state，因此它必然遍历完所有键值对；fold_until的步进函数返回[Continue(state), Break(state)]，由此获得"是否继续"的控制权。官方注释也这样描述二者关系："Same as [Dict.fold], except you can stop folding early"（与Dict.fold相同，只是可以提前停止），见 src/build/roc/Builtin.roc。fold_until的文档示例使用expect断言验证了阈值累加行为：

expect Dict.empty() .insert("Apples", 12.U64) .insert("Oranges", 24) .fold_until(0, |count, _key, qty| if count + qty >= 30 { Break(count + qty) } else { Continue(count + qty) }) == 36

选择建议：当结果可能在遍历中途就已确定（如阈值判断、查找命中、错误短路）时用fold_until避免无谓的剩余遍历；当必须处理全部键值对（如求和、构建聚合结构）时用fold更简洁。从工程角度看，fold_until的价值不只是"少算几步"，更在于把"提前退出"这种命令式控制流，以纯函数式、类型安全的方式表达出来。

家族一致：List.fold_until 与 Set.fold_until

fold_until并非字典独有，Roc 标准库把它作为一套统一的提前终止折叠模式提供给多个容器：

• List.fold_until：对列表元素折叠，签名与实现见 src/build/roc/Builtin.roc，同样用for item in list+match Continue/Break+break实现；
• Set.fold_until：直接委托给Dict.fold_until，见 src/build/roc/Builtin.roc：

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

从源码结构看，由于Set底层就是Dict（其数据记录以元素为键），Set.fold_until只需把"键值对"步进函数适配成"元素"步进函数，即可复用字典的全部实现。

这一族函数在 REPL 快照测试中有成体系的覆盖，可对照阅读以加深理解：

• test/snapshots/repl/dict_fold.md：Dict.fold全量累加的基础行为（输出6.0）；
• test/snapshots/repl/list_fold_until.md：List.fold_until全Continue时等价于List.fold（输出10.0）；
• test/snapshots/repl/list_fold_until_break_early.md：中途触发Break立即停止（输出3.0）；
• test/snapshots/repl/list_fold_until_break_first.md：第一个元素即Break，直接返回该状态（输出10.0）；
• test/snapshots/repl/list_fold_until_empty.md：空列表折叠返回初始状态（输出42.0）。

这些快照共同勾勒出fold_until家族的行为契约。

边界情况与使用注意事项

综合快照与源码实现，使用Dict.fold_until时应注意以下几点：

遍历顺序不可依赖。Dict是哈希表（HashMap(data)，其buckets与shifts字段随哈希种子动态确定，见 src/build/roc/Builtin.roc），遍历顺序取决于哈希种子，不保证等于插入顺序。本文开头快照输出30而非40，正说明在该次运行的哈希种子下先访问到alice再访问到bob；换一个种子或换一个进程，顺序可能不同。因此步进函数与阈值判断必须对遍历顺序不敏感，否则结果不可复现。

空字典返回初始状态。与List.fold_until的空列表行为一致（见 test/snapshots/repl/list_fold_until_empty.md），若字典为空，循环体一次都不执行，直接返回init。

首个元素即 Break。如果第一个被访问的键值对就让步进函数返回Break(state)，折叠立即结束，Break携带的状态原样返回，剩余元素一律不处理（对应列表场景见 test/snapshots/repl/list_fold_until_break_first.md）。

Break 携带的状态会被如实采用。实现中Break(final_state)分支会执行$state = final_state再跳出，因此你在Break中携带的状态不一定要等于当前acc——这给了你"终止时附加上下文"的自由，例如Break(acc + v)可以返回包含本次贡献的最终值。

键参数按需忽略。步进函数签名固定为(state, k, v)，但不需要键时可写成|acc, _k, v| ...（下划线前缀表示忽略该参数），快照中正是如此。

纯函数式约束。fold_until是只读遍历，不会修改原字典（d.len()在折叠后仍为3），累积的状态变量$state只存在于该次调用内部，这是 Roc 不可变数据哲学在标准库中的体现。

小结

Dict.fold_until用最小的语言机制（标签联合 +for/break）实现了"可提前终止的字典折叠"：返回Continue(state)继续、返回Break(state)停止，最终状态从所有分支中统一流出。通过 test/snapshots/repl/dict_fold_until.md 的 REPL 快照与 src/build/roc/Builtin.roc 的实现对照，可以确认其完整行为契约；而与Dict.fold、List.fold_until、Set.fold_until的横向对比，则展示了 Roc 标准库中"一套模式、多个容器复用"的设计取向。当你在 Roc 中需要"算到条件满足就停"的聚合逻辑时，fold_until就是那个类型安全、无副作用的答案。