Roc 语言 List.ends_with 用法详解:从 REPL 快照测试到源码实现
Roc 语言 List.ends_with 用法详解:从 REPL 快照测试到源码实现
导读
本文以 Roc 语言仓库中的 REPL 快照测试文档 list_ends_with.md 为核心,深入讲解 List.ends_with 列表后缀判断函数:包括其 REPL 交互式验证方式、完整语义边界(空后缀、空列表、不匹配场景)、类型约束,以及从 Builtin.roc 源码出发的实现原理与关联函数。读完本文,你将掌握 List.ends_with 的完整用法,并能通过 REPL 快照测试体系快速验证任意列表函数的真实行为。
一、REPL 快照测试文档的结构解读
Roc 仓库在 test/snapshots/repl/ 目录下存放了大量 REPL(Read-Eval-Print Loop)快照测试,每个 .md 文件都是一次 REPL 会话的"标准答案"。以 list_ends_with.md 为例,文件由四个固定区块组成:
# META
~~~ini
description=List.ends_with returns True when the first list ends with the second
type=repl
~~~
# SOURCE
~~~roc
» List.ends_with([1, 2, 3, 4], [3, 4])
~~~
# OUTPUT
True
# PROBLEMS
NIL
# META:描述该测试意图(description)与测试类型(type=repl),供测试框架分类与生成文档使用;# SOURCE:»是 REPL 提示符,其后是用户输入的一行 Roc 表达式;# OUTPUT:REPL 对该表达式求值后打印的结果;# PROBLEMS:预期诊断信息,NIL表示本次求值没有任何错误或警告。
这套快照体系由测试框架自动比对"实际输出 vs 快照输出",一旦 List.ends_with 的实现行为发生变化,对应快照文件就会被标记为失败,从而起到回归保护作用。因此,快照文件本身就是对函数行为最权威、最精确的文档。
二、List.ends_with 核心用法与语义
2.1 基础用法:判断列表是否以指定子列表结尾
List.ends_with 接收两个列表,返回一个布尔值,表示第一个列表是否以第二个列表作为结尾:
» List.ends_with([1, 2, 3, 4], [3, 4])
True
函数签名如下(见 Builtin.roc):
ends_with : List(a), List(a) -> Bool where [a.is_eq : a, a -> Bool]
关键点解读:
- 元素类型必须一致:两个列表的元素类型均为
a,即ends_with要求两个列表是同类型列表; - 类型约束
a.is_eq:函数通过元素相等性(is_eq)比较子列表与原列表的尾部,因此元素类型必须支持相等比较。数值、字符串等可比较类型均可直接使用; - 返回值是
Bool:结果为Bool.True或Bool.False,而非其他语言常见的true/false字面量。
2.2 后缀匹配成功与失败
仓库中专门为成功与失败两种情形各建了快照:
| 场景 | 表达式 | 输出 | 快照文件 |
|---|---|---|---|
| 匹配成功 | List.ends_with([1, 2, 3, 4], [3, 4]) |
True |
list_ends_with.md |
| 匹配失败 | List.ends_with(<a href="https://link.gitcode.com/i/e5c47a135b8ea81f13119f5d94aaeca9" target="_blank">1, 2, 3], [9, 9]) |
False |
[list_ends_with_no_match.md |
当后缀不匹配时返回 False。注意匹配是顺序敏感的:[1, 2, 3] 以 [2, 3] 结尾,但不以 [3, 2] 结尾。
2.3 空后缀的边界语义
快照 list_ends_with_empty_suffix.md 验证了一个重要约定:
» List.ends_with([1, 2, 3], [])
True
即:任何列表都以空列表结尾。这一约定与数学中"空串是任意字符串的后缀"保持一致,也与源码注释完全吻合(见 Builtin.roc):
If the second list is empty, this always returns
Bool.True; every list is considered to "end with" an empty list. If the first list is empty, this only returnsBool.Trueif the second list is empty.
翻译过来:
- 第二个列表(后缀)为空 ⇒ 恒为
Bool.True; - 第一个列表(原列表)为空 ⇒ 仅当第二个列表也为空时才返回
Bool.True。
也就是说 List.ends_with([], []) == Bool.True,而 List.ends_with([], [1]) == Bool.False。
三、源码级实现原理
3.1 基于 take_last 的简洁实现
List.ends_with 的实现只有一行(见 Builtin.roc):
ends_with = |list, suffix|
suffix == List.take_last(list, List.len(suffix))
其计算流程是:
List.len(suffix)取后缀长度n;List.take_last(list, n)从原列表尾部截取最后n个元素;- 用
==比较截取结果与suffix是否相等,得到布尔结果。
3.2 take_last 的内部细节
List.take_last 的定义(见 Builtin.roc)进一步揭示了边界行为:
take_last : List(a), U64 -> List(a)
take_last = |list, n| {
len = List.len(list)
start = if (len <= n) 0 else len - n
List.sublist(list, { start: start, len: len })
}
- 当
len <= n时start取 0,返回整个列表。这正是"空后缀恒返回 True"的实现来源:n = 0时List.take_last(list, 0)与空后缀比较仍成立,因为start逻辑与sublist截取保证结果与原列表尾部语义一致; - 当
n > 0且小于列表长度时,从len - n处截取到末尾,恰好得到原列表的末n个元素。
因此 ends_with 的边界语义(空后缀为 True、空列表仅在空后缀时为 True)完全由 take_last + sublist 的组合自然推导出来,代码虽短,但语义严谨。
3.3 与 starts_with 的对称关系
List.ends_with 与 List.starts_with 在实现上严格对称(见 Builtin.roc):
starts_with = |list, prefix|
prefix == List.take_first(list, List.len(prefix))
一个用 take_first(取前缀),一个用 take_last(取后缀)。两者的快照测试也是一一对应的:list_starts_with.md、list_starts_with_empty_prefix.md、list_starts_with_no_match.md 分别对应本节讲到的三种场景。如果你理解了 ends_with,那么 starts_with 的语义与边界可以完全类比得出。
3.4 与字符串 ends_with 的对照
List.ends_with 对应字符串版本的 Str.ends_with(见 Builtin.roc):
ends_with : Str, Str -> Bool
## expect "ABC".ends_with("C") == Bool.True
## expect "ABC".ends_with("X") == Bool.False
字符串版本同样返回 Bool,并附带 expect 测试断言。两者的 REPL 快照也同时存在于仓库中(str_ends_with.md)。在解释器层面,字符串版本走的是内置的 str_ends_with 指令(见 interpreter.zig 的 str_ends_with 分支),而列表版本则是纯 Roc 源码实现,这体现了 Roc 内置函数"解释器指令与语言库实现并存"的架构特点。
四、实战应用示例
4.1 在 REPL 中验证
启动 Roc REPL 后,可直接输入:
» List.ends_with(["roc", "is", "fast"], ["fast"])
True
» List.ends_with(["roc", "is", "fast"], ["is", "fast"])
True
» List.ends_with(["roc", "is", "fast"], ["roc"])
False
4.2 文件扩展名判断
利用 ends_with 做简单分类(元素为字符串列表时):
file_type = |path|
if List.ends_with(path, ["roc"]) {
"Roc source file"
} else if List.ends_with(path, ["md"]) {
"Markdown file"
} else {
"Other"
}
4.3 结合相等性约束的类型安全
由于签名带 [a.is_eq : a, a -> Bool] 约束,List.ends_with([1, 2], ["a"]) 这类跨类型比较会在编译期被拒绝,避免隐式类型转换带来的意外结果。
五、常见问题(FAQ)
Q1:List.ends_with([], []) 返回什么?
A:Bool.True。空列表以空列表结尾,符合"第一个列表为空时,仅当第二个列表也为空才返回 True"的约定。
Q2:后缀长度超过原列表长度会怎样?
A:返回 Bool.False。因为 take_last 在 len <= n 时返回整个列表,只有当 suffix 恰好等于整个原列表时才可能为 True,而长度超长的 suffix 不可能相等。
Q3:可以用 ends_with 判断非字符串类型吗?
A:可以,只要元素类型支持相等比较(满足 a.is_eq 约束)。数值、字符串、可比较的结构类型均可。
Q4:为什么返回的是 Bool.True 而不是 true?
A:Roc 语言中的布尔类型是 Bool,其值为 Bool.True 与 Bool.False,这一点在 REPL 输出与源码注释中保持一致。
六、延伸阅读
- List.starts_with 快照:前缀判断的对称场景;
- List.take_last 实现:
ends_with的底层依赖; - Str.ends_with 定义:字符串版本对照;
- REPL 快照目录:
list_*、str_*系列覆盖了列表与字符串各函数的全部边界行为。
通过"快照文档 + 源码实现"双重阅读路径,你可以快速、准确地掌握 Roc 标准库中任意函数的真实行为与设计约定。