DIMENSION Command

Example   See Also

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

Syntax

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

Arguments

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.).