Roc 语言 REPL 字典下标查询:解读 `Dict.subscript` 快照测试与 `Err(KeyNotFound)` 语义
Roc 语言 REPL 字典下标查询:解读 Dict.subscript 快照测试与 Err(KeyNotFound) 语义
Roc 语言内置字典类型 Dict 的下标操作 subscript 用于按键取值,命中时返回 Ok(value),键不存在时返回 Err(KeyNotFound)。本文以仓库中的 REPL 快照测试 test/snapshots/repl/dict_subscript.md 为骨架,逐行剖析其交互过程,并结合 src/build/roc/Builtin.roc 的源码实现,讲清 subscript 与 Dict.get 的别名关系、Try 结果类型与 KeyNotFound 错误的由来,以及这套快照文件如何作为可重复执行的回归测试运行。
一、快照测试文档的结构:META / SOURCE / OUTPUT / PROBLEMS
dict_subscript.md 采用 Roc 仓库 REPL 快照测试的统一四段式结构,每一段用 # 标题分隔:
| 段落 | 作用 |
|---|---|
# META |
ini 格式的元信息,声明 description(用例语义描述)与 type=repl(测试类型为 REPL 交互) |
# SOURCE |
以 » 提示符书写的 REPL 输入序列,即测试执行的原始命令 |
# OUTPUT |
每一条输入对应的预期输出,用 --- 分隔,作为断言基准 |
# PROBLEMS |
已知问题列表,NIL 表示当前无未解决的问题 |
本用例的 META 描述精确概括了被测语义:"Dict.subscript returns the value for a key, or Err(KeyNotFound) for absent keys"(Dict.subscript 返回键对应的值,键缺失时返回 Err(KeyNotFound))。type=repl 表明该快照由 REPL(读取-求值-打印循环)驱动,# PROBLEMS 为 NIL 说明该行为目前无已知缺陷,属于稳定契约。
二、逐行解读 SOURCE:链式构造与下标查询
快照的 SOURCE 段包含 4 条 REPL 命令:
» d = Dict.empty().insert("alice", "a heap allocated value").insert("bob", "another heap value")
» d.subscript("alice")
» d.subscript("missing")
» d.subscript("bob")
» d.len()
1. 链式构造字典 d
第一行演示了 Dict 的声明式构造风格:以 Dict.empty() 创建空字典,再通过两次 .insert(key, value) 链式插入两个键值对:
"alice"→"a heap allocated value""bob"→"another heap value"
值特意选用了堆分配的字符串(heap allocated value),说明 subscript 返回的是对存储值的访问结果,涉及引用计数与所有权语义,而非仅限于栈上可拷贝的标量。REPL 对此行的回显为 assigned \d``,表示变量绑定成功。
2. 命中键:Ok(value)
» d.subscript("alice")
输出为:
Ok("a heap allocated value")
说明字典中存在键 "alice" 时,subscript 返回包装在 Ok 中的值——Roc 用 Try 结果类型表达"可能失败"的操作,成功分支为 Ok。
3. 缺失键:Err(KeyNotFound)
» d.subscript("missing")
输出为:
Err(KeyNotFound)
这是本用例的核心断言:查询不存在的键不会崩溃、不会返回空值,而是以类型安全的方式返回错误标签 KeyNotFound,交由调用方通过模式匹配处理。
4. 再次验证第二个键
» d.subscript("bob")
输出 Ok("another heap value"),证明字典中多个条目均可被正确索引,查询逻辑与插入顺序、具体键名无关。
5. 长度校验
» d.len()
输出 2,与插入的两个键值对数量一致,用于佐证字典状态的完整性——插入了 2 条即长度为 2。
三、源码级印证:subscript 是 Dict.get 的别名
在 src/build/roc/Builtin.roc 中可以看到 subscript 的完整定义:
## Alias for [Dict.get], enabling the future `dict[key]` subscript operator.
## Returns the value for a given key.
##
## Returns `Err KeyNotFound` if the dictionary has no value for the key.
## ```roc
## expect Dict.empty()
## .insert("Apples", 12.U64)
## .subscript("Apples") == Ok(12)
## expect Dict.empty()
## .insert("Apples", 12.U64)
## .subscript("Oranges") == Err(KeyNotFound)
## ```
subscript : Dict(k, v), k -> Try(v, [KeyNotFound, ..])
where [k.is_eq : k, k -> Bool, k.to_hash : k, Hasher -> Hasher]
subscript = |dict, key| Dict.get(dict, key)
几个关键信息:
- 纯别名实现:
subscript = |dict, key| Dict.get(dict, key),没有任何额外逻辑,语义完全等同Dict.get。 - 返回值类型:
Try(v, [KeyNotFound, ..])——成功时是Ok(value),失败时是Err(KeyNotFound),其中[KeyNotFound, ..]是开放标签联合,允许错误集合在调用链上继续扩展。 - 键的类型约束:
where [k.is_eq : k, k -> Bool, k.to_hash : k, Hasher -> Hasher],要求键类型k提供相等比较is_eq与哈希to_hash能力,这正是字典查找的数据结构基础。 - 设计意图:文档注释明确说明这是为未来
dict[key]下标运算符语法预留的别名。当前阶段先以函数形式提供稳定 API,后续语法糖可直接映射到该函数。
而 Dict.get 的底层实现位于同文件 src/build/roc/Builtin.roc:
get : Dict(k, v), k -> Try(v, [KeyNotFound, ..])
where [k.is_eq : k, k -> Bool, k.to_hash : k, Hasher -> Hasher]
get = |dict, key| match dict {
HashMap(data) => match dict_find(data, key) {
Found(found) => Try.Ok(found.value)
Missing(_) => Try.Err(KeyNotFound)
}
}
实现揭示了 Dict 的真实形态:它是对 HashMap 的封装(模式匹配 HashMap(data)),内部通过 dict_find 在哈希表中定位键,返回 Found(found) 时取出 found.value 包成 Try.Ok,返回 Missing(_) 时构造 Try.Err(KeyNotFound)。这与快照中 Ok("...") / Err(KeyNotFound) 的输出完全一一对应。从源码结构可以推断:字典查找的时间复杂度取决于内部哈希表的实现,is_eq 与 to_hash 约束保证任意合法键类型都能走统一的查找路径。
四、错误处理的实战模式:匹配 Try 结果
subscript 返回 Try(v, [KeyNotFound, ..]) 意味着调用方必须显式处理缺失键的情况,Roc 编译器会强制穷尽匹配。常见写法:
result = Dict.empty().insert("alice", 1).subscript("bob")
# 显式匹配两个分支
when result is
Ok(value) -> value
Err(KeyNotFound) -> 0 # 提供默认值
KeyNotFound 是与 Dict 深度绑定的语义化错误标签:它比返回 Option(None)携带更明确的意图——"这个键不在字典里",并且由于错误集合是开放的([KeyNotFound, ..]),Try 可以与 Result 风格的其他错误标签自由组合,形成统一错误链。
五、相关快照:同一语义矩阵的更多侧面
dict_subscript.md 并非孤例,仓库 test/snapshots/repl/ 目录下存在一组围绕 Dict 键查找语义的姊妹快照,共同构成覆盖矩阵:
- test/snapshots/repl/dict_get_missing.md:专门验证
Dict.get对缺失键返回Err(KeyNotFound)的基准行为; - test/snapshots/repl/dict_from_iter.md 与 test/snapshots/repl/dict_from_list_duplicates.md:覆盖从迭代器/列表构造字典及重复键的处理;
- test/snapshots/repl/dict_collision_cluster.md 与 test/snapshots/repl/dict_collision_rebuild.md:验证哈希碰撞场景下的查找正确性;
- test/snapshots/repl/dict_growth_all_lookups.md:字典扩容后所有键仍可查询;
- test/snapshots/repl/dict_keep_if.md:过滤操作后的键查找。
这些用例说明 subscript/get 的 Ok/Err(KeyNotFound) 契约在插入、重复、碰撞、扩容、过滤等各类字典状态变迁下均保持稳定。
六、横向对比:subscript 在不同容器中的语义差异
subscript 并不是 Dict 的专属 API,src/build/roc/Builtin.roc 中不同容器类型各自定义了符合自身语义的 subscript:
| 容器 | 签名 | 返回语义 |
|---|---|---|
Dict |
subscript : Dict(k, v), k -> Try(v, [KeyNotFound, ..]) |
按键取值,缺失返回 Err(KeyNotFound) |
List |
subscript : List(item), U64 -> Try(item, <a href="https://link.gitcode.com/i/15eeae029b544d3f8aece23d27555f68" target="_blank">OutOfBounds, ..])([Builtin.roc) |
按下标取元素,越界返回 Err(OutOfBounds),是 List.get 的别名 |
Set |
subscript : Set(item), item -> Bool(Builtin.roc) |
判断成员是否存在,是 Set.contains 的别名 |
可以看出,subscript 是 Roc 内建容器统一暴露的"索引访问"接口名,而具体返回类型随容器语义而变:Dict 返回 Try 结果、List 返回带越界错误的 Try 结果、Set 直接返回布尔值。理解这一设计有助于在阅读和编写 Roc 代码时快速把握不同容器的访问契约。
七、如何亲自复现该快照
该快照文件本身是测试资产,读者可以在仓库中查看,也可以在自己环境中运行 REPL 验证相同行为:
# 在仓库根目录构建或使用已安装的 roc 二进制,然后启动 REPL
roc repl
进入 REPL 后逐条输入 SOURCE 段的命令(去掉 » 提示符),观察输出是否与 OUTPUT 段一致。若 roc 已安装且版本与仓库匹配,d.subscript("alice") 应回显 Ok("a heap allocated value"),d.subscript("missing") 应回显 Err(KeyNotFound),d.len() 应回显 2。该快照在 CI 中作为回归测试持续执行,任何破坏 Dict.subscript 契约的改动都会导致输出比对失败,从而守护这套语义的长期稳定。
八、小结
dict_subscript.md 用 5 条 REPL 命令完整锁定了 Dict.subscript 的行为契约:命中返回 Ok(value)、缺失返回 Err(KeyNotFound)、字典长度不受查询影响。源码侧,src/build/roc/Builtin.roc 表明 subscript 是 Dict.get 的纯别名,底层经 dict_find 在 HashMap 中查找并区分 Found/Missing 两种结果;类型签名 Try(v, [KeyNotFound, ..]) 与 is_eq/to_hash 约束共同保证了类型安全与可扩展的错误处理。这套"快照文档 + 内建库源码"的组合,既是可复现的测试用例,也是理解 Roc 字典查找语义与未来 dict[key] 语法糖的最短路径。