Lists

A list is a one-dimensional collection of elements of the same data type. You can change the size of a list at any time while the application is running and LotusScript® does not allocate any storage space at compile time for the elements of a list. Lists automatically shrink or grow when elements are deleted from or added to them. You access each element in a list by a unique String value, called a list tag.

You can declare a list at module level, in a procedure, or in the definition of a class (but not in the definition of a user-defined data type). You declare a list with the Dim statement or one of its variations:

If you omit the As dataType clause from the Dim statement and do not include a data type suffix character in the list's name, LotusScript® checks to see if the list name is covered by any applicable Deftype statement. If the name of the list is covered by a Deftype statement, then LotusScript® assigns that data type to the list's elements; otherwise, LotusScript® makes them type Variant.

A list is initially empty. You add elements to it with statements of the following form:

listName ( listTag ) = value

where listName is the name of the list, listTag is a string that uniquely identifies the element, and value is the value you want to assign to the element.

A List tag is essentially a key of type STRING. You use this this "key" to uniquely retrieve its associated data once it gets stored.

List tags can be case sensitive or case insensitive, depending on the setting for case sensitivity in the module in which the list is declared. If case sensitivity is in effect for the module, the list tags "A123" and "a123" are different tags; if case sensitivity is not in effect, they are the same and are used interchangeably. You can control whether case sensitivity is observed in string comparison in a module by including the Option Compare statement in that module. The syntax is:

Option Compare { Case | NoCase | Binary }

If you include the Case or Binary keyword, string comparison is case sensitive in the module. NoCase means that such comparisons are case insensitive. Option Compare Case is the default.

The following example illustrates how to declare a list, add elements to it, and refer to those elements. The elements in the list are of one of the scalar data types (String).

' Make string comparison case insensitive
' in this module.
Option Compare NoCase
' Declare a list--myList--to hold first names.
' The list tags will be unique IDs.
Dim myList List As String
Dim newTag As String
Dim newValue As String
' Put some elements in the list.
myList("A1234") = "Andrea"
myList("A2345") = "Vera"
myList("A3456") = "Isabel"
' Ask the user to enter an ID and a name.
newTag$ = InputBox$("Please enter your ID:")
newValue$ = InputBox$("Please enter your first name:")
' Add a new element to the list with
' the user's ID as the list tag and the user's name as
' the value of the new element.
myList(newTag$) = newValue$
Print myList(newTag$)
' Output: the name that the user entered