人工智能AI 技能文档开发工具【免费下载链接】DocAgent项目地址https://gitcode.com/Cangjie-SIG/DocAgent点击查看免费下载std.collection是 Cangjie 标准库中提供常见数据结构高效实现、抽象接口定义以及集合操作通用函数的包。它覆盖了列表、双端队列、栈、队列、哈希表、哈希集合、红黑树映射与有序集合等日常开发中最常用的容器类型并配套一套可直接作用于任意Iterable的管道式集合操作函数如filter、map、fold、zip等。阅读本篇后你将能够按需选型容器、理解各实现的时间复杂度与扩容策略并直接使用文中示例快速上手 Cangjie 集合编程。包定位std.collection 提供什么根据包概述文档std/collection/collection_package_overview.mdcollection 包提供了三大类能力常见数据结构的高效实现以具体类class形式提供例如ArrayList、LinkedList、HashMap、HashSet、TreeMap、TreeSet、ArrayDeque、ArrayQueue、ArrayStack等相关抽象接口的定义以接口interface形式定义统一的操作契约例如List、Map、Set、Queue、Stack、Deque以及只读变体ReadOnlyList、ReadOnlyMap、ReadOnlySet等集合类型中常用的函数功能面向迭代器的通用函数例如all、any、map、filter、fold、reduce、zip、collect*系列转换函数等。一个需要特别注意的边界是collection 包提供的所有集合类型都不支持并发安全。从源码结构看ConcurrentModificationException的存在正是为了在检测到不同步的并发修改时及时暴露问题见 std/collection/collection_package_api/collection_package_exception.md。如果业务场景需要并发安全的集合应使用标准库中单独的并发集合包。数据结构实现总览std/collection/readme.md将包内全部容器分为数据结构实现与集合操作函数两大类。下表完整列出容器类型及其原型与说明名称原型说明DequeTinterfaces DequeT双端队列具有队列和栈特性允许在两端进行插入和删除操作。ListTinterfaces ListT提供对索引友好的列表操作。MapK, Vinterfaces MapK, V提供一种将键映射到值的方式。MapEntryViewK, Vinterfaces MapEntryViewK, V键值对集合中某个 Key 的视图。OrderedMapK, Vinterfaces OrderedMapK, V有序映射。OrderedSetTinterfaces OrderedSetT有序集合。QueueTinterfaces QueueT队列遵循先进先出FIFO原则。ReadOnlyListTinterfaces ReadOnlyListT定义对列表的只读操作。ReadOnlyMapK, Vinterfaces ReadOnlyMapK, V只读映射。ReadOnlySetK, Vinterfaces ReadOnlySetK, V只读集合。SetTinterfaces SetT不包含重复元素的集合。StackTinterfaces StackT栈具有后进先出LIFO特点。EquatableCollectionTinterfaces EquatableCollectionT定义了可以进行比较的集合类型。ArrayDequeTclass ArrayDequeT基于数组实现的双端循环队列支持两端插入和删除。ArrayListTclass ArrayListT变长的连续数组适合存储数量不确定或需按运行时条件动态调整大小的数据。ArrayQueueTclass ArrayQueueT基于数组实现的循环队列只允许尾部插入、头部删除。ArrayStackTclass ArrayStackT基于数组实现的栈先进后出只能在顶部插入和删除。LinkedListTclass LinkedListT链表结构可动态添加或删除元素而不必移动其他元素。HashMapK, Vclass HashMapK, V哈希表存储键值对可根据键快速访问值。HashSetTclass HashSetT基于哈希表实现的集合插入、删除、查找高效。TreeMapK, Vclass TreeMapK, V基于红黑树实现的有序映射表元素按自然顺序或自定义顺序排序。TreeSetTclass TreeSetT基于 TreeMap 实现的有序集合自动排序、去重。HashMapIteratorK, Vclass HashMapIteratorK, V主要实现 HashMap 的迭代器功能。LinkedListNodeTclass LinkedListNodeTLinkedListT 上的节点。ConcurrentModificationException(false)并发修改异常类。接口层面的完整签名与每个方法的语义说明见 std/collection/collection_package_api/collection_package_interface.md类层面的构造器、属性、方法与运算符重载说明见 std/collection/collection_package_api/collection_package_class.md。接口体系从只读到可写的继承层次从接口文档的源码结构可以清晰看到 collection 包的接口设计遵循只读能力 → 可写能力的递进分层只读一族ReadOnlyList、ReadOnlyMap、ReadOnlySet 只提供查询能力例如get、contains、keys()、values()、subsetOf()可写一族List 继承ReadOnlyList新增add、remove、removeIf、clear及下标赋值运算符[]Map 继承ReadOnlyMap新增add、remove、replace、addIfAbsent、entryView等Set 继承ReadOnlySet新增add、remove、retain、clear等顺序增强OrderedMap 在Map基础上增加first、last属性与removeFirst、removeLast、forward(mark, inclusive!)、backward(mark, inclusive!)定向遍历方法OrderedSet 同理结构契约Deque 提供addFirst/addLast/removeFirst/removeLast与first/last属性Queue 提供add/peek/removeStack 同样提供add/peek/remove但语义是栈顶EquatableCollection 提供单元素与批量contains判定。值得注意的是 MapEntryView 的value是可写属性设置非空 value 时若视图对应的键不存在会在原始映射中新增元素设置为None则会删除当前 Entry删除后视图仍可继续使用。这是实现通过视图读写映射的关键入口。树形容器特有的 forward / backward 定向遍历OrderedMap与OrderedSet提供的forward(mark, inclusive!)与backward(mark, inclusive!)是面向有序容器的定向迭代能力对应实现见 TreeMap 与 TreeSetforward(mark, inclusive!)从第一个键元素大于等于 mark 的节点开始按升序遍历到最后一个元素inclusive!决定当 mark 恰好命中首个元素时是否包含该起点默认为truebackward(mark, inclusive!)从第一个键元素小于等于 mark 的节点开始按降序遍历到第一个元素。类实现深度剖析底层原理与关键行为ArrayList可变长连续数组ArrayListT实现 List 接口是一种线性动态数组类定义见 std/collection/collection_package_api/collection_package_class.md。与定长Array不同它创建时无需指定大小插入时若容量不足会自动重新分配更大的内存并复制原有元素。文档明确提示动态数组可节省内存并按需扩容但重新分配内存时可能带来性能下降因此需要谨慎权衡使用场景。关键行为要点默认容量init()构造默认容量为 16init(capacity)可指定初始容量容量为负时抛IllegalArgumentException批量构造支持init(elements: CollectionT)、init(size, initElement)按函数规则生成 size 个元素以及静态工厂ArrayList.of(ArrayT)扩容策略reserve(additional)在剩余容量不足时取原始容量的 1.5 倍向下取整与additional 已使用容量两者中的较大值进行扩容additional小于等于 0 或剩余容量充足时不发生扩容当additional 已使用容量超过Int64.Max时抛OverflowException索引访问get(index)越界时返回None安全而下标运算符list[index]越界时抛IndexOutOfBoundsException严格范围操作slice(range)与remove(range)支持RangeInt64切片/删除若 range 为hasEnd false的构造实例end 不生效切片会取到原数组最后一个元素step不等于 1 时抛IllegalArgumentException切片返回全新对象与原列表无引用关系条件删除removeIf(predicate)删除所有满足条件的元素若 predicate 内部对列表进行了增删改会抛ConcurrentModificationException排序 API 已标记废弃sortBy、sort()、sortDescending()等标注为deprecated文档建议改用 sort 包中的sort函数见 std/sort/sort_package_api/sort_package_funcs.md扩展接口为ArrayList扩展了EquatableArrayListT对应位置元素相等即相等、ToString输出形如[elem1, elem2, elem3]。ArrayDeque / ArrayQueue / ArrayStack基于数组的线性容器三个类均以数组为底层存储区别在于操作约束ArrayDequeT实现DequeT见 ArrayDeque_class.md可调整大小的循环数组实现支持两端插入删除默认容量 8每次扩容默认增加 50%无扩容时插入、删除、查看的时间复杂度为 O(1)。removeFirst/removeLast在空队列时返回NoneArrayQueueT实现QueueT循环队列尾部插入add、头部删除remove、只读查看peek空队列时peek/remove返回None默认容量同为 8扩容逻辑与 ArrayDeque 一致ArrayStackT实现StackT数组 栈顶指针实现仅支持在顶部插入删除默认容量 8reserve在剩余空间不足时扩容至size additionaliterator()的遍历顺序即出栈顺序toArray()同样按出栈顺序输出。LinkedList双向链表与节点操作LinkedListT实现双向链表类定义见 LinkedList_class.md每个节点含前驱/后继指针支持双向遍历。文档特别强调两点迭代器失效规则对集合中元素的修改不会使迭代器失效只有添加和删除元素会使迭代器失效节点悬空风险通过firstNode/lastNode/nodeAt(index)时间复杂度 O(n)获得的LinkedListNode若对应节点被链表删除会变成悬空节点对其任何操作访问next/prev/value都会抛IllegalStateException。链表还提供addFirst/addLast返回新节点、addBefore/addAfter在指定节点前/后插入、remove(node)、splitOff(node)从指定节点处将链表一分为二node 成为新链表首节点、forward(node)/backward(node)从节点向尾部/头部遍历等节点级操作。HashMap哈希表实现HashMapK, V要求键满足K : Hashable EquatableK实现Map接口见 HashMap_class.md。文档描述其原理将数据映射到动态数组哈希表每个元素按哈希值定位查找、插入、删除的时间复杂度通常为 O(1)由于底层数组大小动态变化哈希表不能保证元素顺序不可变。默认初始容量为 16add(key, value)对已存在的键返回旧值Option封装键不存在返回None支持addIfAbsent键不存在才添加、replace键存在才替换返回旧值、removeIf遍历删除满足条件的键值对predicate 内改动容器会抛ConcurrentModificationExceptionkeys()返回EquatableCollectionKvalues()返回CollectionVtoArray()返回键值对数组下标运算符map[key]读取键不存在时抛NoneValueException写入时map[key] value等效于add重复键处理通过数组/集合构造时按迭代器顺序后面的键值对覆盖前面的键值对为HashMap扩展了Equatable键值对完全相等即相等与ToString形如[(k1, v1), (k2, v2), (k3, v3)]。HashSet基于 HashMap 的集合HashSetT要求T : Hashable EquatableT是基于HashMap实现的Set实例见 HashSet_class.md。文档明确指出HashSet 的容量、内存布局、时间性能与 HashMap 完全相同元素无序且不允许重复添加已存在的元素返回false。除常规的增删查改外HashSet 还提供集合代数运算符交集、|并集、-差集返回新HashSetretain(all!: SetT)仅保留与入参集合重复的元素subsetOf(other)判断是否为ReadOnlySet子集removeIf在 predicate 内部改动容器时抛ConcurrentModificationException。TreeMap / TreeSet红黑树支撑的有序容器TreeMapK, V要求K : ComparableK见 TreeMap_class.md基于平衡二叉搜索树文档及包概述均指明为红黑树实现OrderedMap提供有序的键值对存储适合数据库、缓存、查找表等需要有序键值对的场景。iterator()按 Key 从小到大顺序迭代支持forward/backward定向遍历、first/last、removeFirst/removeLastTreeSetT要求T : ComparableT见 TreeSet_class.md基于 TreeMap 实现OrderedSet自动排序且去重同样支持forward/backward、集合代数运算符与subsetOf。HashMapIterator 与并发修改保护HashMapIteratorK, V是 HashMap 的专用迭代器见 HashMapIterator_class.md其next()返回?(K, V)并且是唯一允许在遍历中调用remove()删除next 函数刚返回元素的入口——但该 remove 每次 next 后只能调用一次。迭代器检测到不同步的并发修改时抛ConcurrentModificationException。ConcurrentModificationException见 collection_package_exception.md的典型抛出场景包括使用for-in遍历容器过程中修改容器HashMapIterator.remove()除外使用生命周期较短的视图类型如MapEntryView时其所在容器内容被修改。集合操作函数面向迭代器的函数式工具std/collection/readme.md将包内通用函数完整列出这些函数大多采用先传入参数/谓词返回一个作用于IterableT的函数的柯里化风格便于与 pipeline 表达式|配合。下表为完整清单名称原型说明allT(T) - Bool判断迭代器所有元素是否都满足条件。anyT(T) - Bool判断迭代器是否存在任意一个满足条件的元素。atT(Int64)获取迭代器指定位置的元素越界/为空返回None。collectArrayListT(IterableT)将迭代器转换为ArrayList。collectArrayT(IterableT)将迭代器转换为Array。collectHashMapK, V(Iterable(K, V)) where K : Hashable EquatableK将迭代器转换为HashMap。collectHashSetT(IterableT) where T : Hashable EquatableT将迭代器转换为HashSet。collectStringT(String) where T : ToString将元素实现 ToString 的迭代器拼接为String可指定delimiter!分隔符默认。concatT(IterableT)串联两个迭代器。containsT(T) where T : EquatableT遍历判断是否包含指定元素。countT(IterableT)统计迭代器元素数量。enumerateT(IterableT)获取带索引(Int64, T)的迭代器。filterT((T) - Bool)筛选满足条件的元素。filterMapT, R((T) - ?R)同时进行筛选与映射返回Some视为通过、None视为剔除。firstT(IterableT)获取头部元素为空返回None。flatMapT, R((T) - IterableR)创建带 flatten 功能的映射。flattenT, R(IterableT) where T : IterableR将嵌套迭代器展开一层。foldT, R(R, (R, T) - R)使用指定初始值从左向右折叠计算。forEachT((T) - Unit)遍历所有元素并执行给定操作。inspectT((T) - Unit)每次next()对当前元素执行额外操作不消耗元素。isEmptyT(IterableT)判断迭代器是否为空。lastT(IterableT)获取尾部元素为空返回None。mapT, R((T) - R)创建映射。maxT(IterableT) where T : ComparableT筛选最大元素为空返回None。minT(IterableT) where T : ComparableT筛选最小元素为空返回None。noneT((T) - Bool)判断是否所有元素都不满足条件。reduceT((T, T) - T)以第一个元素为初始值从左向右归并为空返回None。skipT(Int64)跳过前 count 个元素count 为负抛IllegalArgumentException。stepT(Int64)每次next()跳过 count 个元素count 小于等于 0 抛异常。takeT(Int64)取出前 count 个元素count 为负抛异常为 0 返回空迭代器。zipT, R(IterableR)将两个迭代器按位置合并为(T, R)元组长度取决于较短者。函数完整签名与边界行为见 std/collection/collection_package_api/collection_package_function.md。其中几个值得注意的细节skip的边界count 0时相当于不跳过返回原迭代器count 迭代器大小时跳过所有元素返回空迭代器take的边界count 0返回空迭代器count 迭代器大小时取走全部元素返回原迭代器step是步进语义与skip不同每次调用next()都会跳过 count 个元素直到迭代器耗尽collectString的默认分隔符为空字符串示例中展示了用delimiter: 拼接的场景。实战示例从样例看典型用法仓库在 std/collection/collection_package_samples 目录下提供了多个可验证的官方示例均带!-- verify --标记以下选取四个典型场景。1. 迭代器函数 pipeline 管道式操作来自 sample_iterator.md 的示例演示了filter、step、skip、forEach、collectString、contains的组合用法import std.collection.* main() { let arr [-1, 2, 3, 4, 5, 6, 7, 8, 9] arr | filter{a: Int64 a 0} | // filter -1 stepInt64(2) | // [2, 4, 6, 8] skipInt64(2) | // [6, 8] forEachInt64(println) let str arr | filter{a: Int64 a % 2 1} | collectStringInt64(delimiter: ) println(str) println(arr | contains(6_i64)) return 0 }运行结果6 8 3579 true可以看到step步进 2 取 [2,4,6,8]与skip跳过前 2 个得 [6,8]的语义差异、以及collectString指定分隔符的效果一目了然。2. HashMap 的增查删来自 sample_hashmap_get_add_contains.md 与 sample_hashmap_add_remove_clear.mdimport std.collection.* main() { var map: HashMapString, Int64 HashMapString, Int64() map.add(a, 99) // map : [(a, 99)] map.add(b, 100) // map : [(a, 99), (b, 100)] var a map.get(a) var bool map.contains(a) print(a${a.getOrThrow()} ) print(bool${bool.toString()}) map.add(all: [(d, 11), (e, 12)]) // 批量添加 map.remove(d) // 按键删除返回 Option 封装的旧值 map.clear() // 清空 return 0 }运行结果a99 booltrue。注意get返回OptionV需用getOrThrow()解包contains用于键存在性判断。3. ArrayList 的增改查、删除与切片来自 sample_arraylist_add.md、sample_arraylist_get_set.md 与 sample_arraylist_remove_clear_slice.mdimport std.collection.* main() { var list: ArrayListInt64 ArrayListInt64(10) // 容量为 10 list.add(all: [1, 2, 3]) // list: [1, 2, 3] list[1] 120 // 下标写list: [1, 120, 3] var b list.get(2) // b 3 list.add(12, at: 1) // list: [1, 12, 120, 3] list.remove(at: 1) // 删除索引 1 处元素 list.add(all: [1, 2, 3], at: 0) // 从索引 0 批量插入 let r: RangeInt64 1..2 : 1 var sublist: ArrayListInt64 list.slice(r) // sublist: [2, 3] return 0 }运行结果对应示例输出b3,c120,d2b99,g1,m2。这里展示了add(element, at:)指定索引插入、add(all: Collection, at:)批量插入、remove(at:)、slice(range)切片与下标赋值list[i] v的完整用法。4. TreeSet 与 HashSet有序 vs 无序来自 sample_treeset_add_iterator_remove.mdimport std.collection.* main() { var set: TreeSetString TreeSetString() set.add(peach) set.add(banana) set.add(apple) set.add(orange) var itset set.iterator() for (e in itset) { println(e) } set.remove(banana) println(set) return 0 }运行结果有序、去重apple banana orange peach [apple, orange, peach]而 sample_hashset_add_iterator_remove.md 中HashSet的遍历顺序不固定示例输出仅为其中一种可能两者对比可直观理解有序集合与哈希集合的语义差异。使用建议与注意事项综合包文档与类文档使用 collection 包时有以下几点需要留意按语义选型需要随机索引访问选ArrayList频繁在中间增删选LinkedList先进先出选ArrayQueue后进先出选ArrayStack两端操作选ArrayDeque快速键值查找选HashMap需要有序键值对/有序去重集合选TreeMap/TreeSet键与元素的约束HashMap/HashSet要求键/元素实现Hashable EquatableTreeMap/TreeSet要求键/元素实现Comparable。编译器会通过where约束在编译期检查遍历中不要修改容器除HashMapIterator.remove()外遍历过程中对容器增删改会触发ConcurrentModificationException关注扩容开销数组类容器在扩容时存在复制开销扩容策略为原始容量的 1.5 倍向下取整与需求量的较大者对容量敏感的场景可预先通过init(capacity)或reserve预留空间线程安全边界本包所有容器均非并发安全并发场景请使用标准库的并发集合包。完整 API 索引含每个类/接口/异常的 JSON 元数据位于 std/collection/collection_package_index需要查阅精确签名时可直接对照。赞分享人工智能AI 技能文档开发工具【免费下载链接】DocAgent项目地址https://gitcode.com/Cangjie-SIG/DocAgent点击查看免费下载相关推荐仓颉标准库 std.collection 集合包完全指南九大数据结构、接口体系与迭代器操作函数详解仓颉标准库 std.collection 集合包完全指南九大数据结构、接口体系与迭代器操作函数详解 std.collection 是仓颉编程语言标准库中最常用编程语言语言运行时标准库垃圾回收并发编程DocAgent 仓颉文档仓库 std.collection 集合框架深度指南九大数据结构、接口体系与迭代器函数实战DocAgent 仓颉文档仓库 std.collection 集合框架深度指南九大数据结构、接口体系与迭代器函数实战 本文以 DocAgent 仓颉语言文档仓人工智能AI 技能文档开发工具仓颉编程语言 std.collection 集合包详解常用数据结构、接口体系与迭代器高阶函数仓颉编程语言 std.collection 集合包详解常用数据结构、接口体系与迭代器高阶函数 std.collection 是仓颉编程语言标准库std中提文档知识库教程OpenHarmony上一篇terraform-provider-aws 数据源 aws_iam_user_ssh_key 实战读取 IAM 用户 SSH 公钥下一篇Vim 内置 EditorConfig 插件实战指南自动统一代码风格配置与核心实现解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考