Arrays

In AutoHotkey, there are two different types of things that are related to arrays:

• Object-based Arrays
• Pseudo-Arrays (not recommended for use)

Note: The following code examples show different approaches which lead to the same end result.

Object-based Arrays [AHK_L 31+]

Such arrays can be associative arrays or simple arrays. Associative arrays are created using the Object function or the brace syntax, while simple arrays are created using the array function or bracket syntax. For more information, see the AutoHotkey Beginner Tutorial or the Objects page.

The following example shows the usage of a simple array:

; Create the array, initially empty:
Array := [] ; or Array := Array()

; Write to the array:
Loop, Read, %A_WinDir%\system.ini ; This loop retrieves each line from the file, one at a time.
{
    Array.Push(A_LoopReadLine) ; Append this line to the array.
}

; Read from the array:
; Loop % Array.MaxIndex()   ; More traditional approach.
for index, element in Array ; Enumeration is the recommended approach in most cases.
{
    ; Using "Loop", indices must be consecutive numbers from 1 to the number
    ; of elements in the array (or they must be calculated within the loop).
    ; MsgBox % "Element number " . A_Index . " is " . Array[A_Index]

    ; Using "for", both the index (or "key") and its associated value
    ; are provided, and the index can be *any* value of your choosing.
    MsgBox % "Element number " . index . " is " . element
}

This shows only a small subset of the functionality provided by objects. Items can be set, retrieved, inserted, removed and enumerated. Strings and objects can be used as keys in addition to numbers. Objects can be stored as values in other objects and passed as function parameters or return values. Objects can also be extended with new functionality.

Though Push() and enumerators have their uses, some users might find it easier to use the more traditional approach (the commented out lines are the counterparts using the pseudo-arrays described below):

  ; Each array must be initialized before use:
  Array := []

; Array%j% := A_LoopField
  Array[j] := A_LoopField

; Array%j%_%k% := A_LoopReadLine
  Array[j, k] := A_LoopReadLine

  ArrayCount := 0
  Loop, Read, %A_WinDir%\system.ini
  {
      ArrayCount += 1
    ; Array%ArrayCount% := A_LoopReadLine
      Array[ArrayCount] := A_LoopReadLine
  }

  Loop % ArrayCount
  {
    ; element := Array%A_Index%
      element := Array[A_Index]
    ; MsgBox % "Element number " . A_Index . " is " . Array%A_Index%
      MsgBox % "Element number " . A_Index . " is " . Array[A_Index]
  }

ArrayCount is left as a variable for convenience, but can be stored in the array itself with Array.Count := n or it can be removed and Array.MaxIndex() used in its place. If a starting index other than 1 is desired, Array.MinIndex() can also be used.

Pseudo-Arrays

Note: If possible, always use the object-based array mentioned above. It is superior to a pseudo-array in almost every aspect: it is space-saving, more flexible, clearer, and similar to many other programming languages.

Pseudo-arrays are mostly conceptual: Each array is really just a collection of sequentially numbered variables or functions, each one being perceived as an element of the array. AutoHotkey does not link these elements together in any way.

In addition to array-creating commands like StringSplit and WinGet List, any command that accepts an OutputVar or that assigns a value to a variable can be used to create an array. The simplest example is the assignment operator (:=), as shown below:

Array%j% := A_LoopField

Multidimensional arrays are possible by using a separator character of your choice between the indices. For example:

Array%j%_%k% := A_LoopReadLine

The following example demonstrates how to create and access an array, in this case a series of names retrieved from a text file:

; Write to the array:
ArrayCount = 0
Loop, Read, %A_WinDir%\system.ini   ; This loop retrieves each line from the file, one at a time.
{
    ArrayCount += 1  ; Keep track of how many items are in the array.
    Array%ArrayCount% := A_LoopReadLine  ; Store this line in the next array element.
}

; Read from the array:
Loop %ArrayCount%
{
    ; The following line uses the := operator to retrieve an array element:
    element := Array%A_Index%  ; A_Index is a built-in variable.
    ; Alternatively, you could use the "% " prefix to make MsgBox or some other command expression-capable:
    MsgBox % "Element number " . A_Index . " is " . Array%A_Index%
}

A concept related to arrays is the use of NumPut() and NumGet() to store/retrieve a collection of numbers in binary format. This might be helpful in cases where performance and/or memory conservation are important.