Arrays

Basics

Many programming languages provide arrays, vectors, lists or any other data type to store dynamic data. Dynamic data is not known yet when the program is written. For such tasks MADRIX Script provides dynamic arrays. They are declared like variables, followed by [].

int    aiIntArray[];      //a 1-dimensional array of integer values

date   adDateArray[];     //a 1-dimensional array of dates

float  aafFloatArray[][]; //a 2-dimensional array of float values

It is also possible to initialize arrays using a list of values. These are described by values separated with commas and written in curly brackets.

//initialize an array with 5 integer values

int aiIntArray[] = {2, 3, 4, 5, 6};

The operator [expression] provides access to the elements of an array. The expression must result in an integer or compatible value. The lowest index of an array is 0. This means the first entry of an array is always indexed with 0; an array does not start with 1, but 0. When an element is accessed, the array grows automatically in order to provide the requested element. It is not necessary nor possible to request the size of an array explicitly. Here is an example to access an array with integer values.

int aiIntArray[];

aiIntArray[0] = 10;

aiIntArray[1] = 20;

aiIntArray[2] = aiIntArray[3];

After the last access the array will have a length of 4 because 3 was the last accessed element. The initial value of an element is "0" or an empty string or false. The length-attribute of an array tells the current size of an array, which is the number of currently provided elements.

The Length Or Size Of Arrays

Each array has a length-attribute. It can be accessed through the "."-operator which is also used to access elements from a structure.

int l = aiIntArray.length; //store length of the array in l

Note: The length of an array is defined by the highest index that was used to request an element.

Multi-Dimensional Arrays

Up to this point, one-dimensional arrays were introduced. But multi-dimensional arrays are also possible. To declare a multi-dimensional array, a "[]" must be added to its declaration for each dimension. Up to now, the only limit to the number of possible dimensions is set by the resources of the computer on which the script/macro is running. It is also possible to initialize arrays using a list of elements for each dimension. Here are some examples:

int aaArray[][];     //a 2-dimensional array

int aaaArray3[][][]; //a 3-dimensional array

//initializes the array with two dimensions and three values each

int aaArry2[][] = {{2, 3, 4}, {6, 7, 8}};

//a 2-dimensional array of color elements

color aaCArray[][] = {

                     { {0, 0, 0, 0, 255}, {255, 255, 255}, {255, 255} },

                     { {255            }, {255, 255, 255} },

                     { {0, 255         }, {255, 255, 255} } };

The operator [expression] accesses a single element of an array, which for a multi-dimensional array may be another array. In order to access a single element, the applicable index must be used. For example, the 5th element must be accessed with the index 4, while the first entry has the index 0. The same is true for the attribute length. It returns the length of the currently accessed array. Here are two examples:

int aaArray[][];

int aArray1[] = {1, 2, 3, 4, 5, 6}; //intialize the array

aaArray[0] = aArray1; //assign aArray1 to the first element of aaArray

aaArray[0][aArray1.length] = aField1.length + 1;

aaArray[1][0] = 1;

aaArray[1][2] = 2;

Explanation: At the end of this example aaArray consists of two arrays of int values. The first one has a length of 7 and the second one a length of 3 (due to the access of the element with the index 2). These lengths can be received by reading the length attributes.

WriteText("Number of arrays in aaArray: " + aaArray.length);

WriteText("Number of elements in aaArray[0]: " + aaArray[0].length);

WriteText("Number of elements in aaArray[1]: " + aaArray[1].length);

Memory Management Of Arrays

Although the memory for arrays is dynamic, you have to think of it beforehand. Think about the following example:

int aiArray[][];

aiArray[10000][10000] = 1;

After the assignment, the array has indeed a size of 10.000 x 10.000 elements of int values. An int value needs four bytes and 10.000 * 10.000 * 4 = 4.0000.0000 bytes, add up to around 382 megabytes (MB) of memory. So please pay attention when using very big arrays.

Full Example

This example just plays with the arrays and its content. It is just to show how to work with arrays and to get a feeling for them. A better example is given in the chapter »Loops

void InitEffect()

{

    SetBpm(600);

}

void RenderEffect()

{

    int aaArray[][];

    int aArray1[] = {1, 2, 3, 4, 5, 6}; //intialize the array

    aaArray[0] = aArray1; //assign aArray1 to first element of aaArray

    aaArray[0][aArray1.length] = aArray1.length + 1;

    aaArray[1][0] = 1;

    aaArray[1][2] = 2;

    WriteText("Number of arrays in aaArray: " + aaArray.length);

    WriteText("Number of elements in aaArray[0]: " + aaArray[0].length);

    WriteText("Number of elements in aaArray[1]: " + aaArray[1].length);

    WriteText("Element of aaArray[0][0]: " + aaArray[0][0]);

    WriteText("Element of aaArray[0][1]: " + aaArray[0][1]);

    WriteText("Element of aaArray[0][2]: " + aaArray[0][2]);

    WriteText("Element of aaArray[0][3]: " + aaArray[0][3]);

    WriteText("Element of aaArray[0][4]: " + aaArray[0][4]);

    WriteText("Element of aaArray[0][5]: " + aaArray[0][5]);

    WriteText("Element of aaArray[1][0]: " + aaArray[1][0]);

    WriteText("Element of aaArray[1][1]: " + aaArray[1][1]);

    WriteText("Element of aaArray[1][2]: " + aaArray[1][2]);

}