CXlOper::ReadMatrix

Reads data from a 2-dimensional array into a matrix of numbers or strings

[C++]
template< class T >
BOOL ReadMatrix(
   ple::imtx<T>& mat1,
   const char* pszArgName,
   CString& strError,
   long* plUBound1 = 0,
   long* plUBound2 = 0,
   long lFlags = XLA_ARRAY_FLAGS_STD,
   long lLBound1 = 0,
   long lLBound2 = 0,
   long lIgnoreRows = 0,
   long lIgnoreCols = 0
) const;
template< class T >
BOOL ReadMatrix(
   ple::imtx<T>& mat1,
   const char* pszArgName,
   CXlOper& xloError,
   long* plUBound1 = 0,
   long* plUBound2 = 0,
   long lFlags = XLA_ARRAY_FLAGS_STD,
   long lLBound1 = 0,
   long lLBound2 = 0,
   long lIgnoreRows = 0,
   long lIgnoreCols = 0
) const;
template< class T >
BOOL ReadMatrix(
   xlp::matrix<T>& mat2,
   const char* pszArgName,
   CString& strError,
   long* plUBound1 = 0,
   long* plUBound2 = 0,
   long lFlags = XLA_ARRAY_FLAGS_STD,
   long lLBound1 = 0,
   long lLBound2 = 0,
   long lIgnoreRows = 0,
   long lIgnoreCols = 0
) const;
template< class T >
BOOL ReadMatrix(
   xlp::matrix<T>& mat2,
   const char* pszArgName,
   CXlOper& xloError,
   long* plUBound1 = 0,
   long* plUBound2 = 0,
   long lFlags = XLA_ARRAY_FLAGS_STD,
   long lLBound1 = 0,
   long lLBound2 = 0,
   long lIgnoreRows = 0,
   long lIgnoreCols = 0
) const;

Parameters

mat1

A matrix class (descended from class imtx<T>) containing items of type T, whose contents will be replaced by the contents of the CXlOper.

The following types are directly supported for T:

• bool
• long
• unsigned long
• int
• unsigned int
• short
• unsigned short
• double
• float
• CString
• std::string

Any other type is treated as an enumerated type, and converted first to long and then to the specified type.

A matrix of double, whose contents will be replaced by the contents of the CXlOper.

pszArgName

The name of the argument that is being read. This will be used in any error strings that are generated.

strError

Reference to an error string buffer. If the function fails for any reason, a useful error string will be placed here, e.g. "MyArgName: expected number in cell 3".

plUBound1

Pointer to upper bound of first dimension (height). If it is null, then it is ignored. If it is not null then it is used to check that the upper bounds of various arrays are consistent.

See Bounded input arrays for more information on the use of upper bounds.

plUBound2

Pointer to upper bound of second dimension (width). If it is null, then it is ignored. If it is not null then it is used to check that the upper bounds of various arrays are consistent.

See Bounded input arrays for more information on the use of upper bounds.

lFlags

Flags controlling the conversion. See matrix & vector flags for a full list of flag values.

lLBound1

This will be used as a lower bound in the output matrix. lLBound rows containing default values (zero or blank) will be inserted at the start of the output matrix.

lLBound2

This will be used as a lower bound in the output matrix. lLBound columns containing default values (zero or blank) will be inserted at the start of the output matrix.

lIgnoreRows

The first lIgnoreRows rows of input will be ignored. This option can be useful for excluding labels.

lIgnoreCols

The first lIgnoreCols columns of input will be ignored. This option can be useful for excluding labels.

xloError

If any error occurs, a description will be put into xloError. It can then conveniently be returned as the result of the add-in function.

mat2

A matrix of the deprecated class matrix<T>, containing items of type T, whose contents will be replaced by the contents of the CXlOper.

Types supported are the same as for mat1.

A matrix of double, whose contents will be replaced by the contents of the CXlOper.

Return value

The function returns TRUE if the conversion was successful, FALSE if it failed for any reason.

If it fails, an explanatory error string will be written to strError or xloError. This should be returned to the user.

Remarks

This function extracts a rectangular range of numbers or strings from an array argument. Using the default flag values, it is reasonably 'smart': by default it truncates any empty cells at the end (right or bottom) of the input range.

However, a wide variety of other options are available, if you use other flag values and optional arguments. See matrix & vector flags for a full list of flag values.

See Bounded input arrays for more information on the use of upper bounds.

Coercion

If the CXlOper contains a reference to a range of cells, rather than the values of the cells, then this function will fail, and will return a message stating that the argument must be coerced before use.

You should write code to Coerce the input to a value, e.g.:

extern "C" __declspec( dllexport )
LPXLOPER ReadXlOper(const CXlOper* Arg1)
{
    CXlOper xloResult;
//}}XLP_SRC

    CXlOper valArg1;
    if (valArg1.Coerce(*Arg1) != 0)
        return CXlOper::RetError(xlerrValue);
    ple::mtx_ptrs<bool> matB;
    if (!valArg1.ReadMatrix(matB, "Arg1", strError))
        return CXlOper::RetString(strError);
    ...
}

It is generally simpler and faster to use a COper type to handle an array input. You should only use CXlOper to handle an array input if you need a CXlOper feature, such as a heterogeneous input that can contain either a value or a reference (COper does not support references).

For more information on the use of CXlOper for inputs, see Comparison of COper, CXlOper and CXlArray types.

Requirements

Header: xllplus.h

See Also

CXlOper Class | CXlOper Methods | Bounded input arrays | CXlOper::ReadVector()