Detailed Description

CDataArrayString is used for storing wide character strings in a 1D element array.

Since:: 9.0 (2011)

See also:: CDataArray2DString, CIndexSet

#include <xsi_dataarray.h>

Inherits CBaseDataArray.

Public Member Functions
SICPPSDK_INLINE	CDataArrayString ()
SICPPSDK_INLINE	CDataArrayString (ICENodeContext &in_ctxt, ULONG in_nInputPortID, ULONG in_nInstanceIndex=0)
SICPPSDK_INLINE	CDataArrayString (ICENodeContext &in_ctxt)
SICPPSDK_INLINE	~CDataArrayString ()
SICPPSDK_INLINE CStatus	CopyFrom (ULONG in_nInputPortID, ULONG in_nInstanceIndex=0)
SICPPSDK_INLINE CStatus	SetData (ULONG in_nIndex, const CString &in_str)
SICPPSDK_INLINE CStatus	GetData (ULONG in_nIndex, CString &out_str) const
SICPPSDK_INLINE CString	operator[] (ULONG in_nIndex) const
SICPPSDK_INLINE CStatus	SetData (ULONG in_nIndex, const TData *in_pData, ULONG in_nCount)
SICPPSDK_INLINE CStatus	GetData (ULONG in_nIndex, const TData **out_ppStr, ULONG &out_nCount) const
SICPPSDK_INLINE CStatus	GetData (ULONG in_nIndex, TData **out_ppStr, ULONG &out_nCount) const
SICPPSDK_INLINE TData *	Resize (ULONG in_nIndex, ULONG in_nCount)
SICPPSDK_INLINE ULONG	GetCount () const
SICPPSDK_INLINE bool	IsConstant () const

Constructor & Destructor Documentation

SICPPSDK_INLINE CDataArrayString ( )

Default Constructor.

SICPPSDK_INLINE CDataArrayString	(	ICENodeContext &	in_ctxt,
		ULONG	in_nInputPortID,
		ULONG	in_nInstanceIndex = `0`
	)

Constructor for string array types bound to input ports.

Parameters:

in_ctxt	ICENode evaluation context.
in_nInputPortID	Input port identifier.
in_nInstanceIndex	The group instance of the port.

SICPPSDK_INLINE CDataArrayString ( ICENodeContext & in_ctxt )

Constructor for string array types bound to output ports.

Parameters:

in_ctxt ICENode evaluation context.

SICPPSDK_INLINE ~CDataArrayString ( )

Destructor.

Member Function Documentation

SICPPSDK_INLINE CStatus CopyFrom	(	ULONG	in_nInputPortID,
		ULONG	in_nInstanceIndex = `0`
	)

Copy the data from a given input port to this object buffer without allocating memory. This is typically used for passing data by reference from input to output ports, similar to what the built-in 'pass through' node is doing.

Parameters:

in_nInputPortID	Input port identifier.
in_nInstanceIndex	The group instance of the port.

Returns:: CStatus::OK Success; CStatus::InvalidArgument Fails if in_nInputPortID is not an input port identifier or in_nInstanceIndex is invalid.; CStatus::AccessDenied This array is not an output type or wasn't created properly.

Example:

        // Copy data from the ID_IN_STRING port to the current output port
        XSI::CDataArrayString outData( in_ctxt );
        outData.CopyFrom( ID_IN_STRING );

SICPPSDK_INLINE CStatus SetData	(	ULONG	in_nIndex,
		const CString &	in_str
	)

Sets the array at a specific position with the content of in_str.

Parameters:

in_nIndex	Array index to store the string.
in_str	CString object.

Returns:: Success/failure

See also:: CDataArrayString::Resize

SICPPSDK_INLINE CStatus GetData	(	ULONG	in_nIndex,
		CString &	out_str
	)		const

Returns a CString object set with a copy of the string stored at a specific index.

Parameters:

in_nIndex Array index of the string to retrieve. The object is empty if no string is stored at this index.

Return values:

out_str CString object containing a copy of the string.

Returns:: Success/failure

SICPPSDK_INLINE CString operator[] ( ULONG in_nIndex ) const

Method returning a CString stored at in_nIndex. The CString object will contain a copy of the string.

Parameters:

in_nIndex Index in the array. The index must be smaller than the number of elements in the array, otherwise the object returned is empty.

Returns:: CString object.

SICPPSDK_INLINE CStatus SetData	(	ULONG	in_nIndex,
		const TData *	in_pData,
		ULONG	in_nCount
	)

Sets the array at a specific position with the content of in_pStr. This API will allocate emmory for in_nCount characters to store the user data.

Parameters:

in_nIndex	Array index to store the user data.
in_pStr	Pointer to string data.
in_nCount	Number of characters to store.

Returns:: Success/failure

See also:: CDataArrayString::Resize

SICPPSDK_INLINE CStatus GetData	(	ULONG	in_nIndex,
		const TData **	out_ppStr,
		ULONG &	out_nCount
	)		const

Returns a pointer to the string stored at in_nIndex. The data is read-only and cannot be modified.

Note:: The memory allocated for the data returned by CDataArrayString::GetData is only available within the scope of this CDataArrayString instance. Make sure to make a copy of the data if you need to access it outside the scope of CDataArrayString.

Note:: The string returned in out_ppStr is not null-terminated, the caller must make sure to take the number of characters in account when manipulating the string.

Parameters:

in_nIndex Array index of the user data to retrieve. The size is 0 if no data is stored at this index.

Return values:

out_ppStr	Read-only pointer to the string data.
out_nCount	Number of characters in the string.

Returns:: Success/failure

SICPPSDK_INLINE CStatus GetData	(	ULONG	in_nIndex,
		TData **	out_ppStr,
		ULONG &	out_nCount
	)		const

Returns a pointer to the string stored at in_nIndex. The data can be modified directly.

Note:: The memory allocated for the data returned by CDataArrayString::GetData is only available within the scope of this CDataArrayString instance. Make sure to make a copy of the data if you need to access it outside the scope of CDataArrayString.

Parameters:

in_nIndex Array index of the string to retrieve.

Return values:

out_ppStr	Pointer to the string.
out_nCount	Number of characters in the string.

Returns:: Success/failure

SICPPSDK_INLINE CDataArrayString::TData * Resize	(	ULONG	in_nIndex,
		ULONG	in_nCount
	)

Changes the size of the string buffer at a specific index to a specified size and returns a pointer to the allocated data.

Parameters:

in_nIndex	Array index of the string buffer to resize.
in_nCount	The number of characters of the new array.

Returns:: Pointer to the allocated data.

SICPPSDK_INLINE ULONG GetCount ( void ) const

Returns the number of characters in the array.

Returns:: Number of characters.

SICPPSDK_INLINE bool IsConstant ( ) const

Returns true if the array is constant or false otherwise. A constant array has only one value.

Returns:: True if constant, false otherwise.

The documentation for this class was generated from the following file:

xsi_dataarray.h

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation