Fields

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 fields. They are declared like variables, followed by [].

int    aiIntField[];      //a 1-dimensional field of integer values

date   adDateField[];     //a 1-dimensional field of dates

float  aafFloatField[][]; //a 2-dimensional field of float values

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

//initialize a field with 5 integer values

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

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

int aiIntField[];

aiIntField[0] = 10;

aiIntField[1] = 20;

aiIntField[2] = aiIntField[3];

After the last access the field 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 a field tells the current size of a field, which is the number of currently provided elements.

The Length Or Size Of Fields

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

int l = aiIntField.length; //store length of the field in l

Please note: The length of a field is defined by the highest index that was used to request an element.

Multidimensional Fields

Up to this point, one-dimensional fields were introduced. But multidimensional fields are also possible. To declare a multidimensional field, 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 is running. It is also possible to initialize fields using a list of elements for each dimension. Here are some examples:

int aaField[][];     //a 2-dimensional field

int aaaField3[][][]; //a 3-dimensional field

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

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

//a 2-dimensional field of color elements

color aaCField[][] = {

                     { {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 a field, which for a multi dimensional field may be another field. 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 field. Here are two examples:

int aaField[][];

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

aaField[0] = aField1; //assign aField1 to the first element of aaField

aaField[0][aField1.length] = aField1.length + 1;

aaField[1][0] = 1;

aaField[1][2] = 2;

Explanation: At the end of this example aaField consists of two fields 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 fields in aaField: " + aaField.length);

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

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

Memory Management Of Fields

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

int aiField[][];

aiField[10000][10000] = 1;

After the assignment, the field 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 fields.

Full Example

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

void InitEffect()

{

    SetSpeed(1);

}

void RenderEffect()

{

    int aaField[][];

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

    aaField[0] = aField1; //assign aField1 to first element of aaField

    aaField[0][aField1.length] = aField1.length + 1;

    aaField[1][0] = 1;

    aaField[1][2] = 2;

    WriteText("Number of fields in aaField: " + aaField.length);

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

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

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

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

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

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

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

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

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

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

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

}