# Array 对象

    class Array extends Object

Array(数组) 对象包含值的列表或序列.

值由它们在数组中的位置(称为 数组索引) 来表示, 其中位置 1 是第一个元素.

数组通常是通过将值的列表括在方括号中来创建的. 例如:

    veg := ["Asparagus", "Broccoli", "Cucumber"]
    Loop veg.Length
        MsgBox veg[A_Index]

负索引可用于反向处理元素, 因此 -1 是最后一个元素, -2 是倒数第二个元素, 依此类推.

尝试使用超出范围的数组索引(例如零, 或者其绝对值大于数组的 Length) 被视为错误, 并将导致抛出 IndexError. 向数组添加新元素的最佳方法是调用 InsertAt 或 Push. 例如:

    users := Array()
    users.Push A_UserName
    MsgBox users[1]

也可以通过为 Length 指定更大的值来扩展数组. 这些索引是有效的, 但是 Has 将显示新元素没有值. 元素没有值通常用于可变参数调用或可变参数函数, 但也可以被用于任何目的.

下面使用 "ArrayObj" 作为任何数组对象的占位符, 因为 "Array" 就是类本身.

除了从 Object 继承的方法和属性外, Array 对象还具有以下预定义的方法和属性.

## 目录

- 静态方法:
  - Call: 创建一个包含指定值的新数组.
- 方法:
  - Clone: 返回对象的一个浅拷贝.
  - Delete: 删除数组元素的值, 使索引不包含值.
  - Get: 返回给定索引的值或默认值.
  - Has: 如果 Index 有效且在该位置有一个值, 则返回 true.
  - InsertAt: 插入一个或多个值到给定位置.
  - Pop: 删除并返回最后的数组元素.
  - Push: 追加值到数组的末尾.
  - RemoveAt: 从数组中移除项目.
  - __New: 追加项目. 等同于 Push.
  - __Enum: 枚举数组元素.
- 属性:
  - Length: 检索或设置数组的长度.
  - Capacity: 检索或设置数组的当前容量.
  - Default: 定义了当请求一个没有值的元素时返回的默认值.
  - __Item: 检索或设置数组元素的值.

## 静态方法

### Call

创建一个包含指定值的新数组.

    ArrayObj := Array(Value, Value2, ..., ValueN)

参数由 __New 定义.

## 方法

### Clone

返回对象的一个浅拷贝.

    Clone := ArrayObj.Clone()

所有数组元素都被复制到新数组. 对象 引用 被复制(就像普通的赋值一样), 而不是对象本身.

根据 Obj.Clone 来复制自有的属性, 方法和基.

### Delete

删除数组元素的值, 使索引不包含值.

    ArrayObj.Delete(Index)

Index

  类型: 整数

  一个有效的数组索引.

返回删除的值(如果没有, 则为空).

Delete 不影响数组的 Length(长度).

如果 Index 超出范围, 则抛出 ValueError.

### Get

返回给定索引处的值, 或默认值.

    Value := ArrayObj.Get(Index , Default)

该方法执行如下操作:

- 如果 Index 为零或超出范围, 则抛出 IndexError.
- 返回 Index 处的值, 如果有(请参阅 Has).
- 如果指定, 则返回 Default 参数的值.
- 如果定义, 则返回 `ArrayObj.Default` 的值.
- 抛出 UnsetItemError.

当 Default 被省略时, 它等价于 `ArrayObj[Index]`, 除了没有调用 __Item.

### Has

如果 Index 有效且在该位置有一个值, 则返回 true, 否则返回 false.

    ArrayObj.Has(Index)

### InsertAt

插入一个或多个值到给定位置.

    ArrayObj.InsertAt(Index, Value1 , Value2, ... ValueN)

Index

  类型: 整数

  插入 Value1 的位置. 随后的值插入到 Index+1, Index+2, 以此类推. 指定 0 为索引等同于指定 Length + 1.

Value1 ...

  要插入的一个或多个值. 要插入数组值, 请将 `theArray*` 作为最后一个参数传递.

InsertAt 对应 RemoveAt.

先前位于 Index 的项目或 Index 右侧的所有项目都移到右侧. 缺失的参数也会被插入, 但没有值. 例如:

    x := []
    x.InsertAt(1, "A", "B") ; =>  ["A", "B"]
    x.InsertAt(2, "C")      ; =>  ["A", "C", "B"]

    ; 缺失的元素将保留:
    x := ["A", , "C"]
    x.InsertAt(2, "B")      ; =>  ["A", "B",    , "C"]

    x := ["C"]
    x.InsertAt(1, , "B")    ; =>  [   , "B", "C"]

