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 (singlecell) argument whose type is standard. 
XlReadScalarEx  Read a scalar (singlecell) 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 (singlecell) argument whose type is standard from a scalar group. 
XlReadGroupedScalarEx  Read a scalar (singlecell) 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. 
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 nonempty 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 nonnumeric 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 equalsized 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. 
The standard builtin 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 are defined in extension files, and registered using the Manage extensions command.
See Extended types in the User Guide for more information.
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.
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 addin 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.
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}
.
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 CXlUninitializedOperException inherits from CXlConversionException. 