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

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

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)

该方法执行如下操作:

当 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