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 ()
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