An Array is a list of items of varying variable types. Different types can coexist within the same array. An Array can either be one-dimensional or multi-dimensional.
See also: Arrays
Working with arrays
An array variable is a reference to the array (see Wikipedia reference page); this means that if the array is edited, all the scripts/functions using a reference to this array will see the edition.
An array set through setVariable does not need to be assigned again if you modify it by reference:
Create an array
An array can hold another array within it, that can hold another array itself, etc:
Getting an element
An array uses a zero-based index for its elements:
Setting an element
Changing array size
The resize command is made to reduce or expand an array:
In order to avoid this behaviour, copy the array with + (plus):
Sub-arrays are also deep-copied; _myNewArray will not point at the same sub-array instances.
Adding (appending) elements
Removing (deleting) elements
In Arma 3 it became possible to also subtract nested arrays:
The subtraction will remove all elements of second array from the first array:
The solution to this issue is the combined use of set and an item that you know is not present in the array:
Using this technique, it is possible to mimic deleteRange behaviour this way:
Going through the array
The simplest way to iterate through an array is the forEach command:
A simple way to filter an array (and obtain a new one) is using select's alternative syntax:
The findIf command was introduced in Arma 3 and allows you to go through the whole list and stop as soon as the condition is met, returning the condition-meeting element's array index:
The arrayIntersect command returns a new array filled with the items found in both provided lists:
You can remove duplicates (get unique items) with this command:
Be wary that nil elements get removed by this method:
Sorting an array
The reverse command simply reverses the array order:
The function BIS_fnc_sortBy has been created for more complex sorting. Its algorithm input must return a number:
In Arma scripts, indices are rounded to the nearest whole number. A boundary case (X.5, where X is any whole number) rounds to the nearest even whole number.
- Boundary cases
- -0.5 <= index <= 0.5 rounds to 0
- 0.5 < index < 1.5 rounds to 1
- 1.5 <= index <= 2.5 rounds to 2
- 2.5 < index < 3.5 rounds to 3
- In short
- -0.5 rounds up to 0
- 0.5 rounds down to 0
- 1.5 rounds up to 2
- 2.5 rounds down to 2
- 3.5 rounds up to 4
Index out of Range
The following code lists Arma 3 behaviour on wrong indices:
Use the param command in order to avoid out of range error:
If the index given to the set command is out of bounds:
- If the index rounded to a negative number, then an Error Zero Divisor message will be displayed in game.
- If the index rounded to a positive number, then the array will resize to incorporate the index as its last value. Each element between the last valid element, and the new set element, will be the null type
If the array is considered "Un-modifiable" such as select arrays that are returned from an addon, and some undiscovered returns, it will return a Error: Reserved variable in expression upon trying to modify it.
To combat this, copy an array with the + prefix before modifying.