CString Class Reference

---

Detailed Description

Character strings in the Softimage SDK are represented with the CString class. CString consist of a variable-length sequence of characters. The CString class can store either wide characters (16-bit values) or ASCII ("char") characters (8-bit values).

Using wide characters allows unicode strings to be represented in the SDK. Therefore you must use the L character before a character or a string constant to designate the wide character type constant.

The string type of a CString object is generally immutable. Once you create a CString object as wide, the type remains as such until an assignment operation is performed with an ASCII string; likewise when creating an ASCII CString object. The CString class provides methods to perform wide and ASCII operations. Mixing wide and ASCII operations is possible but would trigger internal string conversions on the method arguments which could lead to performance issues.

See also:

CStringArray

Example:

Using the L character to designate the wide-character type constant

        using namespace XSI;
        CString myString(L"Mystring");

Example:

The default constructor creates a wide-character CString object.

        using namespace XSI;
        CString myWideString();

        myWideString = L"Wide String";

        // This will change the CString type from wide to ASCII.
        myWideString = "ASCII String";

Example:

Passing a common char string will create an ASCII-character CString object.

        using namespace XSI;
        CString myAsciiString( "MyString" );

        // This will change the CString type from ASCII to wide.
        myAsciiString = L"Wide String";

#include <xsi_string.h>

List of all members.

Public Member Functions
	CString ()
virtual	~CString ()
	CString (const CString &in_str)
	CString (const wchar_t *in_str)
	CString (const wchar_t *in_str, ULONG in_nCount)
	CString (const char *in_str)
	CString (const char *in_str, ULONG in_nCount)
	CString (const CValue &in_val)
const wchar_t *	GetWideString () const
const char *	GetAsciiString () const
CStatus	PutAsciiString (const char *in_pszStr)
ULONG	Length () const
bool	IsEmpty () const
void	Clear ()
CString &	operator= (const CString &in_rhs)
CString &	operator= (const wchar_t *in_rhs)
CString &	operator= (const char *in_rhs)
bool	operator== (const CString &in_refStr) const
bool	operator== (const wchar_t *in_pwstr) const
bool	operator== (const char *in_pstr) const
bool	IsEqualNoCase (const CString &in_rhs) const
bool	IsEqualNoCase (const wchar_t *in_pwstr) const
bool	IsEqualNoCase (const char *in_pstr) const
CStringArray	Split (const CString &in_strDel) const
bool	operator!= (const CString &in_refStr) const
bool	operator!= (const wchar_t *in_pwstr) const
bool	operator!= (const char *in_pstr) const
CString &	operator+= (const CString &in_refStr)
CString &	operator+= (const wchar_t *in_pwstr)
CString &	operator+= (const char *in_pstr)
CString &	operator+= (const wchar_t in_wchar)
CString &	operator+= (const char in_char)
CString	operator+ (const CString &in_refStr) const
CString	operator+ (const wchar_t *in_pwstr) const
CString	operator+ (const char *in_pstr) const
CString	operator+ (const wchar_t in_wchar) const
CString	operator+ (const char in_char) const
wchar_t	operator[] (ULONG in_index) const
char	GetAt (ULONG in_index) const
bool	operator< (const CString &in_str) const
bool	operator> (const CString &in_str) const
ULONG	FindString (const CString &in_str, ULONG in_nOffset=0) const
ULONG	ReverseFindString (const CString &in_str, ULONG in_nOffset=UINT_MAX) const
CString	GetSubString (ULONG in_nOffset=0, ULONG in_nCount=UINT_MAX) const
void	Lower ()
void	Upper ()
void	TrimLeft (const CString &in_target=CString())
void	TrimRight (const CString &in_target=CString())

---

Constructor & Destructor Documentation

CString

(

)

Default constructor. The newly created CString stores a sequence of wide characters.

virtual ~CString

(

)

[virtual]

Default destructor.

CString

(

const CString &

in_str

)

Constructs a CString object from another CString object. The contents of the string are duplicated.

Parameters:

in_str

constant CString reference object.

CString

(

const wchar_t *

in_str

)

Constructs a CString object from a null-terminated wide character string. The contents of the input string are duplicated inside the CString.

Parameters:

in_str

constant wchar_t* reference pointer.

