# 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(3) = "Arizona"
' and so on.
Print states(2)

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"
' ...
' 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
statesAnd10CitiesAndPeople(2,1,2) = 109957
'...
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:

Element

Description

Dim

Declares an array with Private scope.

Public, Private

Public declares an array with Public scope. Private declares an array with Private scope.

Static

Only 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.

arrayName

The 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.

bounds

A 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 dataType

Specifies 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
``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.