Public Member Functions
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 ()
CStringoperator= (const CString &in_rhs)
CStringoperator= (const wchar_t *in_rhs)
CStringoperator= (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
CStringoperator+= (const CString &in_refStr)
CStringoperator+= (const wchar_t *in_pwstr)
CStringoperator+= (const char *in_pstr)
CStringoperator+= (const wchar_t in_wchar)
CStringoperator+= (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_strconstant 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_strconstant 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_strconstant wchar_t* reference pointer.
in_nCountNumber 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_strconstant 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_strconstant char* reference pointer.
in_nCountNumber 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_valconstant 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_pszStrconstant 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_rhsCString 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_rhswide 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_rhsASCII 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_refStrCString 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_pwstrPointer 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_pstrPointer 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_rhsCString 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_pwstrWide 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_pstrASCII 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_strDelString 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_refStrPointer 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_pwstrPointer 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_pstrPointer 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_refStrPointer 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_pwstrWide 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_pstrASCII 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_wcharconcatenate 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_charconcatenate 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_refStrstring 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_pwstrwide 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_pstrASCII 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_wchara 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_chara 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_index0-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_indexposition 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_strCString 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_strCString 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_strThe string to look for.
in_nOffsetIndex 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_strThe string to look for.
in_nOffsetIndex 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_nOffsetIndex 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_nCountThe 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: