COper::ReadVectorItem

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

[C++]
BOOL ReadVectorItem(
   double& dResult,
   const char* pszArgName,
   long lItem,
   const char* pszItemName,
   CString& strError = 0,
   long lFlags = XLA_ITEM_FLAGS_STD
) const;
BOOL ReadVectorItem(
   double& dResult,
   const char* pszArgName,
   long lItem,
   const char* pszItemName,
   CXlOper& xloError,
   long lFlags = XLA_ITEM_FLAGS_STD
) const;
BOOL ReadVectorItem(
   CString& strResult,
   const char* pszArgName,
   long lItem,
   const char* pszItemName,
   CString& strError,
   long lFlags = XLA_ITEM_FLAGS_STD
) const;
BOOL ReadVectorItem(
   CString& strResult,
   const char* pszArgName,
   long lItem,
   const char* pszItemName,
   CXlOper& xloError,
   long lFlags = XLA_ARRAY_FLAGS_STD
) const;
BOOL ReadVectorItem(
   long& lResult,
   const char* pszArgName,
   long lItem,
   const char* pszItemName,
   CString& strError,
   long lFlags = XLA_ITEM_FLAGS_STD
) const;
BOOL ReadVectorItem(
   long& lResult,
   const char* pszArgName,
   long lItem,
   const char* pszItemName,
   CXlOper& xloError,
   long lFlags = XLA_ITEM_FLAGS_STD
) const;
BOOL ReadVectorItem(
   bool& bResult,
   const char* pszArgName,
   long lItem,
   const char* pszItemName,
   CString& strError,
   long lFlags = XLA_ITEM_FLAGS_STD
) const;
BOOL ReadVectorItem(
   bool& bResult,
   const char* pszArgName,
   long lItem,
   const char* pszItemName,
   CXlOper& xloError,
   long lFlags = XLA_ITEM_FLAGS_STD
) const;

Parameters

dResult: A buffer for the extracted value (if any).
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".
lFlags: Flags controlling the conversion. See matrix & vector flags for a full list of flag values.
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.
strResult: A CString, into which the result (if any) will be placed.
lResult: A long integer, whose contents will be replaced by the extracted value (if any).
bResult: A boolean value, whose contents will be replaced by the extracted value (if any).

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 is deprecated, and is supported for compatibility purposes. The simpler function ReadGroupItem() is preferred.

Requirements