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
In Arma 3 use append and pushBack commands:
You could also use (+) operator to add arrays. The difference is that addition returns a copy of array and thus a little slower than append and pushBack, which modify target array.
Removing (deleting) elements
In Arma 3 the deleteAt and deleteRange commands are available:
You can also use (-) operator to subtract arrays. The subtraction returns array copy, just like addition, and this not as fast as deleteAt and deleteRange which modify target arrays.
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 combination of for, count and select can also be used:
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:
You could use count to achieve the same result, however count won't stop until it iterated through the whole array, so it might take longer.
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 sort command allows for sorting an array of String, Number or sub-Arrays of string/number. It modifies the original array and does not return anything:
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.