CString	(	const wchar_t *	in_str,
		ULONG	in_nCount
	)

Constructs a CString object by copying the first in_nCount characters from a null-terminated wide character string.

Parameters:

in_str	constant wchar_t* reference pointer.
in_nCount	Number of characters to copy from the in_str argument starting from position 0.

Since:

9.0 (2011)

CString

(

const char *

in_str

)

Constructs a CString object from a null-terminated ASCII character string. The contents of the input string are duplicated inside the CString.

Parameters:

in_str

constant char* reference pointer.

Since:

7.5

CString	(	const char *	in_str,
		ULONG	in_nCount
	)

Constructs a CString object by copying the first in_nCount characters from a null-terminated ascii character string.

Parameters:

in_str	constant char* reference pointer.
in_nCount	Number of characters to copy from the in_str argument starting from position 0.

Since:

9.0 (2011)

CString

(

const CValue &

in_val

)

[explicit]

Constructs a CString object from a CValue object. This constructor allows you to initialize a CString object with the string representation of a CValue object.

Parameters:

in_val

constant reference to a CValue object.

See also:

CValue::GetAsText

Example:

        using namespace XSI;

        // Old way of converting a LONG to a CString object
        CString str = CValue((LONG)myLong).GetAsText();

        // New way
        CString str2 = CValue((LONG)10);

---

Member Function Documentation

const wchar_t* GetWideString

(

)

const

Accessor to a null-terminated, wide character representation of the string. This buffer cannot be modified.

Note:

String duplication could take place if the CString object is an ASCII string.

Returns:

The wide char representation for this string.

Example:

        using namespace XSI;
        CString q( L"Data" ) ;

        // Get read-only access to the internal string buffer
        const wchar_t* l_pBuffer = q.GetWideString() ;

        // We can now call normal C runtime library string functions
        if ( 0==wcscmp( l_pBuffer, L"Data" ) )
        {
            // As expected
        }

const char* GetAsciiString

(

)

const

Accessor to a null-terminated, ASCII character representation of the string. This buffer is temporary and cannot be modified. It should not be accessed after the content of the original CString object changes or is destroyed.

Note:

String duplication could take place if the CString object is a wide string.

Returns:

The ASCII char representation for this string.

Since:

5.0

Example:

        using namespace XSI;
        CString q( L"Data" ) ;

        // Get read-only access to the internal string buffer
        const char* l_pBuffer = q.GetAsciiString() ;

        // We can now call normal C runtime library string functions
        if ( 0==strcmp( l_pBuffer, "Data" ) )
        {
            // As expected
        }

CStatus PutAsciiString

(

const char *

in_pszStr

)

Sets the CString object with a null-terminated ASCII character string. The contents of the specified string is duplicated inside the CString.

Note:

This method is obsolete. Use CString( const char* ) to create an ASCII-character CString object or CString::operator = (const char* ) to assign an ASCII string.

Parameters:

in_pszStr

constant char* reference pointer. The string is set to an empty string if the input string is empty or NULL.

Returns:

CStatus::OK success

CStatus::False String set to empty.

See also:

CString::GetAsciiString

Since:

5.0

Example:

        using namespace XSI;
        CString q;

        q.PutAsciiString( "Data" ) ;

        // Get read-only access to the internal string buffer
        const char* l_pBuffer = q.GetAsciiString() ;

        // We can now call normal C runtime library string functions
        if ( 0==strcmp( l_pBuffer, "Data" ) )
        {
            // As expected
        }

ULONG Length

(

)

const

Returns the number of characters in the string. Does not include the null-termination character. This is not the number of bytes required to hold a wide-character string because each character is 2 bytes long.

Returns:

The number of characters in the string.

bool IsEmpty

(

)

const

Tests whether the string is empty.

Returns:

true if the string is empty; false otherwise.

void Clear

(

)

Clears the string's contents.

CString& operator=

(

const CString &

in_rhs

)

Assignment operator. The contents of the string are duplicated. This operation can change the type of this CString.

Parameters:

in_rhs

CString object that we want to assign.

Returns:

A reference to the newly created object.

CString& operator=

(

const wchar_t *

in_rhs

)

Assignment operator The contents of the string are duplicated. This operation can change the type of this CString.

Parameters:

in_rhs

