Arrays are collections of variables that can be accessed using a single name, which comes in very handy when dealing with sets of objects.

For instance, instead of using three variables to specify the height, width and depth of an object, you could create an array called dim (as in "dimension") which contains three elements. So instead of using a variable called height, you would use dim(1). Width would become dim(2), and dim(3) would be used instead of depth.

Why would you want to do this? The benefits may not be as apparent with an array this small, but imagine putting all the prices from a door price file into separate variables. Instead of doorPrice1 = $10, doorPrice2 = $20, etc you can simply have one value doorPrices which has an array value of [$10, $20, ..., etc]. Note that when you type in arrays you must include the square brackets. With an array, you also have the ability to loop through all the elements (with the For Each statement). If we wished to find the average door price and we had used separate variables, the obvious way to do it would be by using the Average function like this:

Average (doorPrice1, doorPrice2, doorPrice3, ...)

This method is tedious and error-prone, especially if there are many door prices. What happens when you add a new doorPriceX variable and forget to update the function? If we had used arrays to store the prices, we could simply use:

Average (doorPrices)

This is possible because mathematical functions that take a variable number of parameters can also take arrays as parameters. See below for details on Expansion of array parameters.

Two Types of Array

The first type of array is the one used in the examples above... one variable containing multiple elements, where each element can be accessed using its numerical index in parentheses, e.g. doorPrices(3). If you have any experience with a programming language, this is the array behaviour you are probably familiar with.

The other type of array is similar to using a collection of separate variables, except that it has some of the beneficial properties of a true array. You can create elements with a statement like benchHeight["low"] = 820mm. Note that instead of a numerical index, you can use any type of value to specify the element, in this case a text string is used. This is very useful because it effectively maps one set of values (the indexes) to another (the values) where all values can be of any type. Lookup table operations frequently use this kind of array.

The difference between this and the first type of array is that each element is essentially a different variable. There is no single variable called benchHeight, even though the elements benchHeight["low"], benchHeight["med"] and benchHeight["high"] may exist. This means you can't use the second type of array with Array functions because there is no single variable that is an array. For example, you can use Max (doorPrices) but not Max (benchHeight) because benchHeight will be undefined. To avoid confusion, we will herein refer to the first type of arrays as indexed arrays, and the second type as associative arrays.

Indexed Arrays

As shown above, a numerical index in parentheses after the array name is used to access the elements in the array. If you accidentally use square brackets (e.g. doorPrices[1] = $10), this will create a new associative array separate from the existing array.

The index numbers in an array start from 1, as opposed to zero as in some programming languages (C, Java, etc). This means that the first item in an array has an index of 1, the second has index 2 and so on. You can also use an expression inside the brackets as long as it evaluates to a valid index, such as doorPrices(4 * 0.5) or doorPrices(Abs (-2)) (which are both the same as doorPrices(2)).

Creating Arrays

Entire indexed arrays can be written by enclosing the set of elements in square brackets, e.g. [47mm, 85mm, 104mm]. To create a new array, you can either use this format (e.g. doorPrices = [$10, $20, $30]) or use the Array function like this: doorPrices = Array ($10, $20, $30). Being able to write arrays out like this also means you can pass arrays directly to functions instead of assigning them to a variable first.

The elements of an array can be of any type. For the special case of arrays of Point2D or Point3D elements, there is a shorthand way of initializing them. The normal initialization would be, for example, [Point2D(1,2),Point2D(3,4),Point2D(5,6)] This can be written more concisely as Point2D([[1,2],[3,4],[5,6]])

The values you use to create arrays can also be expressions that evaluate to the desired values, e.g. Array (Cos(60), 45 / 3, LCase("TEST"), Sqrt(64)) results in [0.5, 15, "test", 8].

To quickly create arrays of numbers (or numerical values), you may find the range function useful. For instance, to create an array of all the even numbers from 10 to 50, you can write [10 to 50 step 2] instead of manually entering [10, 12, 14, ..., 50]. The range function takes two parameters - a lower and upper bound with the "to" keyword between them. It also takes an optional "step" parameter, which is the amount to increase the count by for each element (the default "step" is 1). You may use negative numbers for any of the parameters, but make sure the upper limit is higher than the lower one unless "step" is negative. Using a negative value for "step" makes the elements count downwards from the first value to the second one. e.g. Array (5 to 1 step -1) = [5, 4, 3, 2, 1]. A final point to note about the range function is that you can use it for any element in an array, for example:

["text", 1 to 3 step 0.75, 35deg, 900mm to 1.1m step 100mm] = ["text", 1, 1.75, 2.5, 35deg, 900mm, 1000mm, 1100mm]

Using Arrays with Functions

A great feature of indexed arrays is that because they are a single variable, you can use them in most functions just like any other variable. Functions that accept arrays as parameters will usually also return the result as an array. This means that you can perform a function on every element in an array with a single statement, without having to loop through the array and perform it individually on each element. A few examples will help illustrate this (refer to the function reference if you are unsure on what any of these functions do):

Len ( ["first", "another", "last one"] ) = [5, 7, 8]

Power ( [3, 5, 7], 2) = [9, 25, 49]

Ucase ( ["one String", "Two strings"] ) = ["ONE STRING", "TWO STRINGS"]
 

When an array is passed to one of these functions along with regular numerical parameters, the array is expanded or flattened first, which means that it becomes a list of values just like the other parameters. This means that Sum (8, [3, 9], 6) is the same as Sum (8, 3, 9, 6) for example, where [3, 9] is an array constant.

You will notice that the arrays used in the examples above are never assigned to a variable; they are typed out in the manner described previously and passed straight to the function. This can be useful sometimes, but you will usually want to assign an array to a variable so that you can use it again later.

Evaluation of unary or simple functions from arrays are allowed, for example:-
let funcs := ["%1 * %1", "3 + 1"];
funcs(1)(3) + funcs(2)()

With the result:-
(3 * 3) + (3 + 1) which is equivalent to (9 + 4) which equals 13

Functions that don't return a value (such as Action functions) will be executed once for each value in the array. For example, passing an array of strings to the Msgbox function will pop up a separate message box for each string, one after the other.

Nested Arrays

It is possible that an element inside an array is in fact another array... we call these nested arrays. For example, suppose you wanted an array that contained some of the section names in a cabinet. You might have "door", "back", "shelf1", shelf2" and so on, but it would be handy to group the shelf sections together (this example was chosen because it parallels the idea of nested sections and containers with relation to cabinet construction). So to keep the shelves together, we place them in another array within the main one to give:

cabSections = ["door", ["shelf1", "shelf2"], "back"]

Since the array of shelves is treated just like any other single value, the cabSections array really only has three elements: a string, an array, and another string. To access the elements in the shelves array, we have to first access the shelves array itself using cabSections(2), and then specify another index within that. So to refer to the value "shelf1", we have to use cabSections(2)(1). Arrays can be nested to several levels.

Associative Arrays

As mentioned above, the elements of associative arrays are effectively the same as regular variables. The difference is that you can refer to those elements using a key. As with indexed arrays, you can also use any expression that evaluates to a valid key. You can use this property to loop through an associative array, perhaps using the contents of an indexed array as the key values. An element of an associative array is specified by the key in square brackets after the array name, e.g. panelType[450mm].

The important thing to remember about associative array elements is that they cannot be treated as a single object like an indexed array can, so only individual elements can be passed to functions and so on.

Unlike indexed arrays, you are able to modify the value of an element at any time - in fact this is the only way to create a new element, as there is no equivalent of the Array function for associative arrays.