COper::ReadGroupItem

Reads a single value from an array into a number or string

[C++]
template< class T >
BOOL ReadGroupItem(
   T& result,
   const char* pszArgName,
   long lItem,
   const char* pszItemName,
   CString& strError,
   bool bStrict = false
) const;
template< class T >
BOOL ReadGroupItem(
   T& result,
   const char* pszArgName,
   long lItem,
   const char* pszItemName,
   CXlOper& xloError,
   bool bStrict = false
) const;

Parameters

result

A buffer for the extracted value (if any).

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.

pszArgName

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

lItem

The zero-based index of the item that is being extracted from the argument. If the argument is presented as a vector, then this value determines which item is extracted.

pszItemName

The name of the item that is being extracted from the argument. If the argument is presented as two-column array of labeled values, then this value will be used to search the left-hand column. It will also 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".

bStrict

Flag controlling the conversion. If bStrict is false, then the function will attempt to convert the input cell to the type of result. If bStrict is true, then no conversion will be attempted.

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.

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 is used (particularly in generated code) to extract the various items from a compressed group argument.

The user may present the grouped argument in one of two forms:

A one-dimensional array (vector) of values, in which case the lItem parameter will be used to extract the value (by position).

A two-column array, where the left-hand column contains labels and the right-hand column contains values. In this case, the array will be searched by name, by matching the pszItemName parameter with an entry in the left-hand column.

If the argument cannot be found, then an error string will be set and FALSE will be returned.

If the argument is found, then the function will attempt to convert it to the required type. If this conversion fails, then the function will return FALSE and set the error string.

See Compressed Groups in the User Guide for more information about the permitted layouts of the input argument.

Status

This function should be used in preference to the deprecated function ReadVectorItem().

Requirements