Array

Description

An array is a list of items. Each item may be any of the variable 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.

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).

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 OFP script, indices are rounded to the nearest whole number. A bounday 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 index is out of bounds

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 null type.

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)

Changing 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 Objects:

_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 null type

Example:

_array = [1]

_array set [3, 4]

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

Array copying, addition and substraction

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

Copying

This is done by the + 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 + binary operator. It takes two arrays, and returns a new array which containes all of the first array, followed by all of the second array.

Example:

_array1 = [player, 7, "String"]

_array2 = [player, 2]

_array3 = _array1 + _array2

After this _array3 refers to a new array which has the contents [player, 7, "String", player, 2]

Another example, using set:

_array set [count _array, "String"];

Subtraction

This is done by the - 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]]