CStr Class Reference
 
 
 
CStr Class Reference

This reference page is linked to from the following overview topics: Guidelines for Handling Character Strings, Unicode, wchar_t is Now Treated as a Type.


#include <strclass.h>

Inheritance diagram for CStr:
MaxHeapOperators

Class Description

See also:
Class WStr, UTF8Str and MaxString, Character Strings.

Description:
A simple character string class. This is the standard character string class used in 3ds Max. Methods and operators are provided for calculating lengths, concatenation, substring operations, character searching, case conversion, comparison, and formatted writing.

This class automatically allocates the proper amount of space for the string. This is very handy in the case of internationalization / localization. For example, if you code something like:

MSTR myString = GetString(IDS_STRING_ID);

then myString's constructor will allocate enough space to store the resource string no matter how long it is. This is much better than doing the following:

MCHAR myString[64];

_tcscpy(myString, GetString(IDS_STRING_ID));

because the resource string may turn out to be much longer than 64 bytes once it's translated to German or French (or whatever).

As another example, if you have the following code:

MSTR str1 = _M("This is string1.");

MSTR str2 = _M("This is string2.");

Then

MSTR concatStr = str1 + str2;

will again yield a (concatenated) string will enough space to hold the concatenated contents of str1 and str2, automatically.

All methods are implemented by the system.
Note:
The memory occupied by a CStr object is cannot be larger than 2Gb.
By design, this class assume that all the character data that you use to instanciate them or manipulate them are using the code page defined by the current active language of the 3dsMax. It should not be used to contains data in UTF-8 or in other code page than the current one.

Public Member Functions

  CStr ()
  CStr (const char *cs)
  CStr (const CStr &ws)
  CStr (const MaxSDK::Util::MaxString &ws)
  CStr (const MaxSDK::Util::MaxStringCast< char > &ws)
  ~CStr ()
char *  dataForWrite (size_t nchars=(size_t)-1)
const char *  data () const
  operator const char * () const
void  Resize (int nchars)
int  Length () const
int  length () const
int  ByteCount () const
int  LanguageCharacterCount () const
size_t  AllocatedChars () const
bool  isNull () const
CStr operator= (const CStr &cs)
CStr operator= (const MaxSDK::Util::MaxString &mstr)
CStr operator= (const MaxSDK::Util::MaxStringCast< char > &mstr)
CStr operator= (const char *cs)
CStr  operator+ (const CStr &cs) const
CStr operator+= (const CStr &cs)
CStr Append (const CStr &cs)
CStr append (const CStr &cs)
CStr remove (int pos)
CStr remove (int pos, int N)
CStr  Substr (int start, int nchars) const
CStr  MultiByteCharacterSubString (int firstCharacterIndex, int numberOfMBCharacters) const
int  FindMultiByteCharacterFirstByteIndex (int characterIndex) const
int  FindMultiByteCharacterLastByteIndex (int characterIndex) const
char  operator[] (int i) const
  Returns the nth character of this string.
int  first (char c) const
int  last (char c) const
bool  operator== (const CStr &cs) const
bool  operator== (char c) const
bool  operator!= (const CStr &cs) const
bool  operator!= (char c) const
bool  operator< (const CStr &cs) const
bool  operator<= (const CStr &ws) const
bool  operator> (const CStr &ws) const
bool  operator>= (const CStr &ws) const
void  toUpper ()
void  toLower ()
int  printf (const char *format,...)
  Write a formatted string into this CStr.
int  vprintf (const char *format, va_list args)
  Write a formatted string into this CStr.
wchar_t *  ToBSTR () const
MaxSDK::Util::MaxStringCastCP  ToCP (UINT cp, size_t *length=NULL) const
MaxSDK::Util::MaxStringCast< char >  ToACP (size_t *length=NULL) const
MaxSDK::Util::MaxStringCastUTF8  ToUTF8 (size_t *length=NULL) const
MaxSDK::Util::MaxStringCast
< WCHAR
ToOLESTR (size_t *length=NULL) const
MaxSDK::Util::MaxStringCast
< WCHAR
ToUTF16 (size_t *length=NULL) const
MaxSDK::Util::MaxStringCast
< unsigned int > 
ToUTF32 (size_t *length=NULL) const
MaxSDK::Util::MaxString  ToMaxString () const
void  ToMaxString (MaxSDK::Util::MaxString &) const
CStr  ToCStr () const
WStr  ToWStr () const
MaxSDK::Util::MaxStringCast< char >  ToMCHAR (size_t *length=NULL) const
CStr  ToMSTR () const
bool  EndsWith (const CStr &s, bool caseSensitive=true)
  Returns true if the string ends with s; otherwise returns false.
bool  EndsWith (char c, bool caseSensitive=true)
  Returns true if the string ends with c; otherwise returns false.
bool  StartsWith (const CStr &s, bool caseSensitive=true)
  Returns true if the string starts with s; otherwise returns false.
bool  StartsWith (char c, bool caseSensitive=true)
  Returns true if the string starts with c; otherwise returns false.
size_t  NumberOfLines () const
  Returns the number of lines inside a string.
size_t  Replace (const char *pFind, const char *pReplaceBy, bool firstOnly=false, size_t startPosition=0)
  Replaces one substring with another in this string.

Static Public Member Functions

static CStr  FromBSTR (const wchar_t *string, size_t length=(size_t)-1)
static CStr  FromCP (UINT cp, const char *string, size_t length=(size_t)-1)
static CStr  FromACP (const char *string, size_t length=(size_t)-1)
static CStr  FromUTF8 (const char *string, size_t length=(size_t)-1)
static CStr  FromOLESTR (const wchar_t *string, size_t length=(size_t)-1)
static CStr  FromUTF16 (const wchar_t *string, size_t length=(size_t)-1)
static CStr  FromUTF32 (const unsigned int *string, size_t length=(size_t)-1)
static CStr  FromMaxString (MaxSDK::Util::MaxString &string)
static CStr  FromCStr (const CStr &string)
static CStr  FromWStr (const WStr &string)
static CStr  FromMCHAR (const char *string, size_t length=(size_t)-1)
static CStr  FromMSTR (const CStr &string)

Constructor & Destructor Documentation

CStr ( )
Remarks:
Constructor. The string is set to NULL.
CStr ( const char *  cs )
Remarks:
Constructor. The string is initialized to the string passed.
CStr ( const CStr ws )
Remarks:
Constructor. The string is initialized to the string passed.
CStr ( const MaxSDK::Util::MaxString ws )
Remarks:
Constructor. The string is initialized to the string passed.
CStr ( const MaxSDK::Util::MaxStringCast< char > &  ws )
Remarks:
Constructor. The string is initialized to the string passed.
~CStr ( )
Remarks:
Destructor. The string is deleted.

Member Function Documentation

char* dataForWrite ( size_t  nchars = (size_t)-1 )
Remarks:
Returns a pointer to this string. But the returned string can be modified safely up to nchars.
const char* data ( ) const
Remarks:
Returns a const pointer to the string. If the string is NULL, a pointer to 0 is returned.
operator const char * ( ) const
Remarks:
Returns a const pointer to the string. If the string is NULL, a pointer to 0 is returned.
void Resize ( int  nchars )
Remarks:
Reallocates the string to contain nchars characters. If the string is enlarged it is padded with blanks.
Parameters:
int nchars

Specifies the new number of characters for the string.
int Length ( ) const [inline]
Remarks:
Returns the number of chars used to store the string in memory, including spaces, but excluding the terminating NULL character.
{ return ByteCount(); }
int length ( ) const [inline]
Remarks:
Returns the number of chars used to store the string in memory, including spaces, but excluding the terminating NULL character.
{ return Length(); }
int ByteCount ( ) const
Remarks:
Returns the number of bytes used to store the string in memory, including spaces, but excluding the terminating NULL character.
int LanguageCharacterCount ( ) const
Remarks:
Returns the number of natural language characters the string is represented on, including spaces, but excluding the terminal NULL character. For multi-byte languages, this may be equal or less than the amount of bytes used to store the string in memory. For example, a chinese character might take two bytes. Length() or ByteCount() will count the character as two distinct char. LanguageCharacterCount() will count it as a single char.
size_t AllocatedChars ( ) const
Remarks:
Returns the total number of char allocated to store the string. Including the NULL character and any unused char.
bool isNull ( ) const [inline]
Remarks:
Returns TRUE if the string length is 0; otherwise FALSE.
{ return data()[0]==0; }
CStr& operator= ( const CStr cs )
Remarks:
Assignment operator.
CStr& operator= ( const MaxSDK::Util::MaxString mstr )
Remarks:
Assignment operator.
CStr& operator= ( const MaxSDK::Util::MaxStringCast< char > &  mstr )
Remarks:
Assignment operator.
CStr& operator= ( const char *  cs )
Deprecated:
Deprecated in 3ds Max 2013, use CStr::FromUTF16() or CStr::FromBSTR() instead if have wchar_t* pointer, use WStr::ToACP() if have WStr value.

