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 a fixed array once. At compile time, its size and storage requirements are set according to the specifications of its bounds list and the data type of its elements. At run time, storage is allocated for its elements, which are initialized like any ordinary variable of that data type. The array cannot be resized while the application is running.
• You declare a dynamic array once, but it can be sized and resized many times (with the ReDim statement) while the application is running. When you declare a dynamic array, you specify the data type of its future elements but include an empty bounds list, so LotusScript® doesn't allocate space in memory for those elements. You resize a dynamic array at run time when you know how many elements you want it to hold, at which time LotusScript® allocates the necessary storage space. The values of the elements of the array can be reinitialized or preserved each time you resize the array.

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

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

int a[5]

specifies 5 elements in array a, beginning with a[0] and continuing through a[4]. In LotusScript® and other BASIC-type languages, declaring

DIM a(5) as Integer

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.