Array Object

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.

Table of Contents

Static Methods

Call

Creates a new Array containing the specified values.

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

Parameters are defined by __New.

Methods

Clone

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.

Delete

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

ArrayObj.Delete(Index)
Index

Type: Integer

A valid array index.

Returns the removed value (blank if none).

Delete does not affect the Length of the array.

A ValueError is thrown if Index is out of range.

Get

Returns the value at a given index, or a default value.

Value := ArrayObj.Get(Index , Default)

This method does the following:

When Default is omitted, this is equivalent to ArrayObj[Index], except that __Item is not called.

Has

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

ArrayObj.Has(Index)

InsertAt

Inserts one or more values at a given position.

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

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.

Value1 ...

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.

Pop

Removes and returns the last array element.

Value := ArrayObj.Pop()

All of the following are equivalent:

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

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

Push

Appends values to the end of an array.

ArrayObj.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 an array.

ArrayObj.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.

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

__New

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.

__Enum

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:

Index

Type: Integer

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

Value

The value (if there is no value, Value becomes uninitialized).

Properties

Length

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

Capacity

Retrieves or sets the current capacity of an array.

ArrayObj.Capacity := MaxItems
MaxItems := ArrayObj.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.

Default

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. When the script requests an element which has no value, the array checks for this property before 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.

__Item

Retrieves or sets the value of an array element.

Value := ArrayObj[Index]
ArrayObj[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 IndexError to be thrown.

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