Input conversion and validation functions

The conversion functions are listed below. All conversion that takes place in code that is generated by the XLL+ Function Wizard is done using these functions.

Function	Description
XlReadScalar	Read a scalar (single-cell) argument whose type is standard.
XlReadScalarEx	Read a scalar (single-cell) argument of extended type. Convert the value from an Excel form to that specified for the extended type.
XlReadVector	Read an array argument into a vector of values whose type is standard.
XlReadVectorEx	Read an array argument into a vector of values whose type is extended. Convert each cell's value from an Excel form to that specified for the extended type.
XlReadMatrix	Read an array argument into a matrix of values whose type is standard.
XlReadMatrixEx	Read an array argument into a matrix of values whose type is extended. Convert each cell's value from an Excel form to that specified for the extended type.
XlReadGroupedScalar	Read a scalar (single-cell) argument whose type is standard from a scalar group.
XlReadGroupedScalarEx	Read a scalar (single-cell) argument whose type is extended from a scalar group. Convert the value from an Excel form to that specified for the extended type.
XlReadGroupedVector	Read one column or row of a matrix argument into a vector of values whose type is standard from a vector group.
XlReadGroupedVectorEx	Read one column or row of a matrix argument into a vector of values whose type is extended from a vector group. Convert each cell's value from an Excel form to that specified for the extended type.

Flags

The input conversion and validation functions support a wide range of special behaviors, most of which are controlled by the flags parameter. The bits of the flags parameter are summarized below.

Topic	Flag	Description	Notes
Default	XLA_DEFAULT_EMPTY	Use a default value if the argument is missing or empty.	Ignored if vector or matrix. Ignored if group.
	XLA_DEFAULT_BLANK	Use a default value if the argument is a blank string.
	XLA_DEFAULT_ZERO	Use a default value if the argument's value is zero.
	XLA_DEFAULT_NONNUMERIC	Use a default value if the argument is not numeric.
Truncation	XLA_TRUNC_ONEMPTY	Truncate an array if a cell is empty.	Ignored if scalar. Ignored if XLA_FILL_ALL is used. See Truncation for more details.
	XLA_TRUNC_ONBLANK	Truncate an array if a cell contains a blank string.
	XLA_TRUNC_ONZERO	Truncate an array if a cell contains a zero value.
	XLA_TRUNC_ONNONNUMERIC	Truncate an array if a cell's contents are not numeric.
Cell default	XLA_FILL_USED_AREA	Truncate an array after the last non-empty cell. Empty cells within the used area are filled with the default cell value.	Ignored if scalar. See Fill for details of the interaction between fill flags and truncation flags.
	XLA_FILL_ALL	Empty cells within the array are filled with the default cell value.
Fill values	XLA_CELL_DEFAULT_EMPTY	If an array is to be filled, fill cells that are empty.	Ignored if scalar. Ignored unless either XLA_FILL_USED_AREA or XLA_FILL_ALL is used.
	XLA_CELL_DEFAULT_BLANK	If an array is to be filled, fill cells that contain blank strings.
	XLA_CELL_DEFAULT_ZERO	If an array is to be filled, fill cells that contain the value zero.
	XLA_CELL_DEFAULT_NONNUMERIC	If an array is to be filled, fill cells that contain non-numeric values.
Array	XLA_FLAG_REJECT_NULL_ARRAY	The array argument may not be entirely empty.	Ignored if scalar.
Vector	XLA_FLAG_VECTOR_COLUMN	A vector argument must be vertical, i.e. a column.	Ignored if scalar or matrix.
	XLA_FLAG_VECTOR_ROW	A vector argument must be horizontal, i.e. a row.
Matrix	XLA_FLAG_TRANSPOSE	The contents of a matrix argument will be transposed before storage; array[i][j] will be swapped with array[j][i].	Ignored if scalar or vector.
	XLA_MATRIX_LAYOUT_ROWS	The contents of a matrix argument will be stored with rows as the innermost dimension; an item will be found in the output matrix as matrix[column][row]. Without this flag, matrix values will always be stored with columns as the innermost dimension, and items are found at matrix[row][column].
	XLA_MATRIX_DATA_VALUES	The contents of a matrix argument will be stored in one continuous array. Without this flag, matrix values will always be stored in an array of pointers, each of which points to an equal-sized array.
