Array Object

An Array object contains a list or sequence of values.

Values are addressed by their position within the array (known as an array index), where position 1 is the first element.

Arrays are often created by enclosing a list of values in brackets. For example:

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

A negative index can be used to address elements in reverse, so -1 is the last element, -2 is the second last element, and so on.

Attempting to use an array index which is out of bounds (such as zero, or if its absolute value is greater than the Length of the array) is considered an error and will cause an exception to be thrown. The best way to add new elements to the array is to call InsertAt or Push. For example:

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

An array can also be extended by assigning a larger value to Length. This changes which indices are valid, but Has will show that the new elements have no value. Elements without a value are typically used for variadic calls or by variadic functions, but can be used for any purpose.

The documentation below uses Arr as a placeholder for any Array object. Note that "array" should not be used as a variable name as it is used to refer to the Array class itself.

Array objects are based on Array.Prototype, which is based on Object.Prototype. In addition to the methods and property inherited from Object, Array objects have the following predefined methods and properties:

Methods:

Properties:

Functions:

Methods

Clone

Returns a shallow copy of the object.

Clone := Arr.Clone()

All array elements are copied to the new array. Object references are copied (like with a normal assignment), not the objects themselves.

Own properties, own methods and base are copied as per Obj.Clone.

Delete

Removes the value of an array element, leaving the index without a value.

Arr.Delete(Index)
Index

Type: Integer

A valid array index.

Return Value

The removed value.

Delete does not affect the Length of the array.

Has

Returns true if Index is valid and there is a value at that position, otherwise false.

Arr.Has(Index)

InsertAt

Inserts one or more values at a given position.

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

Type: Integer

The position to insert Value1 at. Subsequent values are inserted at Index+1, Index+2, etc.

Value1 ...

One or more values to insert. To insert an array of values, pass theArray* as the last parameter.

Remarks

InsertAt is the counterpart of RemoveAt.

Any items previously at or to the right of Index are shifted to the right. Missing parameters are also inserted, but without a value. For example:

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

; Missing elements are preserved:
x := ["A", , "C"]
x.InsertAt(2, "B")      ; =>  ["A", "B",    , "C"]

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

Pop

Removes and returns the last array element.

Value := Arr.Pop()

All of the following are equivalent:

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

If the array is empty (Length is 0), an exception is thrown.

Push

Appends values to the end of an array.

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

One or more values to insert. To insert an array of values, pass theArray* as the last parameter.

RemoveAt

Removes items from the array.

Arr.RemoveAt(Index , Length)
Index

Type: Integer

The index of the value or values to remove.

Length

Type: Integer

The length of the range of values to remove. If omitted, one item is removed.

Return Value

If Length is omitted, the removed value is returned (blank if none). Otherwise there is no return value.

Remarks

RemoveAt is the counterpart of InsertAt.

The range indicated by Index and Length must be valid (within the bounds of the array), but some elements can be missing values.

The remaining items to the right of Pos are shifted to the left by Length (or 1 if omitted). For example:

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

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

__New

Equivalent to Push. Usually not called directly.

Arr := Array.New(Value, Value2, ..., ValueN)

__Enum

Enumerates array elements.

For Value in Arr
For Index, Value in Arr

Returns a new enumerator. This method is typically not called directly. Instead, the array object is passed directly to a for-loop, which calls __Enum once and then calls the enumerator once for each iteration of the loop. Each call to the enumerator returns the next array element. The for-loop's variables correspond to the enumerator's parameters, which are:

Index

Type: Integer

The array index, typically the same as A_Index. This is present only in the two-parameter mode.

Value

The value (blank if none).

Properties

Length

Retrieves or sets the length of the array.

Length := Arr.Length
Arr.Length := Length

The length includes elements which have no value. Increasing the length changes which indices are considered valid, but the new elements have no value (as indicated by Has).

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

Capacity

Retrieves or sets the current capacity of the array.

Arr.Capacity := MaxItems
MaxItems := Arr.Capacity
MaxItems

Type: Integer

The maximum number of elements the array should be able to contain before it must be automatically expanded. If setting a value less than Length, elements are removed.

__Item

Retrieves or sets the value of an array element.

Value := Arr[Index]
Arr[Index] := Value
Index

Type: Integer

A valid array index; that is, an integer with absolute value between 1 and Length (inclusive).

A negative index can be used to address elements in reverse, so that -1 is the last element, -2 is the second last element, and so on.

Attempting to use an index which is out of bounds (such as zero, or if its absolute value is greater than the Length of the array) is considered an error and will cause an exception to be thrown.

The property name __Item is typically omitted, as shown above, but is used when overriding the property.

Functions

Array

Creates an Array containing the specified values.

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

If a function with this name is defined in the script, any array literals (such as []) within the same scope will produce calls to that function instead of the default Array function.