6.1.5 Array variables

Array variable names are subject to the same naming conventions as variables.

Index numbers representing the elements of an array variable (or row and column elements of a two-dimensional array) start at 1. Enclose index numbers in parentheses or square brackets.

An array variable declared with an index number has a fixed number of elements. An array variable declared without an index number has a variable number of elements.

An array variable may have one or two dimensions.

The maximum number of elements is 65,536 for an array variable, and 131,072 for a script file.

Once declared, the dimensions of an array variable must not be changed.

Example:

Dim A(5)
Dim A(5,10)#

#

(Error) You cannot change the number of dimensions.

The number of elements in an array variable can be changed as long as the declared dimensions remain unchanged. An array variable with a fixed number of elements can be changed to a dynamic array variable with a variable number of elements, and vice versa. If the number of elements is changed, the previous setting value is set to the Empty value.

Example:

Dim A(10)
Dim A(5)#1
Dim A( )#2

#1

You can change the number of elements.

#2

You can change the number to a variable number of elements.

A non-array variable cannot be redefined as an array variable. An array variable cannot be redefined as a non-array variable.

Example:

Dim A
Dim A( )#

#

(Error) You cannot redefine A because it is defined as a non-array variable.

You can assign values to all the elements of an array variable by using one assignment statement. However, you cannot do so if the array variable on the left has a fixed number of elements and the number of elements varies between the array variable on the left and the array variable on the right.

Example 1:

Dim A(5), B( ), C(10)
For cnt = 1 To 5
   A(cnt) = Time
Next
B = A#1
C = B#2

#1

You can assign all the elements of A to B in one assignment statement. After the assignment, B has five elements.

#2

(Error) You cannot assign all the elements of B to C in one assignment statement because B and C have a different number of elements (5 versus 10).

Example 2:

Dim A( ), B(1)
For cnt = 1 To 5
   A(cnt) = Time
Next
B(1) = Date
A = B#

#

You can assign all the elements of B to A in one assignment statement. After the assignment, A has one element.

Example 3:

Dim A( ), B( )
For cnt = 1 To 5
   A(cnt) = Time
Next
For cnt = 1 To 10
   B(cnt) = Date
Next
A = B#

#

You can assign all the elements of B to A in one assignment statement. After the assignment, A has 10 elements.

All the elements of a single row can be assigned in one assignment statement, but it is not possible to assign all the elements of a single column in one assignment statement.

Example:

Dim A(2,5), B()
For cnt = 1 To 5
   A(1,cnt) = Time
Next
B = A(1)#

#

You can assign the elements of the first row of A to B in one assignment statement.

Equality comparisons can be made on the elements of two array variables, but comparisons to determine which array variable is greater are not allowed.

Example 1:

Dim A(5), B(5)
   ...
If A = B Then#

#

You can compare A and B to determine whether they are equal.

Example 2:

Dim A(5), B(5)
   ...
If A < B Then#

#

(Error) You cannot compare A and B to determine which is greater.

When an intermediate element in a dynamic array variable is undefined, Empty values are assigned from the first element to the undefined element. Note, however, that the elements to which the Empty value is assigned vary depending on how the array variable is declared.

Example 1:

If the number of elements is omitted in a one-dimensional array:

If you assign a value to the m-th element, the Empty value is assigned from the first element to the (m-1)-th element.

Dim A( )
A(1) = "abc"

A(5) = "def"#

#

The elements from A(2) to A(4) are set to an Empty value.

Example 2:

If a row element and a column element are omitted in a two-dimensional array:

When a value is assigned to the element in the m-th row of the n-th column, the Empty value is assigned to the elements in the first to (m-1)-th rows of the first column as well as to the elements in the first to (n-1)-th columns of the m-th row.

Dim A(,)
A (3,5) = "abc"#

#

A(1,1), A(2,1), and the elements from A(3,1) to A(3,4) are set to an Empty value.

Blank elements, such as A(1,2), do not have a value stored in them. Any attempt to reference such an element results in an error with the following message: Cannot reference an unset index of a variable array variable.

Example 3:

If a column element is omitted in a two-dimensional array:

When a value is assigned to the element in the m-th row of the n-th column, the Empty value is assigned to the elements in the first to (n-1)-th columns of the m-th row.

Dim A(3,)
A(3,5) = "abc"#

#

The elements from A(3,1) to A(3,4) are set to an Empty value.

Blank elements, such as A(1,1), do not have a value stored in them. Any attempt to reference such an element results in an error with the following message: Cannot reference an unset index of a variable array variable.

Example 4:

If a row element is omitted in a two-dimensional array:

When a value is assigned to the element in the m-th row of the n-th column, the Empty value is assigned to the elements in the first to (m-1)-th rows of all columns as well as to the first to (n-1)-th columns of the m-th row.

Dim A(,5)
A(3,5) = "abc"#

#

The elements from A(1,1) to A(1,5), from A(2,1) to A(2,5), and from A(3,1) to A(3,4) are set to an Empty value.

In a one-dimensional array variable, the index numbers represent the elements.

Example:

An array variable declared as Dim A(5) has five elements as shown below.

In a two-dimensional array variable, the first index number represents the row element and the second index number represents the column element.

Example 1:

An array variable declared as Dim B(1,5) has one row with five columns as shown below.

Example 2:

An array variable declared as Dim C(3,4) has three rows with four columns each as shown below.