Roc 语言 List.ends_with 用法详解:从 REPL 快照测试到源码实现

原创2026-09-19 17:21:111,967 阅读

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 returns Bool.True if 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))

其计算流程是:

  1. List.len(suffix) 取后缀长度 n;
  2. List.take_last(list, n) 从原列表尾部截取最后 n 个元素;
  3. 用 == 比较截取结果与 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 输出与源码注释中保持一致。

六、延伸阅读

通过"快照文档 + 源码实现"双重阅读路径,你可以快速、准确地掌握 Roc 标准库中任意函数的真实行为与设计约定。

登录后查看全文
roc