cangjie-std-arraylist

name	cangjie-std-arraylist
description	仓颉标准库 ArrayList 类型详细指南。当需要了解 ArrayList 的构造、增删改查、容量管理、切片、排序、迭代、与 Array 互转等操作的完整 API 和用法时，应使用此 Skill。

仓颉标准库 ArrayList 类型 Skill

1. 概述

ArrayList<T> 是 std.collection 包中的 class 类型，使用前需导入：

import std.collection.*

• 动态数组 — 可自动扩容，无需预先指定大小
• 引用类型 — let list2 = list1 后两者共享数据，修改互相可见
• 实现接口：List<T>（继承 Collection<T>、Iterable<T>）
• T 可以是任意类型

---

2. 构造

import std.collection.*

// 空 ArrayList（默认容量 16）
let list = ArrayList<Int64>()

// 指定初始容量
let list2 = ArrayList<Int64>(100)

// 从 Array 字面量构造
let list3 = ArrayList<Int64>([1, 2, 3])

// 从其他 Collection 构造
let list4 = ArrayList<Int64>(otherCollection)

// 指定大小 + 初始化函数
let list5 = ArrayList<Int64>(5, {i => i * 10})  // [0, 10, 20, 30, 40]

// 使用 of 静态方法（支持变长参数语法）
let list6 = ArrayList.of(1, 2, 3)

构造函数签名

构造函数	说明
init()	空 ArrayList，默认容量 16
init(capacity: Int64)	空 ArrayList，指定容量。capacity < 0 抛 IllegalArgumentException
init(elements: Collection<T>)	包含指定集合所有元素
init(size: Int64, initElement: (Int64) -> T)	指定大小 + 初始化函数。size < 0 抛 IllegalArgumentException
static func of(elements: Array<T>): ArrayList<T>	从数组创建

---

3. 属性

属性	类型	说明
size	Int64	元素个数
capacity	Int64	当前容量
first	?T	首元素，空时为 None
last	?T	尾元素，空时为 None

let list = ArrayList<Int64>([10, 20, 30])
println(list.size)      // 3
println(list.capacity)  // >= 3
println(list.first)     // Some(10)
println(list.last)      // Some(30)

---

4. 元素访问

4.1 下标访问

let list = ArrayList<Int64>([10, 20, 30])
let v = list[0]    // 10
list[1] = 99       // [10, 99, 30]

• 索引从 0 开始，类型为 Int64
• 越界抛出 IndexOutOfBoundsException

4.2 安全访问 get

func get(index: Int64): ?T

list.get(1)   // Some(99)
list.get(10)  // None（不抛异常）

4.3 范围下标（切片）

let list = ArrayList<Int64>([0, 1, 2, 3, 4])
let sub = list[1..4]  // ArrayList [1, 2, 3]

---

5. 添加元素

5.1 尾部追加

func add(element: T): Unit
func add(all!: Collection<T>): Unit

let list = ArrayList<Int64>()
list.add(1)                          // [1]
list.add(2)                          // [1, 2]
list.add(all: [3, 4, 5])            // [1, 2, 3, 4, 5]
list.add(all: otherArrayList)        // 追加另一个集合的元素

5.2 在指定位置插入

func add(element: T, at!: Int64): Unit
func add(all!: Collection<T>, at!: Int64): Unit

let list = ArrayList<Int64>([1, 2, 3])
list.add(99, at: 1)                  // [1, 99, 2, 3]
list.add(all: [77, 88], at: 0)      // [77, 88, 1, 99, 2, 3]

• at 越界抛出 IndexOutOfBoundsException

---

6. 删除元素

6.1 按索引删除

func remove(at!: Int64): T

let list = ArrayList<Int64>([10, 20, 30, 40])
let removed = list.remove(at: 1)  // removed = 20, list = [10, 30, 40]

• 越界抛出 IndexOutOfBoundsException

6.2 按范围删除

func remove(range: Range<Int64>): Unit

let list = ArrayList<Int64>([0, 1, 2, 3, 4])
list.remove(1..3)  // [0, 3, 4]

• range.step 必须为 1，否则抛 IllegalArgumentException

6.3 按条件删除

func removeIf(predicate: (T) -> Bool): Unit

let list = ArrayList<Int64>([1, 2, 3, 4, 5, 6])
list.removeIf { v => v % 2 == 0 }  // [1, 3, 5]

