Page tree
Skip to end of metadata
Go to start of metadata

Description

An array is a list of items. Each item may be any of the available Category Data Types.
The items in an array are referred to as its elements.
Arrays have an order. That is, any element in the array comes either before, or after, any other element in the array.

A list of special array types available are listed at the bottom (under Pages in category "Arrays").

Scripting commands specific to arrays can be found in Category VBS Command Group Variables Arrays.

Declaring Arrays

Arrays are declared like this:

_array = [elementOne, elementTwo, ..., lastElement]

Each element is either a literal of some type, or an expression of some type.

For example:

_array = [1, "Word", (1 + damage player)]

The first two elements are literals (a Number and a String), whilst the third is an expression (a Number).

Arrays of Arrays

You can have an array of arrays (aka a multi-dimensional array)

For example:

dudearray = [["Whatever", 2, 3, 1, 6], ["Whatever2", 2, 8, 3]];
firstelement = dudearray select 0;
geteight = (dudearray select 1) select 2;

firstelement would have the value ["Whatever",2,3,1,6]

geteight would have the value 8.


Accessing elements

Every element in the array has an index. The index says what position the element is in the array. Indices are how elements are accessed. Indices begin at zero, and continue up to (size of array - 1).

The command for accessing elements is select. For example, suppose an array is

_array = [soldier1, soldier2, soldier3]

Then, (_array select 0) is _soldier1, and (_array select 2) is soldier3.

Looping to access elements

In order to loop (or iterate) through every element in an array, for any array, we have to know the array's size.
The command for finding an array's size is count.

Index rounding

In SQF 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 rounds up to 0
-0.5 <= index <= 0.5 rounds to 0
0.5 rounds down to 0
0.5 < index < 1.5 rounds to 1
1.5 rounds up to 2
1.5 <= index <= 2.5 rounds to 2
2.5 rounds down to 2
2.5 < index < 3.5 rounds to 3
3.5 rounds up to 4

Other indices follow this pattern.

When an Array index is out of Range

If a rounded index refers to a position in an array that is invalid:

  • If the index is negative, an Error Zero Divisor error message will be displayed.
  • If the index is positive, the returned value will be of the Nothing.

Accesses which are out of bounds:

_array = [];
_element = (_array select 0);
_array = ["element"];
_element = (_array select 1);
_array = ["element"];
_element = (_array select -1);

Accesses which are in bounds:

_array = ["element"];
_element = (_array select 0);
_array = ["element"];
_element = (_array select 0.1);
_array = ["element"];
_element = (_array select -0.3);

Modifying an array

There are two types of operations to change an array: operations which change the underlying array, and operations which return a new array, but leave the old array intact.

Array references

Array variables behave the same as Object references, and differently to String, Number and other variable types. An array variable holds a pointer to an array, or in other words, the location of an array. Any number of different variables can refer to the same array.

Analogy using Object:

_unit1 = player;
_unit2 = player;

The commands (player setDamage 0.5), (_unit1 setDamage 0.5) and (_unit2 setDamage 0.5) all have the same effect, since they all refer to the same object (the player).

It is a similar case with arrays:

_array = [1,2,3];
_array1 = _array;
_array2 = _array;

The commands (_array set [0, 7]), (_array1 set [0, 7]) and (_array2 set [0, 7]) all have the same effect, since they all refer to the same array.

Setting elements

Individual elements in an array can be set to different values.
This is done via the set operator. It is important to declare the array before using the set operator.

The previous element at the specified index gets replaced with the new one.

Example:

_array = [1,2,3;]
_array set [2, "Hello"];

Now, _array is [1, 2, "Hello"]. The 2nd index (which is the third element in the array, which was 3) gets replaced by "Hello".

If the index given by the set operator 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 Nothing

Example:

_array = [1];
_array set [3, 4];

Now _array is [1, <Null>, <Null>, 4]

Copying, addition and subtraction

Each of these commands returns a new array, and leaves the old array or arrays unchanged.

Copying

This is done by the plus a unary operator. It copies an array, and sets the array variable to point to this new array.

Example:

_array1 = [1,2,3];
_array2 = + _array1;

Now _array and _array2 point to 2 different arrays, both of which have the contents [1,2,3].

Addition

This is done by the a plus b binary operator. It takes two arrays, and returns a new array which contains all of the first array, followed by all of the second array.

Example:
_array1 = [tank1, 7, "String"];<br>
_array2 = [tank2, 2];<br>
_array2 = _array2 + ["text"]; // array2 now contains [tank2, 2, "text"]
_array3 = _array1 + _array2; 
//_array3 now contains [tank1, 7, "String", tank2, 2, "text"]. _array1 and _array2 have not been changed.

Another example, using set: (This method is considerably faster than the "addition" method above, especially if large numbers of elements are added.)

_array = ["one","two"]
_array set [count _array, "three"]; // _array now contains ["one","two","three"]

Subtraction

This is done by the a - b binary operator. It takes 2 arrays, and returns a new array that contains all of the items in the first array that were not in the second array.

Example:

_array1 = [1,2,player,2,"String","String",3];
_array2 = [2,player,"String";]
_array3 = _array1 - _array2;

The result is that _array3 is a new array which has the contents [1, 3].

Note:

  • Subtracting an array from itself will always return an empty array [].
  • Nested arrays cannot be substracted - i.e. the following does NOT work:
_a1 = [[1,1],[2,2],[3,3]];
_a2 = [[2,2]];
_a3 = _a1 - _a2; // will still return [[1,1],[2,2],[3,3]]

To circumvent this restriction a nested array can be first replaced them with a non array variable, e.g.

_array = [[1,1],[2,2],[3,3]]; 
_array set [1,-1]; // replaces [2,2] with -1
_array =  _array - [-1]; // _array will now contain: [[1,1],[3,3]]

Property arrays

Arrays for addon or dialog properties require square brackets after the property name, and curled brackets for the array definition, e.g. colorBackground[] = {1, 1, 1, .2};