wide character string that we want to assign.

Returns:

A reference to the newly created object.

CString& operator=

(

const char *

in_rhs

)

Assignment operator The contents of the string are duplicated. This operation can change the type of this CString.

Parameters:

in_rhs

ASCII character string that we want to assign.

Returns:

A reference to the newly created object.

Since:

7.5

bool operator==

(

const CString &

in_refStr

)

const

Equality operator. Tests whether one string has the same contents as another.

Note:

Comparison is case-sensitive.

Parameters:

in_refStr

CString with which we want to compare.

Returns:

true if all characters are the same; false if some or all of the characters are different.

bool operator==

(

const wchar_t *

in_pwstr

)

const

Equality operator. Tests whether the CString has the same contents as a wide character string.

Parameters:

in_pwstr

Pointer to a string with which we want to compare.

Returns:

true if all characters are the same; false if some or all characters are different.

bool operator==

(

const char *

in_pstr

)

const

Equality operator. Tests whether the CString has the same contents as an ASCII character string.

Parameters:

in_pstr

Pointer to a string with which we want to compare.

Returns:

true if all characters are the same; false if some or all characters are different.

Since:

7.5

bool IsEqualNoCase

(

const CString &

in_rhs

)

const

Case-insensitive comparison.

Parameters:

in_rhs

CString with which we want to compare.

Returns:

true if the strings are the same; false otherwise.

Example:

        using namespace XSI;
        CString A( L"A" ) ;
        CString a( L"a" ) ;

        A == a ;                    // False
        A.IsEqualNoCase( a ) ;      // True
        A.IsEqualNoCase( L" a" ) ;  // False

bool IsEqualNoCase

(

const wchar_t *

in_pwstr

)

const

Case insensitive comparison. Tests whether one string has the same contents as another without regard to the case.

Parameters:

in_pwstr

Wide character string we want to compare.

Returns:

true if the strings are the same; false otherwise.

bool IsEqualNoCase

(

const char *

in_pstr

)

const

Case insensitive comparison. Tests whether this CString object has the same contents as an ASCII character string without regard to the case.

Parameters:

in_pstr

ASCII character string we want to compare.

Returns:

true if the strings are the same; false otherwise.

Since:

7.5

CStringArray Split

(

const CString &

in_strDel

)

const

Parses the string and returns the sub-strings delimited by a given string. If the delimiter is empty the space character is used. If the string is empty, the function returns an empty array.

Parameters:

in_strDel

String delimiter.

Returns:

CStringArray Array constaining the sub-strings.

Since:

5.1

bool operator!=

(

const CString &

in_refStr

)

const

Inequality operator. Tests whether two CStrings have different contents.

Note:

Comparison is case-sensitive.

Parameters:

in_refStr

Pointer to a string with which we want to compare.

Returns:

true if some or all characters are different; false if all characters are the same.

bool operator!=

(

const wchar_t *

in_pwstr

)

const

Inequality operator. Tests whether a CString has different contents than a wide character string.

Note:

Comparison is case-sensitive.

Parameters:

in_pwstr

Pointer to a string with which we want to compare.

Returns:

true if some or all characters are different; false if all characters are the same.

bool operator!=

(

const char *

in_pstr

)

const

Inequality operator. Tests whether a CString has different contents than an ASCII character string.

Note:

Comparison is case-sensitive.

Parameters:

in_pstr

Pointer to a string with which we want to compare.

Returns:

true if some or all characters are different; false if all characters are the same.

Since:

7.5

CString& operator+=

(

const CString &

in_refStr

)

Concatenation operator.

Parameters:

in_refStr

Pointer to a string that we want to add to the end.

Returns:

A reference to this string after it has been modified.

Example:

        CString a( L"A" ) ;
        CString b( L"b" ) ;

        a += b ;
        // String now contains L"Ab"

CString& operator+=

(

const wchar_t *

in_pwstr

)

Concatenation operator.

Parameters:

in_pwstr

Wide character string that we want to append.

Returns:

A reference to this string after it has been modified.

CString& operator+=

(

const char *

in_pstr

)

Concatenation operator.

Parameters:

in_pstr

ASCII character string that we want to append.

Returns:

A reference to this string after it has been modified.

Since:

7.5

CString& operator+=

