Normally arrays are declared with constant values for the size of each dimension. This statement allows the size of any dimension to be changed, and the how parameter controls what will happen to the data currently contained in it. Each dimension (1 to 4) is resized to the number of elements in VectorSizeExpression1 to VectorSizeExpression4. If the parameter is missing or it contains a number less than one, the dimension is not resized.

If AutoSizeIncrementExpression1 to AutoSizeIncrementExpression4 are supplied, the auto-resizing configuration of the dimension is changed. If the parameter contains zero, the dimension is set to not auto-resizable, otherwise the dimension is increased to the nearest higher multiple of that number of elements each time an item is read or written outside the array bounds. If an array dimension is declared auto-resizable (without a size inside the square brackets), the increment is initially set to one. Changing the increment to a value of more than one may lessen the number of times an array is resized and thus improve performance. However note that the array may then contain empty items on the end, which will affect sorting and searching operations.

Possible values for the HowExpression parameter are:

• 0 Zeroise all elements of the array.
• 1 Leave the data where it is, and reshape the array around the data. Truncate or add zeroised elements to the end if the overall size changes, and allow the data to "fill up" the new array in row major order.
• 2 Move the data into the same place in the new array that it was indexed by in the old array.
• 3 As above, but never shrink the array. Check each of the dimensions supplied, and enlarge the array if necessary. This option allows the array dimensions to grow to fit the data requirements.
• 4 The array dimensions are not changed. Only the auto-resize information is processed.

You cannot change the number of dimensions that were declared in the array, only the number of elements in each dimension. That is because you cannot change an expression like x[2][3] to contain more or less dimensions - for example x[2][3][5]. If you need to do this, declare the array with the maximum number of dimensions you will need, and just use 1 as the number of elements of any dimensions you don't need; in the above example, declare three dimensions and use x[2][3][1] instead of x[2][3].

However, you can pass an array or vector as a parameter to a procedure which declares a different shaped array. Internally Equinox manipulates the data as a single array in row major order - in other words an array [2][3] is stored [1][1], [1][2], [1][3], [2][1], [2][2], [2][3]). If this array is passed to a procedure which declares the parameter as an array with one dimension, it would appear inside the procedure to have six elements. Alternatively if the procedure parameter was declared with three dimensions, it would appear inside the procedure as [3][2][1]. You can use the ArrayGetDimensions statement to discover how big the dimensions are.

Remember that Equinox handles data type conversions automatically, so arrays declared as procedure parameters do not have to have the same type as the arguments that are passed in.

Arrays that are declared dynamically (for example at the top of a procedure or form method, or after a Block statement) may be given dimension sizes using an expression containing any variable in scope. This is an alternative to the ArraySetDimensions statement (in fact, Equinox calls ArraySetDimensions on your behalf).

This example shows the effects of values 0 to 2 of the how parameter:

number x[4][1], i

| print the contents of array x on one line with a space
| between each element. There are four elements...

print x,;;

ArraySetDimensions 0, x, 3, 2

| ... and now there are six

print x,;;

x = -1

ArraySetDimensions 1, x, 4, 2

print x,;;

for i = 1 to 4

x[i] = i

next

| now x is a 4 * 2 array containing [1 1] [2 2] [3 3] [4 4]
ArraySetDimensions 2, x, 3, 3

| now x is a 3 * 3 array containing [1 1 0] [2 2 0] [3 3 0]
print x,;;

This example prompts the user to enter a value and an index, resizes the array if necessary, and then places the value into the array.

string InputData
number comma, element, i
string x[1]

repeat

InputData = Input("Enter data, index")
If InputData = "" then Exit Repeat

| find the last comma in InputData
comma = "," << InputData
If not comma then Continue Repeat

| get the element number and ensure it's valid
element = Mid(InputData, comma + 1)
if element <= 0 then Continue Repeat

| resize the array if necessary and store the value
ArraySetDimensions 3, x, element
x[element] = Left(InputData, comma - 1)

end repeat
| find out how large the array is and print out any data

ArrayGetDimensions x,element

Print "total size",element

for i = 1 to element

If x[i] <> "" then Print i, x[i]

next

This example sets the first dimension of the array to auto-resize if more than one year's processing is required.

string s[1][12]
string multiyear

multiyear = Input("Multiple years ?")

if multiyear[1] = "Y", "y" then

ArraySetDimensions 4, s,,,,, 1

end if