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 + getDammage 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 1
2.5 rounds down to 2
2.5 < index < 3.5 rounds to 1
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 setDammage 0.5), (_unit1 setDammage 0.5) and (_unit2 setDammage 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 effet, 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.

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]