Assignment operator.

Remarks:
Assignment operator. In release 3.0 and later this method check for self-assignment.
CStr operator+ ( const CStr cs ) const
Remarks:
Concatenation operator. Returns a new string that is this string with string cs appended.
CStr& operator+= ( const CStr cs )
Remarks:
Concatenation. Returns this string with cs appended.
CStr& Append ( const CStr cs ) [inline]
Remarks:
Concatenation. Returns this string with cs appended.
{ return ((*this) += cs); }
CStr& append ( const CStr cs ) [inline]
Remarks:
Concatenation. Returns this string with cs appended to the end.
{ return ((*this) += cs); }
CStr& remove ( int  pos )
Remarks:
Returns this string with all characters from pos to the end removed.
Parameters:
int pos

Specifies the last position in the string.
CStr& remove ( int  pos,
int  N 
)
Remarks:
Returns this string with N characters removed from pos to the end.
Parameters:
int pos

Specifies the position to begin removing characters.

int N

Specifies the number of characters to remove.
CStr Substr ( int  start,
int  nchars 
) const
Remarks:
Returns a substring of this string, beginning at position start, of length nchars.
CStr MultiByteCharacterSubString ( int  firstCharacterIndex,
int  numberOfMBCharacters 
) const
Remarks:
Returns a substring of this string, beginning at multi-byte character position firstCharacterIndex, of length numberOfMBCharacters.
int FindMultiByteCharacterFirstByteIndex ( int  characterIndex ) const
Remarks:
Returns the first byte index value of the multi-byte character position characterIndex.
int FindMultiByteCharacterLastByteIndex ( int  characterIndex ) const
Remarks:
Returns the last byte index value of the multi-byte character position characterIndex.
char operator[] ( int  i ) const

Returns the nth character of this string.

Warning: In some environment, this function may return a partial character, especially for asiatic languages. If you intend to do any advance transformation or interpretation of the returned data, you should consider calling CStr::MultiByteCharacterSubString instead.

Parameters:
i Index of that character.
int first ( char  c ) const
Remarks:
Returns the index of the first occurrence of character c in this string. Returns -1 if not found.
int last ( char  c ) const
Remarks:
Returns the index of the last occurrence of character c in this string. Returns -1 if not found.
bool operator== ( const CStr cs ) const
Remarks:
Equality operator.
Returns:
true if the strings are equal; otherwise false.
bool operator== ( char  c ) const
Remarks:
Returns true if this string contain only the character c.
bool operator!= ( const CStr cs ) const
Remarks:
Inequality operator.
Returns:
false if the strings are equal; otherwise true.
bool operator!= ( char  c ) const
Remarks:
Returns true if this string does not contain only the character c.
bool operator< ( const CStr cs ) const
Remarks:
Returns true if this string is less than cs; otherwise false.
bool operator<= ( const CStr ws ) const
Remarks:
Returns true if this string is less than or equal to ws; otherwise false.
bool operator> ( const CStr ws ) const
Remarks:
Returns true if this string is greater than ws; otherwise false.
bool operator>= ( const CStr ws ) const
Remarks:
Returns true if this string is greater than or equal to ws; otherwise false.
void toUpper ( )
Remarks:
Converts all character of this string to uppercase.
void toLower ( )
Remarks:
Converts all character of this string to lowercase.
int printf ( const char *  format,
  ... 
)

Write a formatted string into this CStr.

Writes the format string, filled in by the optional arguments into this CStr. See the ISO C++ documentation for more information on printf and format strings.

Parameters:
format Specifies how to format the destination string.
... optional arguments to format into the destination string.
Precondition:
format is not null.
There are the correct number of elliptical arguments to fill the format string.
Postcondition:
This string is replaced with the formatted string.
Returns:
The number of characters written to this string, not including the null terminating character, or a negative value if an error occurs.
int vprintf ( const char *  format,
va_list  args 
)

Write a formatted string into this CStr.

This method is similar to CStr::printf. Instead of taking a variable list of arguments as parameter, it takes a structure representing a variable list of argument. This allows CStr objects to be used to build strings based on a format string and a variable number of arguments:

                void LogMessage(const char* format, ...) {
                        va_list args;
                        va_start(args, format);
                        CStr buf;
                        buf.printf(format, args);
                        va_end(args);
                        // log the message contained by buf
                }
wchar_t* ToBSTR ( ) const
Remarks:
Returns the string in memory allocated by SysAllocString. Caller is responsible for freeing memory using SysFreeString.
static CStr FromBSTR ( const wchar_t *  string,
size_t  length = (size_t)-1 
) [static]
MaxSDK::Util::MaxStringCastCP ToCP ( UINT  cp,
size_t *  length = NULL 
) const
static CStr FromCP ( UINT  cp,
const char *  string,
size_t  length = (size_t)-1 
) [static]
MaxSDK::Util::MaxStringCast<char> ToACP ( size_t *  length = NULL ) const
static CStr FromACP ( const char *  string,
size_t  length = (size_t)-1 
) [static]
MaxSDK::Util::MaxStringCastUTF8 ToUTF8 ( size_t *  length = NULL ) const
static CStr FromUTF8 ( const char *  string,
size_t  length = (size_t)-1 
) [static]
MaxSDK::Util::MaxStringCast<WCHAR> ToOLESTR ( size_t *  length = NULL ) const
static CStr FromOLESTR ( const wchar_t *  string,
size_t  length = (size_t)-1 
) [static]
MaxSDK::Util::MaxStringCast<WCHAR> ToUTF16 ( size_t *  length = NULL ) const
static CStr FromUTF16 ( const wchar_t *  string,
size_t  length = (size_t)-1 
) [static]
MaxSDK::Util::MaxStringCast<unsigned int> ToUTF32 ( size_t *  length = NULL ) const
static CStr FromUTF32 ( const unsigned int *  string,
size_t  length = (size_t)-1 
) [static]
void ToMaxString ( MaxSDK::Util::MaxString ) const
static CStr FromMaxString ( MaxSDK::Util::MaxString string ) [inline, static]
{ return CStr(string); }
CStr ToCStr ( ) const [inline]
{ return *this; }
static CStr FromCStr ( const CStr string ) [inline, static]
{ return CStr(string); }
WStr ToWStr ( ) const
static CStr FromWStr ( const WStr string ) [static]
MaxSDK::Util::MaxStringCast<char> ToMCHAR ( size_t *  length = NULL ) const [inline]
static CStr FromMCHAR ( const char *  string,
size_t  length = (size_t)-1 
) [inline, static]
CStr ToMSTR ( ) const [inline]
{ return *this; }
static CStr FromMSTR ( const CStr string ) [inline, static]
{ return CStr(string); }
bool EndsWith ( const CStr s,
bool  caseSensitive = true 
)

Returns true if the string ends with s; otherwise returns false.

Parameters:
s The string to be searched.
caseSensitive If it is true(default), the search is case sensitive; otherwise the search is case insensitive.
bool EndsWith ( char  c,
bool  caseSensitive = true 
)

Returns true if the string ends with c; otherwise returns false.

This function overloads EndsWith().

Parameters:
c The character to be searched.
caseSensitive If it is true(default), the search is case sensitive; otherwise the search is case insensitive.
bool StartsWith ( const CStr s,
bool  caseSensitive = true 
)

Returns true if the string starts with s; otherwise returns false.

Parameters:
s The string to be searched.
caseSensitive If it is true(default), the search is case sensitive; otherwise the search is case insensitive.
bool StartsWith ( char  c,
bool  caseSensitive = true 
)

Returns true if the string starts with c; otherwise returns false.

Parameters:
c The character to be searched.
caseSensitive If it is true(default), the search is case sensitive; otherwise the search is case insensitive.
size_t NumberOfLines ( ) const

Returns the number of lines inside a string.

size_t Replace ( const char *  pFind,
const char *  pReplaceBy,
bool  firstOnly = false,
size_t  startPosition = 0 
)

Replaces one substring with another in this string.

Parameters:
pFind The substring to be replaced.
pReplaceBy The string the substring is to be replaced with.
firstOnly If true, only first occurrence of 'from' is replaced, otherwise all occurrences are replaced
startPosition The character position to start searching from
Returns:
Returns the number of replacements made.