DIMENSION Command

  • Article

Creates a one- or two-dimensional array of variables.

DIMENSION ArrayName1(nRows1 [, nColumns1])
   [, ArrayName2(nRows2 [, nColumns2])] ...

Parameters

  • ArrayName1
    Specifies the name of the array. Multiple arrays can be created with a single DIMENSION command by including additional array names (ArrayName2, ArrayName3, and so on).

  • nRows1 [, nColumns1]
    Specifies the size of the array to create. If you include just nRows1, a one-dimensional array is created. One-dimensional arrays have one column and nRows1 rows. For example, the following command creates a one-dimensional array named gaArrayOne that contains one column and ten rows.

    DIMENSION gaArrayOne(10)

    To create a two-dimensional array, include both nRows1 and nColumns1. nRows1 specifies the number of rows in the array, and nColumns1 specifies the number of columns. The following example creates a two-dimensional array named gaArrayTwo containing two rows and four columns:

    DIMENSION gaArrayTwo(2,4)

    You must specify a size for each array you create with DIMENSION. In the following example, three arrays are created: gaArrayOne and gaArrayTwo from the previous examples and a third array called gaArrayThree:

    DIMENSION gaArrayOne(10), gaArrayTwo(2,4), gaArrayThree(3,3)

    You can use either brackets or parentheses to enclose the expressions in DIMENSION or DECLARE. For example, the following two commands create identical arrays:

    DIMENSION gaArrayOne(10), gaArrayTwo[2,4], gaArrayThree(3,3)
DIMENSION gaArrayOne[10], gaArrayTwo(2,4), gaArrayThree[3,3]

Remarks

DIMENSION is identical in operation and syntax to DECLARE.

Array Elements   The size of an array determines how many elements it can contain. Each element in an array can store a single piece of information. To determine how many elements an array contains and how much information it can store, multiply the number of rows (nRows1) in the array by the number of columns (nColumns1) in the array.

Array elements can contain any type of data and are initialized to false (.F.) when the array is first created. You can initialize all the elements in an array to the same value with STORE if SET COMPATIBLE is FOXPLUS or OFF (the default setting). For example:

DIMENSION gaArray(10,3)
STORE 'initial' TO gaArray

Array Subscripts   Elements in an array are referenced by their subscripts. Each array element has a unique numeric subscript that identifies it. If the array is one-dimensional, an element's subscript is the same as its row number. For example, the subscript for the element in the third row of a one-dimensional array is 3.

Elements in two-dimensional arrays are referenced by two subscripts. The first subscript indicates the row location of the element, and the second subscript indicates the column location. For example, the subscripts for the element in the third row and fourth column of a two-dimensional array are 3,4. For a further discussion of array element subscripts, see ASUBSCRIPT( ).

The subscript or subscripts for the first element in an array always start with 1. If an array is two-dimensional, it can also be referenced by a single subscript. Use AELEMENT( ) to return the single subscript from a pair of array row and column subscripts. Use ASUBSCRIPT( ) to return the row and column subscripts from a single subscript.

Redimensioning Arrays   You can change the size and dimensions of an array by issuing DIMENSION again. The size of an array can be increased or decreased; one-dimensional arrays can be converted to two dimensions, and two-dimensional arrays can be reduced to one dimension.

If the number of elements in an array is increased, the contents of all the elements in the original array are copied to the newly redimensioned array. The additional array elements are initialized to false (.F.).

When the size of an array is increased or decreased when SET COMPATIBLE is set to ON or DB4, the value of each element in the array is reinitialized to .F.

Example

Example 1 demonstrates the result of increasing the size of a one-dimensional array. (Note that if you type these commands in the Command window the array will be PUBLIC, but it will be PRIVATE if you copy them into a program and run it.)

If the number of elements in an array is decreased, the elements and any data they contain are deleted. When a one-dimensional array is redimensioned to two dimensions, the contents of the original one-dimensional array are copied to the new array in an element-to-row order.

In Example 2, a one-dimensional array is converted to a two-dimensional array. The contents of the elements of the one-dimensional array are copied to the first row of the new array, followed by the second row and so on. The additional elements are initialized to false (.F.).

When a two-dimensional array is converted to one dimension, the contents of the original two-dimensional array are copied to the new array in a row-to-element order. The first element in the first row becomes the first element in the one-dimensional array, the second element in the first row becomes the second element, and so on.

Use ADEL( ) or AINS( ) to delete or insert array elements, rows and columns. Use APPEND FROM ARRAY, COPY TO ARRAY, SCATTER and GATHER to transfer data between table records and arrays.

In Example 3, a two-dimensional array is created and loaded with data. The array elements and the data they contain are displayed.

* Example 1
DIMENSION marray(2)
STORE 'A' TO marray(1)
STORE 'B' TO marray(2)
CLEAR
DISPLAY MEMORY LIKE marray
DIMENSION marray(4)
DISPLAY MEMORY LIKE marray
WAIT WINDOW

* Example 2
DIMENSION marrayone(4)
STORE 'E' TO marrayone(1)
STORE 'F' TO marrayone(2)
STORE 'G' TO marrayone(3)
STORE 'H' TO marrayone(4)
CLEAR
DISPLAY MEMORY LIKE marrayone
DIMENSION marrayone(2,3)
DISPLAY MEMORY LIKE marrayone
WAIT WINDOW

* Example 3
DIMENSION sample(2,3)
STORE 'Goodbye' TO sample(1,2)
STORE 'Hello' TO sample(2,2)
STORE 99 TO sample(6)
STORE .T. TO sample(1)
CLEAR
DISPLAY MEMORY LIKE sample

See Also

ACOPY( ) | ADEL( ) | ADIR( ) | AELEMENT( ) | AFIELDS( ) | AFONT( ) | AINS( ) | ALEN( ) | APPEND FROM ARRAY | ASCAN( ) | ASORT( ) | ASUBSCRIPT( ) | COPY TO ARRAY | DECLARE | EXTERNAL | GATHER | PRIVATE | PUBLIC | SCATTER | SET COMPATIBLE | STORE