人工智能AI 技能文档开发工具【免费下载链接】DocAgent项目地址https://gitcode.com/Cangjie-SIG/DocAgent点击查看免费下载本文基于 Cangjie 标准库std.collection包中ArrayQueueT的官方 API 文档与仓库内配套的接口、函数文档系统讲解该基于数组实现的循环队列的构造方式、容量增长策略、全部成员函数与ToString拓展接口并通过可运行的 Cangjie 代码示例演示先进先出FIFO队列在任务调度、消息缓存等场景中的实战用法。读完本文你将能正确选择初始容量、理解reserve扩容边界、熟练使用add/remove/peek组合完成队列的入队出队操作并知晓在遍历过程中修改队列可能引发的异常。ArrayQueue 在 std.collection 中的定位ArrayQueueT是std.collection包提供的核心数据结构之一该包在仓库中的完整介绍见 std/collection/collection_package_overview.md。根据包总览ArrayQueue是基于数组实现的循环队列只允许在尾部插入元素、在头部删除元素与同为数组实现的 ArrayDeque双端循环队列两端均可插入删除和 ArrayStack后进先出栈形成互补。在仓库 API 文档中ArrayQueueT的类声明为public class ArrayQueueT : QueueT { public init() public init(capacity: Int64) }类声明出处std/collection/collection_package_api/collection_package_class.md。其父类型是 QueueT 接口该接口定义了队列的三大核心操作契约public interface QueueT : CollectionT { func add(element: T): Unit // 在队列尾部插入元素 func peek(): ?T // 访问队列头部元素不删除 func remove(): ?T // 删除队列头部元素并返回 }接口定义出处std/collection/collection_package_api/collection_package_interface.md。可以看到ArrayQueue完整遵循先进先出First In First Out, FIFO语义入队从尾部、出队从头部这与QueueT接口的设计意图完全一致。注意与仓库其他 collection 容器一样ArrayQueue不支持并发安全。若需要并发安全的集合应使用 collection.concurrent 包见包总览中的说明。构造函数默认容量与指定容量ArrayQueue提供两个构造函数均已在官方类文档中列出见 ArrayQueue_class.md名称原型说明init()构造一个空的队列其容量大小为默认值 8。init(capacity: Int64)构造一个具有指定容量的队列当 capacity 小于默认容量 8 时构造的 ArrayQueue 初始容量为 8。使用要点无参构造直接获得容量为 8 的空队列适合元素数量不可预估的通用场景带容量构造适合能预估峰值数据量的场景可减少后续扩容带来的复制开销容量下限保护传入的capacity小于 8 时实际初始容量仍为 8不会产生容量小于默认值的队列参数异常当传入的capacity小于 0 时构造函数会抛出 IllegalArgumentException参数非法异常该异常类表示参数非法是 core 包中常见的参数校验异常。成员函数入队、出队与容量管理ArrayQueue共提供 9 个成员函数与 2 个只读属性下表完整列出出处ArrayQueue_class.md名称原型说明prop capacitypublic prop capacity: Int64获取此队列的容量。prop sizepublic prop size: Int64返回此队列中的元素个数。add(element: T): Unit在此队列尾部插入元素。clear(): Unit清空此队列中的所有元素。iterator(): IteratorT获取此队列中元素的迭代器其顺序为从前到后的顺序。isEmpty(): Bool判断此队列是否为空。peek():?T查看此队列头部元素。此操作不会删除元素。remove(): ?T删除队列中的头部元素并返回该值如果此队列为空返回 None。reserve(additional: Int64): Unit增加此队列的容量。toArray(): ArrayT返回一个数组其包含此队列中的所有元素且顺序为从前到后的顺序。入队与出队add / remove / peekadd(element)FIFO 入队操作元素追加到队列尾部返回值类型为Unitremove()FIFO 出队操作从头部删除元素并返回其值。返回类型为可空类型?T即 OptionT队列为空时返回None而不是抛出异常——这是使用remove时最需要留意的语义取出的值需先判空或通过Option的getOrThrow()/getOrDefault()处理peek()仅查看头部元素而不删除同样返回?T空队列返回None。peek与remove的区别在于是否消费元素是只看不出队的典型实现。?T与OptionT等价Option枚举提供Some/None两个构造器及getOrThrow()、getOrDefault()、isSome()、isNone()等成员详见 Option_enum.md可安全解包队列返回的可空值。容量与状态查询capacity / size / isEmptycapacity当前队列的容量底层数组可容纳的元素总数创建时由构造函数决定插入过程中可按需增长size当前队列中实际元素个数isEmpty()判断队列是否为空等价于size 0的语义。当队列被排空所有元素均被remove后容量不会自动缩小队列实例可继续复用capacity保持已扩大的值。清空与转换clear / toArray / iteratorclear()一次性清空队列中所有元素元素个数归零容量保持不变toArray()返回包含队列全部元素的ArrayT元素顺序为从前到后即 FIFO 出队顺序iterator()返回从前到后遍历的 IteratorT可用于for-in循环或链式调用filter/map/forEach等迭代器方法。预分配容量reserve 的扩容规则reserve(additional: Int64)用于按需预分配容量其扩容规则在 collection_package_class.md 中有精确描述当additional小于等于零时不发生扩容当队列剩余容量大于等于additional时不发生扩容当队列剩余容量小于additional时取**原始容量的 1.5 倍向下取整与additional 已使用容量两个值中的最大值**进行扩容。这一策略与包内 ArrayDeque 的reserve规则一致既保证能容纳additional个新元素又避免频繁小幅扩容导致的反复复制开销。在已知下一批数据规模时提前调用reserve可以有效减少插入过程中的隐式扩容次数。拓展接口ToString 字符串化ArrayQueueT在满足约束T : ToString元素类型实现了 ToString 接口时会自动获得字符串表示能力extendT ArrayQueueT : ToString where T : ToString该拓展接口提供toString(): String成员返回队列的字符串表示顺序为从前到后格式形如[elem1, elem2, elem3]例如包含整数 1、2、3 的队列调用toString()得到[1, 2, 3]。ToString接口本身定义于 core 包用于提供具体类型的字符串表示见 ToString_interface.md因此ArrayQueue可直接参与字符串拼接与println输出。FIFO 实战完整的队列使用示例下面结合仓库中 collection 包的示例代码风格参见 sample_arraylist_add.md 与 sample_iterator.md均使用import std.collection.*并可在main()中运行给出ArrayQueue的完整可运行示例import std.collection.* main() { // 1. 构造一个容量为 4 的 Int64 队列 var queue: ArrayQueueInt64 ArrayQueueInt64(4) println(初始容量${queue.capacity}, size${queue.size}, isEmpty${queue.isEmpty()}) // 2. 入队尾部依次插入 10, 20, 30 queue.add(10) queue.add(20) queue.add(30) println(入队后 size${queue.size}, 头部${queue.peek()}) // peek 不删除元素 // 3. 出队头部删除验证 FIFO 顺序 var head queue.remove() // 10 println(第一次出队${head.getOrThrow()}) println(第二次出队${queue.remove().getOrThrow()}) // 20 // 4. 查看剩余元素与字符串表示 println(队列剩余${queue.toString()}) // 形如 [30] var arr queue.toArray() println(toArray 长度${arr.size}) // 1 // 5. 空队列出队返回 None queue.clear() var none queue.remove() println(空队列 remove 结果${none}) // 输出 None // 6. 预分配容量减少后续扩容 queue.reserve(100) println(reserve 后容量${queue.capacity}) // 7. 迭代器从前到后遍历 queue.add(1) queue.add(2) for (elem in queue) { print(${elem} ) } println() return 0 }示例要点说明queue.remove()返回?T使用getOrThrow()解包当确认队列非空时可安全调用空队列的remove()与peek()均返回None代码中直接打印得到Nonereserve(100)会触发扩容由于剩余容量小于 100取max(原容量 × 1.5 向下取整, 100 已使用容量)作为新容量迭代器for (elem in queue)依赖iterator()返回的前到后顺序。遍历期间的修改约束需要特别注意仓库文档在 collection_package_exception.md 中明确说明collection 包提供的容器类均不支持并发修改。在使用for-in遍历ArrayQueue的过程中对队列进行增删操作会抛出 ConcurrentModificationException并发修改异常类。如果需要在遍历中筛选或删除元素建议先通过toArray()或迭代器链式操作如filter生成新集合再对原队列执行clear()或重建避免触发异常。总结ArrayQueueT是 Cangjiestd.collection包中基于数组实现的循环队列具有以下关键特征FIFO 语义尾部入队add、头部出队removepeek提供不消费的头部查看容量管理默认容量 8构造时低于 8 会被抬升到 8reserve按1.5 倍取整与 additional 已使用容量取最大值的规则扩容可空返回remove/peek返回?T空队列返回None需配合Option的getOrThrow/getOrDefault使用遍历与转换iterator/toArray/toString均遵循从前到后的顺序toString需元素实现ToString非并发安全遍历中修改会抛出ConcurrentModificationException并发场景请选择collection.concurrent包。上述 API 的权威出处集中在 ArrayQueue_class.md、collection_package_class.md、Queue_interface.md 与 collection_package_overview.md 等文档中读者可据此继续深入查阅std.collection包其余数据结构如 ArrayDeque、ArrayList、ArrayStack的实现细节。赞分享人工智能AI 技能文档开发工具【免费下载链接】DocAgent项目地址https://gitcode.com/Cangjie-SIG/DocAgent点击查看免费下载相关推荐仓颉标准库 std.collection 队列接口 Queue\T 详解FIFO 语义与 ArrayQueue 循环数组实现仓颉标准库 std.collection 队列接口 Queue\T 详解FIFO 语义与 ArrayQueue 循环数组实现 本文围绕 Cangjie 标准人工智能AI 技能文档开发工具Cangjie std.collection LinkedListNode\T 详解链表节点的遍历、取值与生命周期管理Cangjie std.collection LinkedListNode\T 详解链表节点的遍历、取值与生命周期管理 导读 LinkedListNode人工智能AI 技能文档开发工具Hello 算法ArrayQueue 循环数组队列的 Python 实现与逐步执行解析Hello 算法ArrayQueue 循环数组队列的 Python 实现与逐步执行解析 本篇基于《Hello 算法》俄文版仓库中的 PythonTutor 可教程文档示例工程教育创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
