Array

Description: Array of items, each may be of any type.

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. It's 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, or references, 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).