SizeOfArray

Purpose

Returns the number of elements in an array or array dimension.

Return Type

Syntax

SizeOfArray({ArrayId})
SizeOfArray({ArrayId[{DimensionIndex}]})

Where:

{ArrayId} is the id of the array to retrieve the number of elements for.
{DimensionIndex} is the dimension index of the array to retrieve the number of elements of. If omitted, the outer (leftmost) dimension is used.

What it Does

SizeOfArray is used to retrieve the number of elements of any array dimension.

Example

The below example returns 10 to iSize.

Integer[10] iMyArray
Move (SizeOfArray(iMyArray)) to iSize

Multi-dimensional arrays and jagged arrays can be thought of as arrays of arrays. To get the number of elements of the second dimension of a multi-dimensional or jagged array, specify the indexer for the first dimension, resulting in an expression of the array for the particular dimension:

Integer[][] iMyArray
// Move some values to iMyArray
Move (SizeOfArray(iMyArray[1])) to iSize

The above example retrieves the number of elements in dimension 1 of iMyArray.

Example

This sample declares and fills a dynamic two-dimensional integer array. It then uses SizeOfArray to determine the number of elements of the two dimensions and displays the result to the screen.

Note: This will not work with jagged arrays, since this technique assumes that it's a rectangular array. The assumption is that each inner array contained in the outer array has the same number of elements. Knowing this, we only need to check the size of the first inner array to know the number of elements in all the other inner arrays, since they are the same. For jagged arrays, you need to do this check for each inner array. See the example below for how to do this with jagged arrays.

This example fills an outer array of 3 arrays, where each inner array has 3 elements, conceptually looking like this:

1 2 3
4 5 6
7 8 9

Procedure OnClick
    Integer[][] iIntegers1
    Integer i j iDim1Size iDim2Size

    // fill the array
    Move 1 to iIntegers1[0][0]
    Move 2 to iIntegers1[0][1]
    Move 3 to iIntegers1[0][2]
    Move 4 to iIntegers1[1][0]
    Move 5 to iIntegers1[1][1]
    Move 6 to iIntegers1[1][2]
    Move 7 to iIntegers1[2][0]
    Move 8 to iIntegers1[2][1]
    Move 9 to iIntegers1[2][2]

    // retrieve size of outer (leftmost) dimension
    Move (SizeOfArray(iIntegers1)) to iDim1Size

    // retrieve size of inner (2nd) dimension
    Move (SizeOfArray(iIntegers1[1])) to iDim2Size

    // display the array's contents
    For i From 0 To (iDim1Size - 1)
        For j From 0 To (iDim2Size - 1)
            Show iIntegers1[i][j]
            Show " "
        Loop
        Showln
    Loop
End_Procedure

Since the array in this example is declared dynamically (declaration below), each inner array could contain any number of elements, potentially making it a jagged array. This could cause runtime errors or unnoticed but incorrect data to occur if, at a later time, more elements are added to inner arrays.

Integer[][] iIntegers1

If you want to ensure that each inner array always has the same number of elements and protect your code from potential errors, you should declare a dynamic multidimensional array (declaration below), where in the latter declaration each inner array will always contain exactly 3 elements.

Integer[][3] iIntegers1

Checking Sizes of Jagged Array Dimensions

A jagged array is a non-rectangular array in which the number of rows is fixed but the number of columns is not. You could have an array containing 2 arrays, where the first array has 30 elements, but the second row only has 1 element.

Example

This example is similar to the above example but uses a jagged array, where each inner array may not have the same number of elements. In this scenario, you have to make sure to check the size of each array using the appropriate DimensionIndex for the array you are currently addressing.

This example fills an outer array of 2 arrays, where the first inner array has 3 elements and the second inner array has 2 elements, conceptually looking like this:

1 2 3
4 5

Procedure OnClick
    Integer[][] iIntegers1
    Integer i j iDim1Size iDim2Size

    // fill the array
    Move 1 to iIntegers1[0][0]
    Move 2 to iIntegers1[0][1]
    Move 3 to iIntegers1[0][2]
    Move 4 to iIntegers1[1][0]
    Move 5 to iIntegers1[1][1]

    // retrieve size of outer (leftmost) dimension
    Move (SizeOfArray(iIntegers1)) to iDim1Size

    // display the array's contents
    For i From 0 to (iDim1Size - 1)
        // check the size of the inner array using its dimension index
        Move (SizeOfArray(iIntegers1[i])) to iDim2Size

        For j From 0 to (iDim2Size - 1)
            Show iIntegers1[i][j]
            Show " "
        Loop

        Showln // go to next line for next row
    Loop
End_Procedure

Notes

Attempting to reference an array dimension that is beyond the current number of dimensions of the array will result in error 4509: "Reference Array Index Out Of Bounds".