Arrays

An array is an indexed series of values.

Note: If you are new to arrays, see Arrays Explained.

An array is an ordered collection, or numbered list, of values; all of the same data type. See Data Types.

In UJML, an array is a reference data type that it is stored as a pointer to an array of elements elsewhere in memory. Array indexes are zero-based and multiple dimensions are allowed. The number and size of array dimensions are specified with the size attribute of the var element declaring the array variable. See Variables.

Arrays may be fixed (meaning that the number of elements is fixed at compile time) or resizeable (meaning that the number of elements may be changed at runtime). See Resizable Arrays. The _getArrayLength() function returns the number of elements in an array at runtime See _getArrayLength().

Remarks

Array variables may not be assigned to other variables or passed as function arguments. Once created, they can only be changed by assigning values to the array elements. However, the array elements may be treated like single variables of the array data type and may be assigned to other variables or passed as function arguments in the normal manner.

In practice, the maximum number of possible array dimensions is limited only by the device memory. In most cases, you will not want to use more than two or three dimensions; but if you do require an array with many dimensions remember that each array dimension increases the number of elements in the array by the multiple of the dimension size. A ten-dimensional array where each dimension has ten elements would contain ten to the tenth power (or 10,000,000,000) elements!

Topics

Topic	Description
Arrays Explained	A simplified explanation of arrays.
Resizable Arrays	Some variable arrays may be resized at runtime.

Example

The following example shows how to declare a one-dimensional and a three-dimensional array. It is part of the assignment.ujml sample.

Copy Code

<var name="m3DArray" type="string" size="2, 3, 4"/>
<var name="mMessages" type="string" size="&MESSAGE_COUNT;"/>

The following example shows how to set a value for one element of the one-dimensional array declared above. It is part of the assignment.ujml sample.

Copy Code

mMessages[0] = "1: A simple string assignment.";

The following example sets values for elements of the three-dimensional array declared above. It is part of the assignment.ujml sample.

Copy Code

// Fill a multidimensional array.
for (mCtr1 = 0; mCtr1 &_LT; 2; mCtr1++)
{
    for (mCtr2 = 0; mCtr2 &_LT; 3; mCtr2++)
    {
        for (mCtr3 = 0; mCtr3 &_LT; 4; mCtr3++)
        {
            m3DArray[mCtr1][mCtr2][mCtr3] = _strcat(mCtr1, "/", mCtr2, "/", mCtr3);
        }
    }
}

The following example shows how to access two elements of the three-dimensional array declared above and uses them in a string assigned to the one-dimensional array. It is part of the assignment.ujml sample.

Copy Code

mMessages[5] = _strcat("6: Two elements of a multi-dimensional array: ",
    m3DArray[0][1][2], " - ", m3DArray[1][2][3]);

The following example shows how to set values for elements of three different two-dimensional arrays. It is part of the colors.ujml sample.

Copy Code

// Set color box values.
mColorVal[0][0] = &_COLOR_AQUA;;
mColorNameColorVal[0][0] = &_COLOR_BLACK;;
mColorName[0][0] = "Aqua";
mColorVal[1][0] = &_COLOR_BLACK;;
mColorNameColorVal[1][0] = &_COLOR_WHITE;;
mColorName[1][0] = "Black";

...

mColorVal[4][2] = &_COLOR_YELLOW;;
mColorNameColorVal[4][2] = &_COLOR_BLACK;;
mColorName[4][2] = "Yellow ";
mColorVal[5][2] = &_COLOR_TRANSPARENT;;
mColorNameColorVal[5][2] = &_COLOR_WHITE;;
mColorName[5][2] = "Transparent";

The following example shows how to use values from the two-dimensional arrays values set above to display a box with a color and a name in a grid with multiple rows and columns. This is done by setting a state variable with the same dimensions to true for each array element. The state transition then shows the colors and text for the requested grid position. It is part of the colors.ujml sample.

Copy Code

for (mColorCtrX = 0; mColorCtrX &_LT; &COLORS_WIDE;; mColorCtrX++)
{
    for (mColorCtrY = 0; mColorCtrY &_LT; &COLORS_HIGH;; mColorCtrY++)
    {
        sColors[mColorCtrY][mColorCtrX] = true;
    }
}

The following example is the display code for the loop above. It is part of the colors.ujml sample.

Copy Code

<box>
    <x>
        <eval>
        &COLOR_SPACING; +
            (mColorCtrX * &COLOR_SPACING;) +
            (mColorCtrX * mColorWidth)
        </eval>
    </x>
    <y>
        <eval>
        &COLOR_SPACING; +
            (mColorCtrY * &COLOR_SPACING;) +
            (mColorCtrY * mColorHeight)
        </eval>
    </y>
    <width><eval>mColorWidth</eval></width>
    <height><eval>mColorHeight</eval></height>
    <fg>0xFFDDEEFF</fg>
    <bg><eval>mColorVal[mColorCtrY][mColorCtrX]</eval></bg>
    <x-clip>true</x-clip>
    <label>
        <text><eval>mColorName[mColorCtrY][mColorCtrX]</eval></text>
        <x>&COLOR_SPACING;</x>
        <y>&COLOR_SPACING;</y>
        <fg><eval>mColorNameColorVal[mColorCtrY][mColorCtrX]</eval></fg>
        <size>&_FONT_SIZE_SMALL;</size>
        <style>&_FONT_STYLE_PLAIN;</style>
        <face>&_FONT_FACE_SYSTEM;</face>
    </label>
</box>

The following example gets the size of a one-dimensioned variable. It is part of the timer.ujml sample.

Copy Code

cnt = _getArrayLength(mListeners, 0);