Fixed arrays

Declaring a fixed size array

When you declare a fixed size array, you specify the data type, the number, and the organization of the elements that it will hold. You specify the data type of an array's elements in the As dataType clause of the declaration:

' Declare a one-dimensional array of strings.
Dim aStringArray(1 To 10) As String
' Declare a two-dimensional array of Variants.
Dim myVarArrayV(1 To 10, 1 To 10) As Variant

If the values that the array is going to hold belong to one of the scalar data types that LotusScript® recognizes, you can omit the As dataType clause and instead specify the data type by appending the appropriate data type suffix to the name of the array:

' Declare a one-dimensional array of strings.
Dim aStringArray$(1 To 10)
' Declare a two-dimensional array of integers.
Dim anIntArray%(1 To 10, 1 To 10)

If you omit both the suffix and the As dataType clause, LotusScript® checks to see if the array name is covered by any applicable Deftype statement. If it is, LotusScript® defines the array's elements to be of the appropriate data type. Otherwise, LotusScript® defines them to be of type Variant:

DefInt A-C
' Declare an array of integers.
Dim arrayOfInts(1 To 10)
' Declare an array of Variants.
Dim otherArrayV(1 To 10) 

You specify the number of elements in an array and the number of dimensions along which they are organized in the bounds list. The lower and upper bounds of an array dimension can be any numeric constant between -32768 and 32767, inclusive, though the constraint that a fixed-sized array local to a procedure can take up no more than 32K bytes of storage means that the range between lower and upper bounds in a multidimensional array must be smaller than this. The memory needed for an array depends on the size of the array and the storage needed for an element of the array. The size of an array is the total size of the elements in it. It is the product of the sizes of all the dimensions.

For example:

Dim arrayOfSingles(1 To 5, 1 To 10, 1 To 2) As Single

The dimensional lengths are 5, 10, and 2, so arrayOfSingles holds 100 elements. The actual storage needed for all of these elements is 400 bytes, since one value of Single data type takes up four bytes of storage.

For example:

Dim myStats(1980 To 1983, 1 To 4, -2 To 2) As Currency

Here the dimensional lengths are 4, 4, and 5 (1980, 1981, 1982, 1983; 1, 2, 3, 4; -2, -1, 0, 1, 2) for a total of 80 elements, each of which requires 8 bytes of storage. The amount of memory necessary to store myStats is therefore 640 bytes.

You might use such an array as myStats to hold some number of values distributed over a bell curve for each quarter of the years from 1980 to 1983 inclusive. The reason why you might use the subscript ranges 1980 To 1983, 1 To 4, and -2 To 2 instead of 1 To 4, 1 To 4, and 1 To 5 is to have a mnemonic device to make entering and retrieving values in the array more intuitive: to enter the value for the curve in the second quarter of 1982, you would use a statement like this:

myStats(1982, 2, -2) = 123.456

This example demonstrates that a dimension's lower bound doesn't have to be 1, although it is usually convenient to have a dimension's lower bound be 1 or 0. LotusScript® lets you set 1 or 0 as the default lower bound for the dimensions of all arrays that you declare in a module by including the appropriate Option Base statement in the module. Option Base 0 is the LotusScript® language default but your product may choose a different setting, which you can override.

For example:

Option Base 0
' Declare a 120 x 4 array, both of whose dimensions
' are zero origin. This is the same as saying 
' Dim empSpacesA(0 To 119, 0 To 3) As String
Dim empSpacesA(119, 3) As String

' Declare a 3 x 4 x 10 array, all of whose dimensions
' are zero origin. This is the same as saying
' Dim EmpSpacesB(0 To 2, 0 To 3, 0 To 9) As String 
Dim empSpacesB(2, 3, 9) As String 

Another example is:

Option Base 1
' Declare a 120 x 4 array, both of whose dimensions
' are one origin. This is the same as saying 
' Dim empSpacesA(1 To 120, 1 To 4) As String
Dim empSpacesA(120, 4) As String

' Declare a 3 x 4 x 10 array, all of whose dimensions
' are one origin. This is the same as
' Dim EmpSpacesB(1 To 3, 1 To 4, 1 To 10) As String
Dim empSpacesB(3, 4, 10) As String

You can mix explicit and implicit lower bound specifications in a declaration:

Option Base 0
Dim myStats(3, 1 To 2, -2 To 2) As Currency
' The first dimension of this 4 x 2 x 5 array is 0 To 3.

Dim arrayOfSingles(1 To 5, 9, 1) As Single
' The second and third dimensions of this 5 x 10 x 2 array
' are 0 To 9 and 0 To 1, respectively. 

Use the LBound function to ascertain the lower bound of a dimension. The syntax is:

LBound ( arrayName [ , dimension ] )

where arrayName is the name of the array, and dimension is an integer that represents the dimension whose lower bound you want to ascertain. The default value of dimension is 1. So, for example:

Option Base 1 
Dim myStats(1980 To 1983, 2, -2 To 2) As Currency
Print LBound(myStats)
' Output: 1980 (the lower bound of the first dimension).
Print LBound(myStats, 2)
' Output: 1 (the lower bound of the second dimension). 

You can ascertain the upper bound of a dimension with the UBound function.

Referring to the elements of an array

How you assign or refer to values in an array depends on the data type of the array's elements. This section describes how to assign values and refer to array elements of one or another of the scalar data types.

You assign a scalar value to an element in an array with a statement of this form:

arrayName( S1, S2, S3,... ) = value

where arrayName is the name of the array; S1, S2, S3,... are subscripts, one for each dimension of the array; and value is the value you want to assign to the element whose location in the array is defined by S1, S2, S3,... For example:

Option Base 1
Dim empSpacesB(3,4,10) As String
empSpacesB(1,1,1) = "Maria Jones"
empSpacesB(1,1,2) = "Fred Smith"

Or:

Dim empSpacesA(120,4) As String
Dim counter As Integer
Dim LB1 As Integer
Dim LB2 As Integer
' Get lower bound of first dimension.
LB1% = LBound(empSpacesA, 1)
' Get lower bound of second dimension.
LB2% = LBound(empSpacesA, 2)
' For the first 40 elements in the first dimension,
' assign the value "Floor 1" to the first element
' in the second dimension; for the next 40 elements
' in the first dimension, assign the value "Floor 2"
' to the first element in the second dimension; and
' for the last 40, assign the value "Floor 3".
For counter% = LB1% to LB1% + 39
     empSpacesA(counter%, LB2%) = "Floor 1"
     empSpacesA(counter% + 40, LB2%) = "Floor 2"
     empSpacesA(counter% + 80, LB2%) = "Floor 3"
Next

You refer to the value of a scalar element in an array by the element's subscripts, as in this example which searches for parking spaces to which no employee has been assigned:

Option Base 1
Dim empSpacesB(3,4,10) As String
' Declare three String variables the quickest way
' to hold values for floor, section, and space.
Dim Flo$, Sec$, Spa$
' Declare six Integer variables the quickest way
' to hold values for the lower and upper bounds
' of the dimensions of empSpacesB for easy reference.
Dim LB1%, LB2%, LB3%, UB1%, UB2%, UB3%
' Initialize the array. Typically you do this by reading
' the data from a file rather than by hard-coding the
' values.
empSpacesB(1,1,1) = "Maria Jones"
empSpacesB(1,1,2) = ""
empSpacesB(1,1,3) = "Joe Smith"
' And so on down to the last space.
empSpacesB(3,4,10) = "Sal Piccio"
' Assign the lower and upper bounds of each dimension
' of empSpacesB to a variable.
LB1% = LBound(empSpacesB, 1)
LB2% = LBound(empSpacesB, 2)
LB3% = LBound(empSpacesB, 3)
UB1% = UBound(empSpacesB, 1)
UB2% = UBound(empSpacesB, 2)
UB3% = UBound(empSpacesB, 3)

' Loop through all the array elements and print
' the floor, section, and location of each space
' that has the empty string--that is, no employee name--
' as its value. Convert the floor, section, and space
' numbers to strings by calling the cStr function and
' passing it the appropriate subscript.
For counter1% = LB1% to UB1%
  For counter2% = LB2% to UB2%
    For counter3% = LB3% to UB3%
      If empSpacesB(counter1%, counter2%, counter3%) = "" Then
         Flo$ = "Floor " & cStr(counter1%) & " "
         Sec$ = "Section " & cStr(counter2%) & " "
         Spa$ = "Space " & cStr(counter3%) & " "
         Print Flo$ & Sec$ & Spa$ & "is empty."
      End If
    Next
  Next
Next