(

const wchar_t

in_wchar

)

Concatenation operator.

Parameters:

in_wchar

concatenate a single character at the end.

Returns:

A reference to this string after it has been modified.

CString& operator+=

(

const char

in_char

)

Concatenation operator.

Parameters:

in_char

concatenate a single ASCII character at the end.

Returns:

A reference to this string after it has been modified.

Since:

7.5

CString operator+

(

const CString &

in_refStr

)

const

Addition operator.

Parameters:

in_refStr

string to add together with this string

Returns:

A new string that contains the concatenation of this string and in_refStr.

CString operator+

(

const wchar_t *

in_pwstr

)

const

Addition operator.

Parameters:

in_pwstr

wide character string to add together with this string

Returns:

A new string that contains the concatenation of this string and in_pwstr.

CString operator+

(

const char *

in_pstr

)

const

Addition operator.

Parameters:

in_pstr

ASCII character string to add together with this string

Returns:

A new string that contains the concatenation of this string and in_pstr.

Since:

7.5

CString operator+

(

const wchar_t

in_wchar

)

const

Addition operator.

Parameters:

in_wchar

a single wide character to add together with this string

Returns:

A new string that contains the concatenation of this string and in_wchar.

CString operator+

(

const char

in_char

)

const

Addition operator.

Parameters:

in_char

a single ASCII character to add together with this string

Returns:

A new string that contains the concatenation of this string and in_char.

Since:

7.5

wchar_t operator[]

(

ULONG

in_index

)

const

Array element operator. Returns a single wide character contained in the string at a given position.

Note:

String conversion may occur if this object is an ASCII character string, which could lead to performance issues.

Parameters:

in_index

0-based position in the array.

Returns:

A wide character.

0xffff if the position is invalid.

See also:

CString::GetAt

char GetAt

(

ULONG

in_index

)

const

Returns a single ASCII character contained in the string at a given position.

Note:

String conversion may occur if this CString is a wide character string, which could lead to performance issues.

Parameters:

in_index

position in the 0-based array.

Returns:

ASCII character.

0xffff if the position is invalid.

See also:

CString::operator []

Since:

7.5

bool operator<

(

const CString &

in_str

)

const

Less-than operator. Performs a case-sensitive comparison with the contents of a specified CString to determine if this CString is lexicographically less than the specified CString. This is useful for sorting operations with stl maps.

Parameters:

in_str

CString we want to test.

Returns:

true if this CString is less than the specified CString, false otherwise.

Since:

7.5

bool operator>

(

const CString &

in_str

)

const

Greater-than operator. Performs a case-sensitive comparison with the contents of a specified CString to determine if this CString is lexicographically greater than the specified CString.

Parameters:

in_str

CString we want to test.

Returns:

true if this CString is greater than the specified CString, false otherwise.

Since:

7.5

ULONG FindString	(	const CString &	in_str,
		ULONG	in_nOffset = 0
	)		const

Searches this string instance in the forward direction for the first occurrence of the specified string.

Parameters:

in_str	The string to look for.
in_nOffset	Index of the position at which the search is to begin. The default position is 0.

Returns:

The position of the sub-string searched when successful. If no sub-string is found, the function returns UINT_MAX.

See also:

CString::ReverseFindString, CString::GetSubString

Since:

7.5

Example:

Demonstrates a number of options for forward string searching

        CString str( "0123456789" ) ;

        // Returns 0 for an exact match
        ULONG npos = str.FindString( str );

        // Returns 0 for an empty string
        npos = str.FindString( CString() );

        // Returns 1 if "12" is found
        npos = str.FindString( CString("12") );

        // Returns UINT_MAX if "777" is not found
        npos = str.FindString( CString("777") );

        // Returns UINT_MAX if "12" is not found
        npos = str.FindString( CString("12"), str.Length() );

        // Returns the specified search position (i.e. 10) for an empty string
        npos = str.FindString( CString(), 10 );

        // Returns UINT_MAX if the specified search position exceeds the string size
        npos = str.FindString( CString("12"), str.Length()+1 );

ULONG ReverseFindString	(	const CString &	in_str,
		ULONG	in_nOffset = UINT_MAX
	)		const

Searches this string instance in the backward direction for the first occurrence of the specified string.

Parameters:

in_str	The string to look for.
in_nOffset	Index of the position at which the search is to begin. The default position is UINT_MAX which is equivalent to the position of the last character in this string.

Returns:

The position of the sub-string searched when successful. If no sub-string is found, the function returns UINT_MAX.

See also:

CString::FindString, CString::GetSubString

Since:

7.5

Example:

Demonstrates a number of options for backward string searching

        CString str( "0123456789" ) ;

        // Returns 0 for an exact match
        ULONG npos = str.ReverseFindString( str );

        // Returns str length (i.e. 10) for an empty string
        npos = str.ReverseFindString( CString() );

        // Returns 1 if "12" is found
        npos = str.ReverseFindString( CString("12") );

        // Returns UINT_MAX if "777" is not found
        npos = str.ReverseFindString( CString("777") );

        // Returns UINT_MAX if "12" is not found
        npos = str.ReverseFindString( CString("12"), 0 );

        // Returns str length if the specified search position exceeds the string size
        npos = str.ReverseFindString( CString("12"), str.Length()+10 );

CString GetSubString	(	ULONG	in_nOffset = 0,
		ULONG	in_nCount = UINT_MAX
	)		const

Returns a sub-string from this instance beginning at a specified character position. If no arguments are passed, the function returns a copy of this CString.

Parameters:

in_nOffset	Index of the position at which the search is to begin. The default position is 0. This function returns an empty string if the index position exceeds this CString size.
in_nCount	The number of characters to copy. The default value is UINT_MAX, which is equivalent to the number of characters for this CString. This parameter is set to UINT_MAX if the value exceeds the number of characters for this CString.

Returns:

A CString object that is a copy of the elements of this instance beginning at the position specified by the first argument.

See also:

CString::FindString, CString::ReverseFindString

Since:

7.5

Example:

Demonstrates a number of options for extracting sub-strings from a CString instance

        CString str( "0123456789" ) ;

        // Returns "0123456789" by default
        CString substr = str.GetSubString( );

        // Returns "01234"
        substr = str.GetSubString( 0, 5 );

        // Returns empty string if the search position exeeds the str length
        substr = str.GetSubString( str.Length() + 10, 5 );

        // Returns "6789", str.length is used as 2nd argument if the requested number of characters exeeds str length.
        substr = str.GetSubString( 7, str.Length() + 10 );

void Lower

(

)

Convert this string to a lower-case character string.

See also:

CString::Upper

Since:

9.0 (2011)

void Upper

(

)

Convert this string to an upper-case character string.

See also:

CString::Lower

Since:

9.0 (2011)

void TrimLeft

(

const CString &

in_target = CString()

)

Removes a character or a group of characters from the beginning of this string. When called with no argument, the method removes newline, space and tab characters.

See also:

CString::TrimRight

Since:

11.0 (2013)

Example:

Demonstrates TrimLeft usage.

        Application app;
        CString str( "\n\n\t \t 0123456789   \n" ) ;

        // Trim blank characters
        str.TrimLeft( );
        app.LogMessage( str );
        // INFO: "0123456789   \n"

        // Trim "01234" characters
        str = "0123456789";
        str.TrimLeft( "42130" );
        app.LogMessage( str );
        // INFO: "56789"

        // Trim " *** \t" characters
        str = " *** \t0123456789";
        str.TrimLeft( " *\t" );
        app.LogMessage( str );
        // INFO: "0123456789"

void TrimRight

(

const CString &

in_target = CString()

)

Removes a character or a group of characters at the end of this string. When called with no argument, the method removes newline, space and tab characters.

See also:

CString::TrimLeft

Since:

11.0 (2013)

Example:

Demonstrates TrimRight usage.

        Application app;
        CString str( "\n\n\t \t 0123456789   \n" ) ;

        // Trim blank characters
        str.TrimRight( );
        app.LogMessage( str );
        // INFO: "\n\n\t \t 0123456789"

        // Trim "789" characters
        str = "0123456789";
        str.TrimRight( "978" );
        app.LogMessage( str );
        // INFO: "0123456"

        // Trim " *** \t" characters
        str = "0123456789 *** \t";
        str.TrimRight( " *\t" );
        app.LogMessage( str );
        // INFO: "0123456789"

---

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

• xsi_string.h