Classes | 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";

Definition at line 76 of file xsi_string.h.

#include <xsi_string.h>

List of all members.

Classes
struct   StringData
  Private class used for holding the CString data.

Public Member Functions
  CString ()
  Default constructor.
virtual  ~CString ()
  Default destructor.
  CString (const CString &in_str)
  Constructs a CString object from another CString object.
  CString (const wchar_t *in_str)
  Constructs a CString object from a null-terminated wide character string.
  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.
  CString (const char *in_str)
  Constructs a CString object from a null-terminated ASCII character string.
  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.
  CString (const CValue &in_val)
  Constructs a CString object from a CValue object.
const wchar_t *  GetWideString () const
  Accessor to a null-terminated, wide character representation of the string.
const char *  GetAsciiString () const
  Accessor to a null-terminated, ASCII character representation of the string.
CStatus  PutAsciiString (const char *in_pszStr)
  Sets the CString object with a null-terminated ASCII character string.
ULONG  Length () const
  Returns the number of characters in the string.
bool  IsEmpty () const
  Tests whether the string is empty.
void  Clear ()
  Clears the string's contents.
CString &  operator= (const CString &in_rhs)
  Assignment operator.
CString &  operator= (const wchar_t *in_rhs)
  Assignment operator The contents of the string are duplicated.
CString &  operator= (const char *in_rhs)
  Assignment operator The contents of the string are duplicated.
bool  operator== (const CString &in_refStr) const
  Equality operator.
bool  operator== (const wchar_t *in_pwstr) const
  Equality operator.
bool  operator== (const char *in_pstr) const
  Equality operator.
bool  IsEqualNoCase (const CString &in_rhs) const
  Case-insensitive comparison.
bool  IsEqualNoCase (const wchar_t *in_pwstr) const
  Case insensitive comparison.
bool  IsEqualNoCase (const char *in_pstr) const
  Case insensitive comparison.
CStringArray  Split (const CString &in_strDel) const
  Parses the string and returns the sub-strings delimited by a given string.
bool  operator!= (const CString &in_refStr) const
  Inequality operator.
bool  operator!= (const wchar_t *in_pwstr) const
  Inequality operator.
bool  operator!= (const char *in_pstr) const
  Inequality operator.
CString &  operator+= (const CString &in_refStr)
  Concatenation operator.
CString &  operator+= (const wchar_t *in_pwstr)
  Concatenation operator.
CString &  operator+= (const char *in_pstr)
  Concatenation operator.
CString &  operator+= (const wchar_t in_wchar)
  Concatenation operator.
CString &  operator+= (const char in_char)
  Concatenation operator.
CString  operator+ (const CString &in_refStr) const
  Addition operator.
CString  operator+ (const wchar_t *in_pwstr) const
  Addition operator.
CString  operator+ (const char *in_pstr) const
  Addition operator.
CString  operator+ (const wchar_t in_wchar) const
  Addition operator.
CString  operator+ (const char in_char) const
  Addition operator.
wchar_t  operator[] (ULONG in_index) const
  Array element operator.
char  GetAt (ULONG in_index) const
  Returns a single ASCII character contained in the string at a given position.
bool  operator< (const CString &in_str) const
  Less-than operator.
bool  operator> (const CString &in_str) const
  Greater-than operator.
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.
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.
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.
void  Lower ()
  Convert this string to a lower-case character string.
void  Upper ()
  Convert this string to an upper-case character string.

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)
The documentation for this class was generated from the following file:
Generated on Fri Mar 11 2011 01:43:20 by doxygen 1.7.3
Please send us your comment about this page

CString CString CString CString CString CString CString CString CString CString
CString CString CString CString CString CString CString CString CString CString