Array
Template:SideTOC 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.
Working with arrays
Array properties
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.
private _myArray = ["a", "b", "c"]; private _myNewArray = _myArray; _myArray set [1, "z"]; _myNewArray select 1; // will be "z"
An array set through setVariable does not need to be assigned again if you modify it by reference:
player setVariable ["myArray", ["a", "b", "c"]]; private _myArray = player getVariable "myArray"; _myArray set [1, "z"]; player getVariable "myArray"; // is ["a", "z", "c"]
Create an array
// Example of an empty array private _myArray = []; count _myArray; // returns 0 // Example of a filled array private _myFilledArray = ["abc", "def"]; count _myFilledArray; // returns 2
An array can hold another array within it, that can hold another array itself, etc:
private _myArray = [["my", "subArray", 1], ["mySubArray2"], [["my", "sub", "sub", "array"]]]; count _myArray; // returns 2 count (_myArray select 0); // returns 3 count (_myArray select 1); // returns 4 count (_myArray select 2); // returns 1 count ((_myArray select 2) select 0); // returns 4
Getting an element
An array uses a zero-based index for its elements:
private _myArray = ["first item", "second item", "third item"]; _myArray select 0; // returns "first item" _myArray # 2; // returns "third item" - Arma 3 only
Setting an element
private _myArray = ["first item", "second item", "third item"]; _myArray select 1; // returns "second item" _myArray set [1, "hello there"]; // _myArray is ["first item", "hello there", "third item"]
Counting elements
private _myArray = ["first item", "second item", "third item"]; count _myArray; // returns 3
Changing array size
The resize command is made to reduce or expand an array:
private _myArray = [1, 2, 3, 4, 5]; _myArray resize 3; // _myArray is [1, 2, 3]
private _myArray = [1, 2, 3]; _myArray resize 5; // _myArray is [1, 2, 3, nil, nil]
Array duplication
private _myArray = ["a", "b", "c"]; private _myNewArray = _myArray; _myArray set [1, "z"]; _myNewArray select 1; // will be "z"
private _myArray = [["a", "b", "c"], ["d", "e", "f"]; private _subArray1 = _myArray select 0; _subArray1 set [1, "z"]; // _subArray1 is now ["a", "z", "c"] // _myArray is now [["a", "z", "c"], ["d", "e", "f"]]
In order to avoid this behaviour, duplicate the array with + (plus):
// duplication private _myArray = ["a", "b", "c"]; private _myNewArray = +_myArray; _myArray set [1, "z"]; _myNewArray select 1; // still "b"
Sub-arrays are also deep-duplicated; _myNewArray will not point at the same sub-array instances.
Adding (appending) elements
In Arma 3 use append and pushBack commands:
private _myArray = [1, 2, 3]; _myArray pushBack 4; // _myArray is [1, 2, 3, 4] _myArray append [5, 6]; // _myArray is [1, 2, 3, 4, 5, 6]
Before Arma 3 you had to use (plus) in order to add a new element:
private _myArray = [1, 2, 3]; _myArray = _myArray + [4]; // _myArray is [1, 2, 3, 4] _myArray = _myArray + [5, 6]; // _myArray is [1, 2, 3, 4, 5, 6]
Removing (deleting) elements
In Arma 3 use deleteAt and deleteRange commands:
private _myArray = [1, 2, 3, 4, 5]; _myArray deleteAt 0; // _myArray is [2, 3, 4, 5]
private _myArray = [1, 2, 3, 4, 5]; _myArray deleteRange [1, 2]; // _myArray is [1, 4, 5]
You can also use - (minus) to remove nested arrays in Arma 3 only:
private _myArray = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]; _myArray = _myArray - [[4, 5, 6]]; // _myArray is [[1, 2, 3], [7, 8, 9]]
Before Arma 3 you had to use - (minus) for all these operations:
private _myArray = [1, 2, 3, 4, 5]; _myArray = _myArray - [1]; // _myArray is [2, 3, 4, 5]
The issue with this solution is that all item instances (here, 1) would be removed:
private _myArray = [1, 2, 1, 2, 1]; _myArray = _myArray - [1]; // _myArray is [2, 2]
The solution to this issue is the combined use of set and an item that you know is not present in the array:
private _myArray = [1, 2, 1, 2, 1]; _myArray set [2, objNull]; // _myArray is [1, 2, objNull, 2, 1]] _myArray = _myArray - [objNull]; // _myArray is [1, 2, 2, 1]]
Using this technique, it is possible to mimic deleteRange behaviour this way:
private _myArray = [1, 2, 3, 4, 5]; { _myArray set [_x, objNull] } forEach [1, 2]; // _myArray is [1, objNull, objNull, 4, 5] _array = _array - [objNull]; // _myArray is [1, 4, 5]
Going through the array
The simplest way to iterate through an array is the forEach command:
private _myArray = [1, 2, 3, 4, 5]; { systemChat str _x } forEach _myArray;
A combination of for, count and select can also be used:
private _myArray = [1, 2, 3, 4, 5]; for "_i" from 0 to (count _myArray) -1 do { // count would return 5, but 5 is at array index 4 systemChat str (_myArray select _i); };
Advanced usage
apply
Similar to the "map" function in Javascript, apply allows to apply code to every elements in an array, without changing reference to said array:
private _myArray = [1, 2, 3, 4, 5]; _myArray apply { _x * 2 }; // _myArray is [2, 4, 6, 8, 10] // same as for "_i" from 0 to count _myArray -1 do { private _element = _myArray select _i; _myArray set [_i, _element * 2]; };
select
A simple way to filter an array (and obtain a new one) is using select's alternative syntax:
private _myArray = [1, 2, 3, 4, 5]; private _filteredArray = _myArray select { _x > 3 }; // _filteredArray is [4, 5] // same as private _filteredArray = []; { if (_x > 3) then { _filteredArray pushBack _x } } forEach _myArray;
findIf
findIf command 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:
private _myArray = [1, 2, 3, 4, 5]; { _x == 3 } findIf _myArray == -1; // returns false, meaning an element equals 3 { _x == 6 } findIf _myArray == -1; // returns true, meaning no elements equal 6
Before Arma 3 you had to use count:
private _myArray = [1, 2, 3, 4, 5]; { _x == 3 } count _myArray > 0; // returns true, meaning an element equals 3 { _x == 6 } count _myArray > 0; // returns false, meaning no elements equal 6
arrayIntersect
The arrayIntersect command returns a new array filled with the items found in both provided lists:
private _array1 = [1, 2, 3, 4]; private _array2 = [3, 4, 5, 6]; private _result = _array1 arrayIntersect _array2; // _result is [3, 4]
Sorting an array
sort
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:
private _myArray = ["zzz", "aaa", "ccc"]; _myArray sort true; // _myArray is ["aaa", "ccc", "zzz"]
private _myArray = [666, 57, 1024, 42]; _myArray sort false; // _myArray is [1024, 666, 57, 42]
private _myArray = [["zzz", 0], ["aaa", 42], ["ccc", 33]]; _myArray sort true; // _myArray is [["aaa", 42], ["ccc", 33], ["zzz", 0]]
reverse
The reverse command simply reverses the array order:
private _myArray = [99, 33, 17, 24, "a", [3,2,1], 7777]; reverse _myArray; // _myArray is [7777, [3,2,1], "a", 24, 17, 33, 99]
BIS_fnc_sortBy
The function BIS_fnc_sortBy has been created for more complex sorting. Its algorithm input must return a number:
private _closestHelicopters = [[_heli1, _heli2, _heli3], [], { player distance _x }, "ASCEND"] call BIS_fnc_sortBy;
Common errors
Index rounding
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
etc.
Index out of Range
The following code lists Arma 3 behaviour on wrong indices:
private _myArray = ["element0"]; _myArray select -1; // throws a Error Zero Divisor error message _myArray select 0; // returns "element0" _myArray select 1; // returns nil _myArray select 2; // throws a Error Zero Divisor error message
set
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
Bad syntax
// Error: Unexpected "," private _myErroneousArray = ["Weapon1", "Weapon2", "Weapon3",]; // The last element in an array must exclude the ","