Array arguments

The XLL+ Function Wizard can be used to mark arguments as arrays of one or two dimensions, and to define further constraints.

The Wizard will generate code to read the data at run-time and to generate error messages if the input is unacceptable.

Setting the dimensions

You can set the dimensions of the selected argument in one of the following ways:

1. Scalar,Vector and Matrix tool-buttons on the Arguments toolbar
2. Argument - Argument Dimensions menu option
3. Ctrl+0, Ctrl+1 or Ctrl+2 shortcut keys
4. Using the Array tab of the Argument Window

Note that arguments with native Excel types (COper, CXlArray and CXlOper) cannot be marked as arrays.

Vector layout

The Vector layout combo field appears on the Array tab of the Argument Window when the argument is marked as a vector. You can select one of the following values, to constrain the layout of vector inputs:

• Row or column - The input must be a vector of either type, containing either multiple rows or multiple columns, but not both.
• Row - The input must contain one or more columns, in a single row, otherwise an error message will be generated.
• Column - The input must contain one or more rows, in a single column, otherwise an error message will be generated.

Matrix layout

The Matrix layout combo field appears on the Array tab of the Argument Window when the argument is marked as a matrix. You can select one of the following values, to control how matrix inputs are interpreted:

• Columns together - The data will be read column-wise, with all the cells of any column stored together in the C++ storage. Thus the C++ data storage can be navigated using [row, column] coordinates. This is the default setting.
• Rows together - The data will be read row-wise, with all the cells of any row stored together in the C++ storage. Thus the C++ data storage can be navigated using [column, row] coordinates.

The Matrix data combo field also appears on the Array tab of the Argument Window. You can select one of the following values, to control how matrix inputs are stored in the generated code:

• Pointers - The data will be held as an array of pointers, each pointing to the contents of a row or a column (depending on the value of the Matrix layout setting). This is the default setting.
• Continuous - The data will be held in a single long array.

You should choose the setting that best suits the destination of your data. If your existing functions expect continuous data, then the Continous setting will produce faster run-time code.

Note that you can use the ple::flatreader<T>() or ple::ptrreader<T>() functions to pass data from a C++ matrix object to an existing function in appropriate form. The Matrix data setting does not prevent either form being used; but it does improve efficiency if the setting matches the usage of the matrix data.

Bounds

Arguments marked as Vector or Matrix may be marked as bounded, using the Bounded check-boxes on the Array tab of the Argument Window. A matrix argument may be bounded in one or both of its dimensions.

If a dimension is bounded, then code is generated at run-time that constrains the size of the dimension.

The UBound field may be set to contain an integer, in which case the dimension must contain precisely that number of cells, or the input will be rejected and an error message will be generated, such as:

#Error: expected 6 rows for MyArg

The UBound field may be set to contain a variable name, in which case code will be generated to:

1. instantiate a variable of that name as a long
2. initialise the variable to the value -1
3. assign the size of the dimension to the variable when the input is read into an array object

If the same variable is used to bind dimensions of more than one argument, or both dimensions of a single argument, then the size of each of those dimensions must match precisely, or the wrongly sized input will be rejected and an error message will be generated.

See also Bounded input arrays.

Fill flag

The Fill flag can be set on the Array tab of the Argument Window. The flag controls how empty cells within arrays are treated. It may be set to any of the following values:

• No fill, in which case empty space at the lower and/or right-hand extremes of the input array will be truncated.
• Fill used area, in which case empty space at the lower and/or right-hand extremes of the input array will be truncated, but empty cells within the input array will be populated with zeroes or blanks.
• Fill all, in which case empty space at the lower and/or right-hand extremes of the input array will be populated with zeroes or blanks, as will empty cells within the input array.

See Also

Function Wizard