Arrays as variables

You can create or modify an array variable using a Store step or the Manage Variables dialog, as described in the Procedure for adding and managing variables section in Chapter 25: Variables and the Store step.

As with other variables, when defining an array variable, you must select the type of data that the array will contain; for example, you can specify a Numeric array, String array, or Object array. Unlike other variables, arrays have unique qualities, such as size; they also allow you to manipulate their content with array operations (from the Store step).

Array size

Arrays in Matrox Design Assistant are one-dimensional and one-based; each array element has a single index and the index value of the first element is 1. By default, an array has an infinite size (no maximum length). Such arrays are automatically resized when necessary to contain the required number of elements. If required, you can specify a maximum array length (for example, to limit memory use).

When you add an element to an array, it is put at the end. Adding an element to an array that does not have an infinite size, and that has reached its specified maximum length, removes the first element and appends the newest one to the end of the array. This is sometimes called a circular buffer, or trend data buffer. This can be useful, for example, when calculating the average of a set of a values that change continuously.

Adding values to an array

When you first create an array variable, you are presented with the Add variable dialog. The array is empty; it has no elements and no initial value.

You can, at this time, specify an initial value or initial value expression; for example:

[1,2,3], which is a valid initial value when Type is set to Numeric array.
{["one", "two", "three"]}, which is a valid initial value when Type is set to String array.

Note that string arrays must be enclosed in the evaluate-to-string operator ({}).
REPEAT (1,10), which is a valid initial value expression when Type is set to Numeric array.
RANGE (1,256), which is a valid initial value expression when Type is set to Numeric array.

For more information about specifying an initial value with the array operator [], see the Array operator section later in this chapter. You can also specify an array's initial value with the Set array operation.

Like all variables, array variables have a Reset Point and Persist Value property, as seen in the Add variable dialog. These properties specify whether array data is reinitialized (reset) for each inspection (main inspection loop), and whether array data is saved (persists) from one execution of the project to the next. For more information, see the Lifetime section in Chapter 25: Variables and the Store step.

Array operations

You can use the Store step to specify array operations that can add, replace, and remove array elements (thereby modifying the content of an array variable). To specify an operation, select the array variable and click on the Add operations button (or double-click on the variable name) from the Store step's Configuration pane. If you add an operation for a variable whose type is not array, you cannot specify a specific operation (for non-array type variables, the operation is intrinsically Set).

Possible array operations that you can specify are listed below. The most typical operations you will use are Set, Add, and RemoveAll.

Set. Completely replaces the content of the array with the specified new value(s). If you specify a simple value, such as one number or one string, the result is a one-element array that contains the value defined. To specify multiple values, use the array operator brackets, []; for example, [1, 2, 3].

If the value is an expression (an advanced value), the result is either an array of values or a one-element array, depending on the return value of the expression.

The result must respect the maximum length limits of the array variable. For example, in an infinite length array, if you set the value to [1,2,3,4,5], the result is the array [1,2,3,4,5]. However, if the array variable's maximum length is 4, the result would be the array [1,2,3,4].
Add. Adds elements to the end of the array.
RemoveAll. Removes every element in the array. This returns an empty array.
SetAtIndex. Replaces the element(s) in the array, starting from the specified index, with the specified new value(s). For example, if an array holds [1,1,1,1,1] and the passed values are [2,2,2] at index 3, the resulting array is [1,1,2,2,2].

You cannot set a value at a start index that is more than one element beyond the current size of the array. For example, if an array holds [1,2,3,4,5], specifying a start index between 1 and 6 inclusive is permissible: passing values [0,0,0,0] to [1,2,3,4,5] at index 6 outputs the array [1,2,3,4,5,0,0,0,0]. Whereas, in this case, passing a value at start index 7 will return an error. Each element of the array must contain a value; therefore, the array must grow without having 'null' elements.
Insert. Inserts elements at the specified index, shifting each of the array's original elements, starting at the specified index. In the case of inserting an array, the elements are shifted by the length of the inserted array.

As with SetAtIndex, inserting an element at an index greater than the current size of the array plus one returns an error.
Remove. Removes elements from the array, starting from the specified index and up to a specified count (number).

Note that, to expand the space in which you specify the value to store, click on the Add... arrowhead button to point it left. If necessary, you can double-click on the name of the array variable to open a dialog that is dedicated to specifying array operations.

Like all variables, array variables can be enabled (conditionally enabled) or disabled by clicking the checkbox next to the variable name. This indicates whether the variable will be set when the step runs.

You can specify additional array operations for the same array variable within the same Store step by clicking the plus button next to the array variable name. To delete an operation, select it and click the X button. The top-down order of operations indicates the order in which they are executed. To modify this order, select the operation and click on the up or down arrowhead button in between the plus and X buttons.

To specify an advanced value (build expressions) for an array variable, double-click in the Value to store field or click on the Alternate options button to the right of that field. You can also use the Alternate options button to specify a linked value.

In following example, an array is constructed piecewise with 3 array operations (Set, Add, and Add), each of which uses an array function (RANGE, REPEAT, and RANGE) to build their respective expression:

For more information about using functions with array operations to build expressions, see the Array functions section later in this chapter.

Referencing array elements

When linking to an array while building an expression (for example, as the parameter of an array function), it is important to specify whether you want to consider the entire array or just one element from it.

In the Advanced editor, you can quickly select the required array variable from the tree structure. Right-click on the variable to bring up the Array Variable context menu, which lets you select either a link to the entire array (Insert link to array) or to the first element (Insert), as required. Double-clicking the variable has the same effect as choosing Insert from the context menu. To access another element of the array besides the first one, choose Insert and then manually change the index number located between the parentheses in the displayed expression.

You can also retrieve an element of an array using the ELEMENTAT function. For example, ELEMENTAT(Variables.myArray, 2) returns the second element.

If you attempt to access an element beyond the range of elements stored in an array, this results in both a design-time and a runtime error. You can check the number of elements in the array using the function COUNT. You can also use the ItemCount keyword in an expression to refer to the total number of elements in the array. See the Array functions section later in this chapter for an explanation of keywords.

To check if specific indices of an array exist, you can use the ISVALID function. For example, if the variable myArray contains 5 elements, ISVALID(Variables.myArray(8)) returns "false", since there is no eighth element.

If you pass a single element of an array to a function expecting an entire array, an error is generated. For more information on runtime errors, see the Runtime error handling subsection of the Procedure for using the Status step and Error step section in Chapter 23: Flow control steps.