Cangjie 标准库 std.collection 的 List 接口详解：索引友好的列表操作指南

人工智能AI 技能文档开发工具【免费下载链接】DocAgent项目地址https://gitcode.com/Cangjie-SIG/DocAgent点击查看免费下载ListT是 Cangjie 标准库std.collection中面向索引index操作的列表接口它在只读列表ReadOnlyListT的基础上补充了按位插入、按位删除、条件删除、清空与下标赋值等可变操作是ArrayList、LinkedList等列表容器的统一抽象。阅读本文后你将完整掌握List接口的全部成员函数原型、参数与返回值语义、边界行为与异常规则并能结合仓库中ArrayList/LinkedList的实现与官方示例在真实业务中正确选用合适的列表类型完成增删改查。一、List 接口的定位与继承关系ListT定义在std.collection包中其核心定位是只提供对索引友好操作的列表类型——即所有成员函数都围绕索引位置这一概念展开在指定索引插入、按索引删除、按下标替换。从 接口完整声明 可以看到它的继承关系与完整原型public interface ListT : ReadOnlyListT { func add(element: T): Unit func add(all!: CollectionT): Unit func add(element: T, at!: Int64): Unit func add(all!: CollectionT, at!: Int64): Unit func remove(at!: Int64): T func remove(range: RangeInt64): Unit func removeIf(predicate: (T) - Bool): Unit func clear(): Unit operator func [](index: Int64, value!: T): Unit }List的直接父类型是 ReadOnlyListT后者定义了只读侧的索引操作包括成员原型说明prop firstprop first: ?T返回列表中第一个元素空列表返回Noneprop lastprop last: ?T返回列表中最后一个元素空列表返回Nonegetfunc get(index: Int64): ?T返回指定位置元素索引小于 0 或大于等于元素数量时返回None下标 getoperator func [](index: Int64): T操作符重载 - get越界时抛出异常也就是说一个ListT类型的变量天然具备first、last、get(index)与list[index]读取能力无需额外依赖List接口本身只负责补齐可写的部分。在仓库的包总览 collection_package_overview.md 中List同样被描述为提供了对索引友好的列表操作。二、追加与插入add 系列成员函数List接口对add提供了 4 个重载覆盖单元素/整集合与末尾/指定位置两种维度的组合。1.add(element: T)末尾追加单元素func add(element: T): Unit将指定的元素附加到此列表的末尾。参数element: T为待插入的元素。2.add(all!: CollectionT)末尾追加整个集合func add(all!: CollectionT): Unit将指定集合中的所有元素附加到此列表的末尾。参数all!: CollectionT是需要插入的元素的集合从 ArrayList 的实现说明 看实现会按照迭代器顺序遍历入参集合将所有元素依次追加到列表尾部因此最终排列顺序与源集合的迭代顺序一致。3.add(element: T, at!: Int64)指定位置插入单元素func add(element: T, at!: Int64): Unit在此列表中的指定位置插入指定元素。at!: Int64是插入元素的目标索引!表示该参数以!结尾的参数名形式传递Cangjie 的命名实参写法如list.add(12, at: 1)。4.add(all!: CollectionT, at!: Int64)指定位置插入整个集合func add(all!: CollectionT, at!: Int64): Unit从指定位置开始将指定集合中的所有元素插入此列表。原先位于指定位置及其之后的元素会后移见 ArrayList.add(Collection, Int64) 的实现说明。add 的异常规则在具体实现如 ArrayList中当at超出合法范围时抛出 IndexOutOfBoundsException该异常定义于std.core包。三、删除操作remove / removeIf / clear1.remove(at!: Int64): T按索引删除func remove(at!: Int64): T删除此列表中指定位置的元素并返回被移除的元素本身返回类型是T而非OptionT。参数at!: Int64为被删除元素的索引在 ArrayList 实现 中索引越界时抛出IndexOutOfBoundsException。2.remove(range: RangeInt64): Unit按区间批量删除func remove(range: RangeInt64): Unit删除此列表中 RangeInt64 范围所包含的所有元素。Range是std.core中表示区间/步进的结构可支持1..2 : 1这类带步长的写法。需要注意 ArrayList 对 remove(Range) 的边界约定若range是通过 Range 构造函数构造的实例且hasEnd为false则end值不生效不受构造时isClosed影响此时区间会一直取到列表的最后一个元素step不等于 1 时抛出 IllegalArgumentExceptionstart或end小于 0或end大于列表长度时抛出IndexOutOfBoundsException。3.removeIf(predicate: (T) - Bool): Unit条件删除func removeIf(predicate: (T) - Bool): Unit删除此列表中满足给定 lambda 表达式或函数的所有元素。参数predicate: (T) - Bool传递判断删除的条件返回true的元素会被移除。典型用法如删除列表中所有偶数list.removeIf({ it % 2 0 })。该函数有一个重要的并发约束根据 ArrayList 的实现说明若在predicate内部增删或修改了列表中的元素将抛出 ConcurrentModificationException。这与std.collection包整体容器不支持并发修改的设计一致——在 异常类说明 中明确列出使用 for-in 遍历容器过程中对容器进行修改是典型的抛异常场景。4.clear(): Unit清空列表func clear(): Unit从此列表中删除所有元素操作后列表变为空列表。四、下标赋值operator func []set 重载operator func [](index: Int64, value!: T): Unit这是操作符重载的set方向通过下标运算符用指定的元素替换此列表中指定位置的元素。参数含义index: Int64- 要设置的索引值value!: T- 要设置的 T 类型的值。它与ReadOnlyList中继承下来的operator func [](index: Int64): Tget 方向正好构成一对读写组合list[0]读取首元素list[0] x替换首元素。在 ArrayList 的实现 中索引越界时抛出IndexOutOfBoundsException而 get 方向越界同样抛异常这与get(index)方法越界返回None的宽松语义形成对比使用时需注意区分。五、实战示例在 ArrayList 上的完整演练List接口的典型实现是 ArrayListpublic class ArrayListT : ListT变长的连续数组创建时不需要指定大小仓库在 collection 示例目录 中提供了可直接验证的用例。1. add 系列示例来自 sample_arraylist_add.mdimport std.collection.* main() { var list: ArrayListInt64 ArrayListInt64(10) // 创建一个容量为 10 的 ArrayList var arr: ArrayInt64 [1, 2, 3] list.add(all: arr) // list: [1, 2, 3] list[1] 120 // list: [1, 120, 3] var b list.get(2) print(b${b.getOrThrow()},) list.add(12, at: 1) // list: [1, 12, 120, 3] var c list.get(2) print(c${c.getOrThrow()},) var arr1: ArrayInt64 [1,2,3] list.add(all: arr1, at: 1) // list: [1, 1, 2, 3, 12, 120, 3] var d list.get(2) print(d${d.getOrThrow()}) return 0 }运行结果b3,c120,d2这段示例同时演示了List接口中的三个关键能力add(all:)批量追加、add(element, at:)指定位置插入以及[]set 下标替换list[1] 120。注意get(index)返回的是?TOption 封装需要通过getOrThrow()取出实际值。2. get/set 示例来自 sample_arraylist_get_set.mdimport std.collection.* main() { var list ArrayListInt64([97, 100]) // list: [97, 100] // 修改值 list[1] 120 // list: [97, 120] // 获取值 var b list.get(1) print(b${b.getOrThrow()}) return 0 }运行结果b1203. remove/clear 示例来自 sample_arraylist_remove_clear_slice.mdimport std.collection.* main() { var list: ArrayListInt64 ArrayListInt64([97, 100, 99]) list.remove(at: 1) // list: [97, 99] var b list.get(1) print(b${b.getOrThrow()},) list.clear() list.add(11) var arr: ArrayInt64 [1, 2, 3] list.add(all: arr, at: 0) // list: [1, 2, 3, 97, 99] var g list.get(0) print(g${g.getOrThrow()},) let r: RangeInt64 1..2 : 1 var sublist: ArrayListInt64 list.slice(r) // sublist: [2, 3] var m sublist.get(0) print(m${m.getOrThrow()}) return 0 }运行结果b99,g1,m2该示例展示了remove(at:)按索引删除删除索引 1 后[97, 99]、clear()清空后重新添加以及与Range配合的区间操作1..2 : 1表示从 1 到 2、步长 1 的闭区间对应元素为[2, 3]。六、实现视角ArrayList 与 LinkedList 的取舍List接口在std.collection中有两种主要实现理解其内部结构有助于做出正确的选型。ArrayList动态数组ArrayList 是基于连续内存的动态数组默认构造init()的初始容量为16也支持init(capacity: Int64)、init(elements: CollectionT)以及init(size, initElement)等构造方式详见 构造函数与成员当数组已满时会重新分配更大的内存空间并将原有元素复制到新空间见 ArrayList 功能说明提供reserve(additional: Int64)预扩容剩余容量不足时取原始容量的 1.5 倍向下取整与additional 已使用容量两者中的较大值扩容见 reserve 实现说明额外提供clone()浅拷贝、slice(range)、reverse()、toArray()等便捷方法。因此ArrayList适合需要频繁按索引随机访问的场景其代价是中间位置插入/删除需要移动后续元素且扩容时可能有复制开销。LinkedList双向链表LinkedList 实现双向链表由LinkedListNodeT节点串联支持在任意节点前后插入addAfter/addBefore、按节点删除remove(node)插入删除无需移动其他元素适合频繁在列表中部增删的场景提供firstNode/lastNode/nodeAt(index)访问节点以及forward(mark)/backward(mark)区间迭代器缺点是每个元素需要额外的节点内存且按索引访问是 O(n) 的遍历。两种实现都满足ListT接口因此面向ListT抽象编程的代码可以在这两者间平滑切换需要说明的是std.collection中的容器均不支持并发安全并发场景应使用collection.concurrent包见 包总览说明。七、使用注意事项小结读写下标行为不同list[index]读取get 方向与get(index)在越界时行为不一致——前者抛IndexOutOfBoundsException后者返回Nonelist[index] valueset 方向越界同样抛异常。remove 返回被删元素remove(at: index)直接返回被移除的元素类型T可用于取出后再处理而remove(range)无返回值。removeIf 中禁止修改容器在predicate内对列表做增删改会触发ConcurrentModificationException条件删除逻辑应保持纯净。Range 删除的步长限制remove(range)要求Range的step为 1且注意无终点 RangehasEnd false会一直删除到列表末尾。批量添加保持迭代顺序add(all: collection)按入参集合的迭代器顺序追加结果顺序可预期。综上ListT接口以索引为纲将读操作沉淀在ReadOnlyList、将写操作收拢在自身构成了 Cangjie 列表类容器统一、清晰的编程模型。无论是面向ArrayList的动态数组场景还是面向LinkedList的频繁增删场景掌握本接口的 9 个成员函数即可覆盖绝大多数列表操作需求。赞分享人工智能AI 技能文档开发工具【免费下载链接】DocAgent项目地址https://gitcode.com/Cangjie-SIG/DocAgent点击查看免费下载相关推荐std.collection 集合接口全解析从 Deque 到 Stack 的接口族谱与实战用法Cangjie 标准库std.collection 集合接口全解析从 Deque 到 Stack 的接口族谱与实战用法Cangjie 标准库 本篇技术指南以 Cangjie 标人工智能AI 技能文档开发工具仓颉标准库 std.collection 集合包完全指南九大数据结构、接口体系与迭代器操作函数详解仓颉标准库 std.collection 集合包完全指南九大数据结构、接口体系与迭代器操作函数详解 std.collection 是仓颉编程语言标准库中最常用编程语言语言运行时标准库垃圾回收并发编程仓颉语言 std.collection Deque 接口详解双端队列的头部/尾部操作与 ArrayDeque 实现原理仓颉语言 std.collection Deque 接口详解双端队列的头部/尾部操作与 ArrayDeque 实现原理 Dequedouble ended人工智能AI 技能文档开发工具上一篇如何彻底解决Mac鼠标滚动难题终极优化指南下一篇Windows 10终极解决方案如何快速安装PL-2303旧版芯片驱动创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考