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'):
- Add new items with Push front
- Retrieve the next value with Array.Back
- Remove the retrieved value with Pop back
The following scheme implements a stack (last in first out, or 'LIFO'):
- Add new items with Push back
- Retrieve the next value with Array.Back
- Remove the retrieved value with Pop back
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.