XSI::CString

CString Class Reference

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). More...

#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 char *in_str)
  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=ULONG_MAX) const
CString  GetSubString (ULONG in_nOffset=0, ULONG in_nCount=ULONG_MAX) const

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

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 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 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 ULONG_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 ULONG_MAX if "777" is not found
        npos = str.FindString( CString("777") );

        // Returns ULONG_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 ULONG_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 = ULONG_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 ULONG_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 ULONG_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 ULONG_MAX if "777" is not found
        npos = str.ReverseFindString( CString("777") );

        // Returns ULONG_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 = ULONG_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 ULONG_MAX, which is equivalent to the number of characters for this CString. This parameter is set to ULONG_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 );

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