• 在 predicate 中修改 ArrayList 会抛 ConcurrentModificationException

6.4 清空

func clear(): Unit

list.clear()  // size = 0

---

7. 容量管理

ArrayList 在元素超过容量时会自动扩容（重新分配内存 + 复制元素），频繁扩容会影响性能。

7.1 构造时预分配

let list = ArrayList<Int64>(1000)  // 预分配容量 1000

7.2 运行时扩容

func reserve(additional: Int64): Unit

list.reserve(500)  // 额外增加 500 的容量

• 当 additional + 已使用容量 超过 Int64.Max 时抛 OverflowException

---

8. 切片

func slice(range: Range<Int64>): ArrayList<T>

let list = ArrayList<Int64>([0, 1, 2, 3, 4])
let sub = list.slice(1..=3)  // [1, 2, 3]（新 ArrayList）

• range.step 必须为 1，否则抛 IllegalArgumentException
• 越界抛 IndexOutOfBoundsException

---

9. 反转

func reverse(): Unit

let list = ArrayList<Int64>([1, 2, 3])
list.reverse()  // [3, 2, 1]

---

10. 拷贝

func clone(): ArrayList<T>

let list = ArrayList<Int64>([1, 2, 3])
let copy = list.clone()
copy[0] = 999
println(list[0])  // 1（不受影响，浅拷贝但各自独立存储）

---

11. 转换

11.1 转为 Array

func toArray(): Array<T>

let list = ArrayList<Int64>([1, 2, 3])
let arr: Array<Int64> = list.toArray()  // [1, 2, 3]

11.2 转为字符串（需要 T <: ToString）

func toString(): String

ArrayList<Int64>([1, 2, 3]).toString()  // "[1, 2, 3]"

---

12. 判空与包含

func isEmpty(): Bool

ArrayList<Int64>().isEmpty()  // true

12.1 contains（需要 T <: Equatable）

func contains(element: T): Bool

let list = ArrayList<Int64>([1, 2, 3])
list.contains(2)  // true
list.contains(5)  // false

---

13. 相等比较（需要 T <: Equatable）

let a = ArrayList<Int64>([1, 2, 3])
let b = ArrayList<Int64>([1, 2, 3])
let c = ArrayList<Int64>([1, 2, 4])
a == b  // true
a != c  // true

---

14. 迭代

func iterator(): Iterator<T>

import std.collection.*

let list = ArrayList<String>(["a", "b", "c"])

// for-in 遍历
for (item in list) {
    println(item)
}

// 函数式操作（通过迭代器）
let result = list
    |> filter { s => s != "b" }
    |> map { s => s.toAsciiUpper() }
    |> collectArrayList
// result = ["A", "C"]

---

15. 排序

15.1 使用 std.sort（推荐）

import std.sort.*
import std.collection.*

let list = ArrayList<Int64>([3, 1, 4, 1, 5])
sort(list)  // [1, 1, 3, 4, 5]

15.2 内置排序方法（已废弃）

// 以下方法已废弃，建议使用 std.sort
list.sort()                                          // 升序（T 须 <: Comparable）
list.sortDescending()                                // 降序
list.sortBy(comparator: { a, b => b - a })          // 自定义比较器
list.sortBy(stable: true, comparator: { a, b => a - b }) // 稳定排序

---

16. 常见用法总结

import std.collection.*

// 1. 动态收集元素
let results = ArrayList<String>()
for (item in source) {
    if (isValid(item)) {
        results.add(item.toString())
    }
}

// 2. 批量添加
let list = ArrayList<Int64>()
list.add(all: [1, 2, 3])
list.add(all: moreItems)

// 3. 安全访问
if (let Some(v) <- list.get(index)) {
    process(v)
}

// 4. 条件过滤删除
list.removeIf { v => v < 0 }

// 5. 从 Array 创建 → 操作 → 转回 Array
let arr = [3, 1, 2]
let list = ArrayList<Int64>(arr)
sort(list)
let sorted = list.toArray()  // [1, 2, 3]

// 6. 遍历并修改
for (i in 0..list.size) {
    list[i] = list[i] * 2
}

// 7. 预分配避免扩容开销
let bigList = ArrayList<Int64>(10000)
for (i in 0..10000) {
    bigList.add(i)
}