XLL+ Class Library (6.3)

::XlReadMatrix

Transform a CXlOper into a matrix

template< class T >
void XlReadMatrix(
   const CXlOper& xlo,
   ple::imtx<T>& value,
   CMatrixConvertParams<T>& params
);
template< class T >
void XlReadMatrix(
   const CXlOper& xlo,
   ple::imtx<T>& value,
   const wchar_t* argName,
   unsigned long flags = 0,
   long* expectedSize0 = NULL,
   unsigned long lowerBound0 = 0,
   long* expectedSize1 = NULL,
   unsigned long lowerBound1 = 0,
   const T& defaultCellValue = T()
);

Parameters

xlo

A reference to the input passed by Excel.

value

A reference to a variable into which the results will placed, if the conversion is successful.

params

A set of parameters that control the conversion.

See CMatrixConvertParams<T> for details.
argName

The name of the argument that is being converted. This will be used in error messages.

flags

A set of flags that control the conversion. See Conversion functions for a list of values.

expectedSize0

A pointer to variable that will receive the number of rows in the matrix. If it has already been set (i.e. does not have a value of -1), and the height of the matrix is not equal to the value. then an exception of type CXlConversionException will be thrown, along with a user-friendly message, such as "Expected 15 rows in X". If the pointer is NULL, then the argument will be ignored.

lowerBound0

The number of empty rows to insert at the start of the result matrix. If you are going to pass the matrix to a library function that expects arrays to be 1-based, then this value should be set to 1.

expectedSize1

A pointer to variable that will receive the number of columns in the matrix. If it has already been set (i.e. does not have a value of -1), and the width of the matrix is not equal to the value. then an exception of type CXlConversionException will be thrown, along with a user-friendly message, such as "Expected 15 columns in X". If the pointer is NULL, then the argument will be ignored.

lowerBound1

The number of empty columns to insert at the start of the result matrix. If you are going to pass the matrix to a library function that expects arrays to be 1-based, then this value should be set to 1.

defaultCellValue

The default value that will be used for empty cells, if the appropriate flags have been set for the conversion.

Remarks

If the function fails for any reason, an exception of type CXlConversionException is thrown. This will be caught by the outer wrapper function, and converted into an appropriate form to be returned to Excel.

Requirements

Header: xlpconvert.h

See Also

Global conversion functions