Creates a one- or two-dimensional array of variables.
DIMENSION ArrayName1(nRows1 [, nColumns1]) [, ArrayName2(nRows2 [, nColumns2])] ...
- 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
gaArrayOnethat contains one column and ten rows.
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
gaArrayTwocontaining two rows and four columns:
You must specify a size for each array you create with DIMENSION. In the following example, three arrays are created:
gaArrayTwofrom the previous examples and a third array called
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, gaArrayTwo(2,4), gaArrayThree[3,3]
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 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
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