LOTUSSCRIPT LANGUAGE


Arrays
An array is a named collection of elements of the same data type, where each element can be accessed individually by its position within the collection. A LotusScript array can have a maximum of eight dimensions.

The position of an element in an array can be identified by one or more coordinates called subscripts (or indexes). The number of subscripts necessary to identify an element is equal to the number of the array’s dimensions. In a one-dimensional array, a given element’s position can be described by one subscript; in a two-dimensional array, it takes two subscripts to locate an element.

For example, in a one-dimensional array whose elements are the names of the states of the United States, a single subscript identifies the position of a given state in the collection:

Dim states(1 to 50) As String
states(1) = "Alabama"
states(2) = "Alaska"
states(3) = "Arizona"
' and so on.
Print states(2)
' Output: Alaska

In a two-dimensional array whose elements are the names of the ten most populous cities in each state, the first subscript identifies the state, and the second subscript identifies the city:

Dim statesAnd10Cities(1 to 50, 1 to 10) As String
statesAnd10Cities(1,1) = "Alabama, Birmingham"
statesAnd10Cities(1,2) = "Alabama, Mobile"
' ...
statesAnd10Cities(2,1) = "Alaska, Anchorage"
statesAnd10Cities(2,2) = "Alaska, Fairbanks"
' and so on.
Print statesAnd10Cities(1,2)
' Output: Alabama, Mobile

A three-dimensional array might contain the numbers of adult females, adult males, and children in each of the ten most populous cities in each state:

Dim statesAnd10CitiesAndPeople(1 to 50, 1 to 10, 1 to 3) _
  As Double
statesAnd10CitiesAndPeople(1,1,1) = 120748
' Number of adult males in Birmingham, Alabama.
statesAnd10CitiesAndPeople(1,1,2) = 145104
' Number of adult females in Birmingham, Alabama.
' ...
statesAnd10CitiesAndPeople(2,1,1) = 116381
' Number of adult males in Anchorage, Alaska.
statesAnd10CitiesAndPeople(2,1,2) = 109957
' Number of adult females in Anchorage, Alaska.
'...
Print StatesAnd10CitiesAndPeople(1,1,2)
' Output: 145104

The size of an array — the number of dimensions and the extent of each individual dimension — is defined by the array’s bounds list. Each dimension has a lower bound and an upper bound, specified as integer values.

LotusScript supports both fixed and dynamic arrays.


You declare an array with the Dim statement or one of its variations, as summarized in the following diagram:

Breaks down the module into a Procedure, Class, and User-defined data types

The syntactic elements in the declaration of an array are summarized as follows:

ElementDescription
DimDeclares an array with Private scope.
Public, PrivatePublic declares an array with Public scope. Private declares an array with Private scope.
StaticOnly applicable to arrays declared inside a procedure. Static arrays retain their values (rather than going out of existence) between calls to the procedure while the module remains loaded.
arrayNameThe name of the array. At module level or within a procedure, arrayName can end in one or another of the data type suffixes that LotusScript recognizes. This determines the type of data that the array can hold. You can append a data type suffix to the name of an array only if you do not include the As dataType clause in the declaration.
boundsA comma-separated list of bounds for each dimension of arrayName. The bounds for each dimension are specified in the form:
[lowerBound To] upperBound
The lowerBound is the minimum subscript allowed for the dimension, and upperBound is the maximum. If no lowerBound is specified, the lower bound for the array dimension defaults to 0, unless the default lower bound has been changed to 1 using the Option Base statement.
Array subscript bounds must fall in the range -32768 to 32767 inclusive. For a fixed array, bounds must be integer constants, that is, values known at compile time.
As dataTypeSpecifies the type of data the array can hold. Required in the declaration of an array within the definition of a user-defined data type or class, but optional in the declaration of a variable at module level or within a procedure. If you include this clause, arrayName cannot end in a data type suffix character. dataType can be any of the scalar data types, Variant, a user-defined data type, or an object reference.
Note In many programming languages, such as C, declaring an array
specifies 5 elements in array a, beginning with a[0] and continuing through a[4]. In LotusScript and other BASIC-type languages, declaring
specifies 6 elements in array a, beginning with a[0] and continuing through a[5]. In this case the lower bound of the array is 0 and the upper bound is 5. You can change the base default to 1 instead by using the Option Base statement.

See Also