如果 Index 小于 `-ArrayObj.Length` 或大于 `ArrayObj.Length + 1`, 则抛出 ValueError. 例如, 对于一个包含 3 个项目的数组, Index 必须介于-3 和 4 之间(包含).

### Pop

删除并返回最后的数组元素.

    Value := ArrayObj.Pop()

下面这些都是等同的:

    Value := ArrayObj.Pop()
    Value := ArrayObj.RemoveAt(ArrayObj.Length)
    Value := ArrayObj.RemoveAt(-1)

如果数组为空(Length 为 0), 则抛出 Error.

### Push

追加值到数组的末尾.

    ArrayObj.Push(Value, Value2, ..., ValueN)

Value ...

  要插入一个或多个值. 要插入数组值, 请将 `theArray*` 作为最后一个参数传递.

### RemoveAt

从数组中移除项目.

    ArrayObj.RemoveAt(Index , Length)

Index

  类型: 整数

  要删除的值的索引.

Length

  类型: 整数

  要删除的值的范围的长度. 如果省略, 则删除一项.

如果省略 Length, 返回删除的值(如果没有, 则返回空值). 否则就没有返回值.

RemoveAt 对应 InsertAt.

如果 Index 和 Length 所表示的范围不完全在数组的当前范围内, 则抛出 ValueError.

Pos 侧的其余项将根据 Length 向左移动(如果省略则为 1). 例如:

    x := ["A", "B"]
    MsgBox x.RemoveAt(1)  ; A
    MsgBox x[1]           ; B

    x := ["A", , "C"]
    MsgBox x.RemoveAt(1, 2)  ; 空值
    MsgBox x[1]              ; C

### __New

追加项目. 等同于 Push.

    ArrayObj.__New(Value, Value2, ..., ValueN)

这个方法是为了支持 Call 而存在的, 并不打算直接调用. 请参阅构造和销毁.

### __Enum

枚举数组元素.

    For Value in ArrayObj

    For Index, Value in ArrayObj

返回一个新的枚举器. 该方法通常不直接调用. 而是将数组对象被直接传递给 for-loop, 其调用一次 __Enum 然后循环的每次迭代都调用一次枚举器. 每次对枚举器的调用都会返回下一个数组元素. for-loop 的变量对应于枚举器的参数, 它们是:

Index

  类型: 整数

  数组索引, 通常与 A_Index 相同. 其仅在两参数模式下存在.

Value

  值(如果没有, 则 Value 为未初始化值).

## 属性

### Length

检索或设置数组的长度.

    Length := ArrayObj.Length

    ArrayObj.Length := Length

长度包含没有值的元素. 因增加长度而产生的索引是有效的, 但是新元素没有值(由 Has 反映出来). Decreasing the length truncates the array.

    MsgBox ["A", "B", "C"].Length  ;  3
    MsgBox ["A",    , "C"].Length  ;  3

### Capacity

检索或设置数组的当前容量.

    ArrayObj.Capacity := MaxItems

    MaxItems := ArrayObj.Capacity

MaxItems

  类型: 整数

  在必须自动扩展前, 数组可以包含最大元素数量. 如果设置的值小于 Length, 则删除多的元素.

    x := ["A", "B", "C"]
    x.push("D")
    MsgBox  x.Capacity  ;  6

    x := ["A", "B", "C"]
    x.push("D", "E", "F", "G")
    MsgBox  x.Capacity  ;  7

### Default

定义请求没有值的元素时返回的默认值.

    ArrayObj.Default := Value

默认情况下, 该属性实际上不存在, 但是可以由脚本定义. 当脚本请求一个没有值的元素时, 数组在抛出 UnsetItemError 之前检查该属性. 它可以通过任何常规方法实现, 包括动态属性或元函数, 但要确定查询的是哪个键, 则需要重写 __Item 或 Get.

设置默认值并不会在索引超出范围时防止抛出错误.

### __Item

检索或设置数组元素的值.

    Value := ArrayObj[Index]

    ArrayObj[Index] := Value

Index

  类型: 整数

  一个有效的数组索引; 也就是说, 一个绝对值在 1 和 Length(包括) 之间的整数.

  负索引可用于反向处理元素, 因此 -1 是最后一个元素, -2 是倒数第二个元素, 依此类推.

  尝试使用超出范围的数组索引(例如零, 或者其绝对值大于数组的 Length(长度)) 被视为错误, 并将导致抛出 IndexError.

如上所示, 属性名 __Item 通常被省略, 但在覆盖属性时使用.

dftg