An array variable gives a single name to a group of related values and organizes them in a list or table. Here are some of the advantages that using an array can provide over using regular variables:
Arrays are not difficult to use or understand, but they're not usually used in simple macros. Unless your macro needs to handle a lot of values, you probably don't need to use an array. The most common use for arrays in WordBasic is to list items in a custom dialog box. For more information on using arrays in custom dialog boxes, see Chapter 5, "Working with Custom Dialog Boxes."
Each variable within an array is called an element and shares a common name — the array name. Elements are distinguished from each other by a subscript, a unique number assigned to each element. Before you can assign values to the elements of an array, you must specify how many elements the array contains. To do so, you use the Dim statement. Here is the syntax:
Dim ArrayVariableName(LastElementNumber)
The first element of a WordBasic array is always numbered 0 (zero). This can be confusing because it means that the subscript number of the last element is one less than the number of elements. For example:
Dim Months$(11) 'Define an array with 12 elements
This instruction defines an array with 12 elements to hold the names of the months of the year. Because the first element is numbered 0 (zero), the twelfth element is numbered 11.
An array variable can be defined to hold either numbers or strings — a single array cannot hold both. The name of an array that contains string values must end with the dollar sign ($), just like a regular string variable.
After you have used the Dim statement to define an array, you can assign values to the elements within it. You can assign values to array elements just as you do to regular variables. Here is an example:
Dim FourWinds$(3) 'Define an array with four elements FourWinds$(0) = "East" FourWinds$(1) = "West" FourWinds$(2) = "North" FourWinds$(3) = "South"
Sometimes, it's useful to ignore an array's first element, numbered 0 (zero), so that you can assign your first value to the element whose subscript is 1, the second value to the element whose subscript is 2, and so on. The following example assigns string values to the array Weekdays$(7) so that the subscripts of elements 1 through 7 correspond to a number returned by the Weekday() function:
Dim Weekdays$(7) 'Define an array with eight elements Weekdays$(0) = "" 'Assign no value to first element Weekdays$(1) = "Sunday" Weekdays$(2) = "Monday" Weekdays$(3) = "Tuesday" Weekdays$(4) = "Wednesday" Weekdays$(5) = "Thursday" Weekdays$(6) = "Friday" Weekdays$(7) = "Saturday" MsgBox "Today is " + Weekdays$(WeekDay(Today()))
You can use a For…Next loop to assign values to some arrays. The following example first defines an array that has as many elements as the number of available fonts, a value returned by the CountFonts() function. Then a For…Next loop inserts the names of all the fonts into the array. Note that the array is dimensioned so that the number of the last element is CountFonts() - 1, since CountFonts() starts its count at 1, whereas (as noted earlier) array subscript numbering starts at 0 (zero).
Dim fontnames$(CountFonts() - 1) 'Define an array
For count = 0 To (CountFonts() - 1) 'Repeat CountFont() times
fontnames$(count) = Font$(count + 1) 'Assign font name Font$()
Next
You could use the fontnames$() array to present the list of font names in a custom dialog box. For information on using arrays in this way, see Chapter 5, "Working with Custom Dialog Boxes."
At times, it's useful for a macro to change the size of an array. For example, a macro that defines an array to hold all the fonts available on the current printer could later select another printer and reuse the original array to hold the new list of fonts. Because the second printer could have a different number of fonts available, the macro should resize the array before reusing it.
You use the Redim statement to resize an array. The syntax for Redim is exactly the same as for Dim:
Redim ArrayVariableName(LastElementNumber)
Note that when you resize an array, you also clear its contents. If you try to use the Dim statement to resize an existing array, Word generates an error.
The examples presented so far use arrays to order variables in a list. But you can also use arrays to order variables in a table. Suppose, for example, you wanted to create a variable for each day of the year. One way would be to define an array that lists 365 variables. For example:
Dim Year(364) 'Define an array with 365 variables
However, you could give more structure to these variables by placing them in a table. You could order them, for example, so that each row of a table represented a month and each column corresponded to a day:
Dim Year(11,30) 'Define an array with 12 rows and 31 columns
This kind of array is called a two-dimensional array, while those presented earlier in the chapter are one-dimensional arrays. You can create arrays with three or more dimensions — as many as there is room for in memory — but in practice, arrays with more than two dimensions are rare.
You define an array with more than one dimension by listing the number of elements in each dimension in the standard Dim statement. Here is the syntax for a two-dimensional array:
Dim ArrayVariableName(LastElementNumber1, LastElementNumber2)
In the following example of a two-dimensional array, both dimensions have five elements:
Dim MailingList$(4,4) 'Define a 5-by-5 two-dimensional array
Here is a visual representation of the 25 elements contained in the array.
Each cell in the table represents an element in the array — a slot for a string, because Dim MailingList$(4,4) defines a string array variable. Each pair of numbers represents the subscript for an element of the array. For example, MailingList$(2,1) indicates the second element in the third row. You could use this array to store five names, each with its own street address, city, state or province, and postal code. The first column would list the names, the second column would list the street addresses, and so on.
The following example creates a two-dimensional array that contains a multiplication table up to, and including, the number 10, and inserts the table into the active document:
Dim MultTable(10,10)
For N = 1 to 10
For M = 1 to 10
MultTable(N,M) = N * M
Insert Str$(MultTable(N,M)) + Chr$(9)
Next
EditClear -1
InsertPara
Next
In the example, the inner loop multiplies N and M, assigns the value to the element MultTable(N,M), and then inserts the product and a tab character into the active document. At the end of each row, the macro deletes the last tab character in the row and inserts a paragraph mark to start a new row.
You can use the SortArray statement to sort arrays in alphabetical or numerical order. The following example assigns the available font names to the array fontnames$() and sorts the array:
Dim fontnames$(CountFonts() - 1) 'Define an array
For count = 0 To (CountFonts() - 1) 'Repeat CountFont() times
fontnames$(count) = Font$(count + 1) 'Assign font name Font$()
Next
SortArray fontnames$() 'Sort font names
For detailed information, see SortArray in Part 2, "WordBasic Reference."