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 size, 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.

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

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

Old section

Arrays are somewhat different from other variable types.
Arrays are returned by reference.

What does this mean?

It means that the variable name you give to an array (for example myArray, or _units) references an array of values in the computer's memory.

Suppose you have two numbers, _num1 and _num2. You set _num1 to equal 5, and _num2 equal to _num1.

What do you have?
You have two completely separate variables, which store a number each, and which are both currently storing the number 5.

But what happens if you do a similar thing with a pair of arrays?

For Example:

_array1 = [5]
_array2 = _array1

What do you have now?

You have two variables, but each one points to the same data, in this case an array containing a single variable of type number, with the value of 5. You can understand the difference when you try to change the two variable types around.

Taking our number type variables:

Suppose we set _num2 to zero.
Now we have _num2 equal to zero, but _num1 still equal to 5.

Now take the two arrays.
Supposing we set _array2 to [ player].

What does _array1 equal?
_array1 also equals [ player].

We have modified the array that both _array1 and _array2 refer to.
Exactly the same thing would happen if we set _array1 to [ player] instead of _array2.
Both our variables, _array1 and _array2 are two labels for the same thing.

The difference between ' =' and 'set'.

It is important at this point to recognise the difference between two commands, set and = . If you think about it, there are two ways we could set _array2 to [ player] from its previous value of [5]. We could say _array2 = [ player] or we could say _array2 set [0, player].

The difference is very important.

If you use = to change _array2, you will find that _array1 and _array2 now have different values completely; _array1 is still [5] but _array2 is [ player].

If you use set, then both _array1 and _array2 store [ player].

The reason for this lies in what you're doing with the equals.

When you say _array2 = [ player], you are creating an entirely new array, and assigning _array2 as the variable that points to it.

_array2 is stripped away from the array that it was originally pointing to (but which _array1 still points to).

The equals command has a slighly different meaning - here is a summary:

_a1 = [1,2,3] The variable _a1 points to a new array which is created at the end of this statement

_a2 = _a1 No new array is created, but the variable _a2 now refers to the same array that _a1 refers to.

_a2 = +_a1 A new array is created which is an identical clone of the array that _a1 points to. _a2 points to this new array. _a1 points to the old one

_a2 = _a1 + [2] A new array is created which is the same as array _a1 plus an extra element.

_a2 set [0, player] The array which _a2 references is modified. Its zero element is set to 'player'. All variables referencing this array will return the changed array.

Because arrays are 'returned by reference' (not by value), the equality ( ==) operator behaves differently. Testing our two numbers, _num1 and _num2, we know that _num1 == _num2 is true when _num1 and _num2 are storing the same value.

The same is not true of arrays.

If we had two separate arrays, and both had identical values e.g. [3,4,2].

_firstArray == _secondArray would return false, even though the values are identical. When used with arrays, the equality ( ==) operator compares two references and checks if they point to the same thing.

From our example above, _array1 == _array2 would return true, because both _array1 and _array2 point to the same array.

Another interesting thing is what happens when we delete a variable pointing to an array.

Returning to our two arrays, supposing we do: _array2 = nil

The array is not deleted. It helps to think of _array1 and _array2 as labels or arrows, pointing to a chunk of data (the array). Deleting _array2 removes one of the arrows pointing to the array. _array1, however, still points to the array as per usual.

(An array is normally destroyed, and its memory reclaimed, when there are no more labels pointing to it).