Bounds	XLA_BOUND_UBOUND_INNER	A array whose size is constrained will treat the constraint as the index of the upper bound, i.e. size - 1.	Ignored if scalar, or if bounds are not constrained.
	XLA_BOUND_UBOUND_AUTO	A array whose size is constrained will treat the constraint as the index of the upper bound, i.e. size - 1, if the lower bound of the dimension is not zero. If the lower bound is zero (or is not specified) then the constraint will be treated as the size of the array (in the given dimension).
Grouping	XLA_OPER_IS_GROUP	The argument is a member of a group.	Ignored if matrix.

Standard types

The standard built-in types are listed below.

Name	C++ type
Boolean	bool
Double	double
Integer	int
Short integer	short
Unsigned short integer	unsigned short
String	CXlStringArg

Extended types

Extended types are defined in extension files, and registered using the Manage extensions command.

See Extended types in the User Guide for more information.

Groups

Groups are a way of representing multiple inner arguments as a single Excel argument. This is useful when there are too many arguments for Excel to handle, and for helping with layouts of complicated arguments.

See Grouping arguments in the User Guide for more information.

Truncation

The truncation flags and the fill flags control how the conversion functions treat the sizes of arrays. Let us say we have an argument x, which is defined as a vector of numbers (std::vector<double>). The user passes cell range A1:A3 as x. A1 and A2 contain numbers, but A3 is empty. If none of the truncation flags are set, then the conversion function will fail, with an error message like: "Expected a number for x[3]". However, if the XLA_TRUNC_ONEMPTY flag is set, then the conversion function will discard cell A3, and set x to contain just two numbers (A1 and A2).

Truncation of arrays is very convenient for the user of an add-in function. When assigning an array argument to a function, the user can specify an area that is large enough to contain the array, and also contains some spare, empty cells. If the array changes size, the formula does not need to be changed, because the conversion function automatically truncates the array, discarding the empty cell range.

By default, new vector arguments have the standard truncation flags set: XLA_TRUNC_ONEMPTY and XLA_TRUNC_ONBLANK. XLA_TRUNC_ONBLANK is useful because it allows the use of formulae within the array such as =IF(C2<>0,D2/C2,""). A blank cell is treated as an empty cell, and the user thereby has full control over the size of their array argument.

Fill

The two fill flags, XLA_FILL_ALL and XLA_FILL_USED_AREA, work in conjunction with the truncation and cell default flags to allow special behavior when a conversion function reads an array that is not full populated (i.e. sparse).

If XLA_FILL_ALL is set, then the function will treat every empty cell within the array as if it contained the default cell value passed to the conversion function. This behavior is useful for sparsely populated arrays. Thus if we have a numeric vector argument x and a default cell value of -999.0, and the user passes a range {100.0, empty, 50.0, empty}, the conversion function will return the vector {100.0, -999.0, 50.0, -999.0}.

The cell default flags control which cells are considered to be empty. Normally, the flags XLA_CELL_DEFAULT_EMPTY and XLA_CELL_DEFAULT_BLANK are used in conjunction with a fill flag.

While the XLA_FILL_ALL flag is useful for reading sparse arrays that are of fixed size, the XLA_FILL_USED_AREA can be used to read sparse arrays of variable size. The logic used by the conversion function is a little more complicated. First, the function searches from the end of the range for the last populated cell. (The truncate flag values are used to control which cells are considered to be populated or not populated.) All cells after the last populated cell are discarded; the remaining cells are considered to be the "used area". Next, any empty cells within the used area are replaced with the default cell value.

Say a numeric vector argument is marked with the following flags: XLA_FILL_USED_AREA | XLA_CELL_DEFAULT_EMPTY | XLA_TRUNC_ONEMPTY, and has a default cell value of -999.0. The user passes the following array: {5.0, empty, 6.1, 1.2, empty, empty, empty}. The last 3 cells will be discarded, and then the second cell will be treated as filled, giving a result of {5.0, -999.0, 6.1, 1.2}.

Exceptions

The table below lists the exceptions that may be thrown by the conversion functions.

Type	Description
CXlConversionException	General conversion error.
CXlUninitializedOperException	The argument has not been properly initialized. This cannot occur in code that was generated by the wizard, but it can occur if the conversion functions are used on local CXlOper variables that were instantiated by the developer. CXlUninitializedOperException inherits from CXlConversionException.