COper::ReadColumn

Reads a column from an array into a vector of numbers or strings

[C++]
template< class T >
BOOL ReadColumn(
   std::vector<T>& vecResult,
   const char* pszArgName,
   CString& strError = 0,
   long* plUBound = 0,
   long lColumn = XLA_UNIQUE_VECTOR,
   long lFlags = XLA_ARRAY_FLAGS_STD,
   long lLBound = 0,
   long lIgnoreItems = 0
) const;
template< class T >
BOOL ReadColumn(
   std::vector<T>& vecResult,
   const char* pszArgName,
   CXlOper& xloError,
   long* plUBound,
   long lRowOrCol = XLA_UNIQUE_VECTOR,
   long lFlags = XLA_ARRAY_FLAGS_STD,
   long lLBound = 0,
   long lIgnoreItems = 0
) const;

Parameters

vecResult

A vector containing items of type T, whose contents will be replaced by the contents of the COper.

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.

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".

plUBound

Pointer to upper bound. 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.

lColumn

Zero-based index of column to be extracted. If it is out of range, the function will fail.

If lColumn is set to XLA_UNIQUE_VECTOR, then the only column of a single-column array will be returned: if the array has more than one column, the function will report an error and return FALSE.

lFlags

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

lLBound

This will be used as a lower bound in the output vector. lLBound cells containing the default value will be inserted at the start of the output vector.

lIgnoreItems

The first lIgnoreItems 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.

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 single column 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 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.

Requirements

Header: xllplus.h

See Also

COper Class | COper Methods | Bounded input arrays | COper::ReadMatrix() | COper::ReadRow() | COper::ReadVector()