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, ..., elementItem]

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. This is how:

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 (X.5 rounds to the nearest even whole number).

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)

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]

How array variables work

Each data type that a variable refers to has what is called a 'value'.

For strings, numbers and other primitive types, this is a unique instance of the value.

For arrays and objects, this value is a reference to a particular array or object. This reference is not unique, and can be shared between multiple variables.

Example (Number):

_number1 = 5
_number2 = _number1

_number1 and _number2 are two independent variables, both of which happen to be equal to 5. Doing
_number1 = _number1 + 1
has no effect on _number2, which still equals 5.

Example (Array):

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

_array1 and _array2 now refer to exactly the same thing. Doing
_array1 set [2, "Hello"]
will mean that both _array1 and _array2 are [1,2,"Hello"]