Array

The Array object stores lists of values (numbers or text). It is analogous to arrays in traditional programming languages.

About Arrays

Array supports up to three dimensions. For example, a simple list of ten values would be a 10 x 1 x 1 array. Note that you should not set a size of 0 on any of the dimensions else the entire array becomes empty; it is correct to have a size of 1 on unused dimensions.

Each element of an array can store a number or some text. The number or text in an element can be changed with the Set actions, and accessed with the At expression. For example, a 10 x 10 x 1 array is analogous to a 2D grid with a total of 100 values. A number could be stored at the position (3, 7) with the action Set at XY, and accessed with Array.At(3, 7). Note like the rest of Construct 2, indices are zero-based, so the first element is at 0. In this example, Array.At(0, 0) would return the first number in the grid.

Array can store either text or a number in any of the elements. Numbers and text can also be mixed within an array.

Arrays do not automatically resize. If you access a value outside the array bounds, it returns the number 0. If you set a value outside the array bounds, it will have no effect.

Manipulating arrays

A one-dimensional array, sized N x 1 x 1, serves as a simple list of N values. The actions in the Manipulation category (e.g. Push, Pop) allow one-dimensional arrays to be used like other data structures. (These actions work with multidimensional arrays, but are intended for the one-dimensional case.)

For example, the following scheme implements a queue (first in first out, or 'FIFO'):
[ul]Add new items with Push front
Retrieve the next value with Array.Back
Remove the retrieved value with Pop back[/ul]

The following scheme implements a stack (last in first out, or 'LIFO'):
[ul]Add new items with Push back
Retrieve the next value with Array.Back
Remove the retrieved value with Pop back[/ul]

Array properties

Width (X dimension)
Height (Y dimension)
Depth (Z dimension)
The size of the array. If you want a one-dimensional array (i.e. a list of values), use A x 1 x 1. If you want a two-dimensional array (i.e. a grid of values) use A x B x 1.

Array conditions

Compare at X
Compare at XY
Compare at XYZ
Compare a value at a position in the array. Indices are zero-based. All values outside the array return the number 0. If Compare at X is used, the Y and Z indices are 0. If Compare at XY is used, the Z index is 0.

Compare size
Compare the size of one of the array dimensions, which is the number of elements on that axis.

For each element
A repeating condition that runs once for each element in the array. This therefore runs width x height x depth times.

Compare current value
Only valid in a For each element loop, either as a following condition or in a sub-event.

Contains value
Searches the entire array to check if any of the elements contains the given value. For example, you can use this to test if the string "sword" is stored anywhere in the array.

Is empty
Test if the array is empty. The array is empty when the total number of elements is zero, calculated as width x height x depth. Therefore the array is empty when any axis has a size of zero. This can be useful when using Array as a data structure (e.g. when pushing and popping values).

Array actions

Clear
Set every element in the array to the number 0.

Set at X
Set at XY
Set at XYZ
Write a value at a position in the array. Indices are zero-based. Writing to values outside the array has no effect. If Set at X is used, the Y and Z indices are 0. If Set at XY is used, the Z index is 0.

Set size
Set the dimensions of the array. Values are preserved, but if the new array is smaller it is truncated. If the new array is larger, new elements are set to store the number 0. If any of the dimensions are 0 the entire array is empty, so usually all the dimensions are at least 1.

Download
Invokes a browser download of a file containing the Array's contents in JSON format. This is intended for offline development, e.g. creating level editors.

Load
Load the contents of the array from a string in JSON format. This must have been retrieved from either the Download action or the AsJSON expression. It could also be retrieved dynamically from the AJAX object.

Push
Add a new value either to the beginning (front) or end (back) of an axis. Since the Array is a 3D cube of values, technically this inserts a new 2D plane of elements all with the given value. However in 1D arrays this adds a single element, and in 2D arrays it inserts a new row of elements.

Pop
Delete the value at either the beginning (front) or end (back) of an axis. Since the Array is a 3D cube of values, technically this removes a 2D plane of elements. However in 1D arrays this removes a single element, and in 2D arrays it removes a whole row of elements.

Insert
Insert a new value at a specific index on an axis. Since the Array is a 3D cube of values, technically this inserts a new 2D plane of elements all with the given value. However in 1D arrays this adds a single element, and in 2D arrays it inserts a new row of elements.

Delete
Delete the value at a specific index on an axis. Since the Array is a 3D cube of values, technically this removes a 2D plane of elements. However in 1D arrays this removes a single element, and in 2D arrays it removes a whole row of elements.

Reverse
Reverse the order of elements on an axis. Note that in multidimensional arrays this only reverses one axis. For example reversing the X axis in a 2D array will reverse the order of the columns while preserving the contents of each column.

Sort
Sorts the order of elements on an axis in ascending order. Note that in multidimensional arrays this sorts based on the first element on the axis. For example sorting the X axis in a 2D array will sort the order of the columns based on the elements at Y co-ordinate 0, while preserving the contents of each column.

Array expressions

At(X)
At(X, Y)
At(X, Y, Z)
Retrieve a value at a position in the array. Indices are zero-based. Reading values outside the array returns the number 0. If the Y or Z indices are not provided then 0 is used.

CurX
CurY
CurZ
The current zero-based index for each dimension in a For each element loop.

CurValue
The current value in a For each element loop. This is a shortcut for Array.At(Array.CurX, Array.CurY, Array.CurZ).

Width
Height
Depth
Return the size of each of the array's dimensions.

Front
Shortcut to access the first value in the array, which is the same as At(0, 0, 0).

Back
Shortcut to access the last value on the X axis, which is the same as At(Self.Width - 1, 0, 0).

IndexOf
LastIndexOf
Searches the array X axis for a given value and returns the index it is found at, or -1 if not found. IndexOf finds the first matching element, and LastIndexOf finds the last matching element.

AsJSON
Return the contents of the array as a string in JSON format. This can later be loaded in to the array with the Load action.

Tags: