Roc 语言 REPL 字典下标查询:解读 `Dict.subscript` 快照测试与 `Err(KeyNotFound)` 语义

原创2026-09-18 14:58:171,833 阅读

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)

几个关键信息:

  1. 纯别名实现:subscript = |dict, key| Dict.get(dict, key),没有任何额外逻辑,语义完全等同 Dict.get。
  2. 返回值类型:Try(v, [KeyNotFound, ..])——成功时是 Ok(value),失败时是 Err(KeyNotFound),其中 [KeyNotFound, ..] 是开放标签联合,允许错误集合在调用链上继续扩展。
  3. 键的类型约束:where [k.is_eq : k, k -> Bool, k.to_hash : k, Hasher -> Hasher],要求键类型 k 提供相等比较 is_eq 与哈希 to_hash 能力,这正是字典查找的数据结构基础。
  4. 设计意图:文档注释明确说明这是为未来 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 键查找语义的姊妹快照,共同构成覆盖矩阵:

这些用例说明 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] 语法糖的最短路径。

登录后查看全文
roc