class Array extends 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 IndexError 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.
"ArrayObj" is used below as a placeholder for any Array object, as "Array" is the class itself.
In addition to the methods and property inherited from Object, Array objects have the following predefined methods and properties.
Creates a new Array containing the specified values.
ArrayObj := Array(Value, Value2, ..., ValueN) ArrayObj := Array.Call(Value, Value2, ..., ValueN)
Parameters are defined by __New.
Returns a shallow copy of an array.
Clone := ArrayObj.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.
Removes the value of an array element, leaving the index without a value.
RemovedValue := ArrayObj.Delete(Index)
Type: Integer
A valid array index.
Type: Any
This method returns the removed value (blank if none).
This method does not affect the Length of the array.
A ValueError is thrown if Index is out of range.
Returns the value at a given index, or a default value.
Value := ArrayObj.Get(Index , Default)
This method does the following:
ArrayObj.Default, if defined.When Default is omitted, this is equivalent to ArrayObj[Index], except that __Item is not called.
Returns a non-zero number if the index is valid and there is a value at that position.
HasIndex := ArrayObj.Has(Index)
Inserts one or more values at a given position.
ArrayObj.InsertAt(Index, Value1 , Value2, ... ValueN)
Type: Integer
The position to insert Value1 at. Subsequent values are inserted at Index+1, Index+2, etc. Specifying an index of 0 is the same as specifying Length + 1.
Type: Any
One or more values to insert. To insert an array of values, pass theArray* as the last parameter.
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"]
A ValueError is thrown if Index is less than -ArrayObj.Length or greater than ArrayObj.Length + 1. For example, with an array of 3 items, Index must be between -3 and 4, inclusive.
Removes and returns the last array element.
RemovedValue := ArrayObj.Pop()
All of the following are equivalent:
RemovedValue := ArrayObj.Pop() RemovedValue := ArrayObj.RemoveAt(ArrayObj.Length) RemovedValue := ArrayObj.RemoveAt(-1)
Appends values to the end of an array.
ArrayObj.Push(Value, Value2, ..., ValueN)
Removes items from an array.
RemovedValue := ArrayObj.RemoveAt(Index) ArrayObj.RemoveAt(Index, Length)
Type: Integer
The index of the value or values to remove.
Type: Integer
If omitted, one item is removed. Otherwise, specify the length of the range of values to remove.
Type: Any
If Length is omitted, the removed value is returned (blank if none). Otherwise there is no return value.
RemoveAt is the counterpart of InsertAt.
A ValueError is thrown if the range indicated by Index and Length is not entirely within the array's current bounds.
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
Appends items. Equivalent to Push.
ArrayObj.__New(Value, Value2, ..., ValueN)
This method exists to support Call, and is not intended to be called directly. See Construction and Destruction.
Enumerates array elements.
For Value in ArrayObj
For Index, Value in ArrayObj
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:
Type: Integer
The array index, typically the same as A_Index. This is present only in the two-parameter mode.
Type: Any
The value (if there is no value, Value becomes uninitialized).
Retrieves or sets the length of an array.
Length := ArrayObj.Length
ArrayObj.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). Decreasing the length truncates the array.
MsgBox ["A", "B", "C"].Length ; 3 MsgBox ["A", , "C"].Length ; 3
Retrieves or sets the current capacity of an array.
MaxItems := ArrayObj.Capacity
ArrayObj.Capacity := MaxItems
MaxItems is an integer representing 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.
Defines the default value returned when an element with no value is requested.
ArrayObj.Default := Value
This property actually doesn't exist by default, but can be defined by the script. If defined, its value is returned by __Item or Get if the requested element has no value, instead of throwing an UnsetItemError. It can be implemented by any of the normal means, including a dynamic property or meta-function, but determining which key was queried would require overriding __Item or Get instead.
Setting a default value does not prevent an error from being thrown when the index is out of range.
Retrieves or sets the value of an array element.
Value := ArrayObj[Index]
Value := ArrayObj.__Item[Index]
ArrayObj[Index] := Value
ArrayObj.__Item[Index] := Value
Index is an integer representing 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 IndexError to be thrown.
The property name __Item is typically omitted, as shown above, but is used when overriding the property.