WStr Class Reference
 
 
 
WStr Class Reference

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


#include <strclass.h>

Inheritance diagram for WStr:
MaxHeapOperators

Class Description

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

Description:
A wide character string class. This class uses 16 bits to hold each character. Methods and operators are provided for calculating lengths, concatenation, substring operations, character searching, case conversion, comparison, and formatted writing. All methods are implemented by the system.

OLE file IO requires the wide characters of WStr.
Note:
The memory occupied by a WStr object is cannot be larger than 2Gb.

Public Member Functions

  WStr ()
  WStr (const wchar_t *wcstr)
  WStr (const WStr &ws)
  WStr (const MaxSDK::Util::MaxString &ws)
  WStr (const MaxSDK::Util::MaxStringCast< WCHAR > &ws)
  ~WStr ()
wchar_t *  dataForWrite (size_t nchars=(size_t)-1)
const wchar_t *  data () const
  operator const wchar_t * () const
void  Resize (int nchars)
int  Length () const
int  length () const
int  ByteCount () const
int  LanguageCharacterCount () const
size_t  AllocatedChars () const
bool  isNull () const
WStr operator= (const WStr &ws)
WStr operator= (const MaxSDK::Util::MaxString &mstr)
WStr operator= (const wchar_t *wcstr)
WStr operator= (const MaxSDK::Util::MaxStringCast< WCHAR > &mstr)
WStr  operator+ (const WStr &ws) const
WStr operator+= (const WStr &ws)
WStr Append (const WStr &ws)
WStr append (const WStr &ws)
WStr remove (int pos)
WStr remove (int pos, int N)
WStr  Substr (int start, int nchars) const
wchar_t  operator[] (int i) const
  Returns the nth character of this string.
int  first (wchar_t c) const
int  last (wchar_t c) const
bool  operator== (const WStr &ws) const
bool  operator== (wchar_t c) const
bool  operator!= (const WStr &ws) const
bool  operator!= (wchar_t c) const
bool  operator< (const WStr &ws) const
bool  operator<= (const WStr &ws) const
bool  operator> (const WStr &ws) const
bool  operator>= (const WStr &ws) const
void  toUpper ()
void  toLower ()
int  printf (const wchar_t *format,...)
  Write a formatted string into this WStr.
int  vprintf (const wchar_t *format, va_list args)
  Write a formatted string into this WStr.
WStr  MultiByteCharacterSubString (int firstCharacterIndex, int numberOfMBCharacters) const
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 WStr &s, bool caseSensitive=true)
  Returns true if the string ends with s; otherwise returns false.
bool  EndsWith (wchar_t c, bool caseSensitive=true)
  Returns true if the string ends with c; otherwise returns false.
bool  StartsWith (const WStr &s, bool caseSensitive=true)
  Returns true if the string starts with s; otherwise returns false.
bool  StartsWith (wchar_t 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 wchar_t *pFind, const wchar_t *pReplaceBy, bool firstOnly=false, size_t startPosition=0)
  Replaces one substring with another in this string.

Static Public Member Functions

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

Constructor & Destructor Documentation

WStr ( )
Remarks:
Constructor. The string is set to NULL.
WStr ( const wchar_t *  wcstr )
Deprecated:
Deprecated in 3ds Max 2013, use WStr::FromACP(), WStr::FromUTF8(), WStr::FromCP(), or WStr::FromMCHAR() instead if have char* pointer, use CStr::ToWStr() if have CStr value.

Constructor. The string is initialized to the string passed.

Remarks:
Constructor. The string is initialized to the string passed.
WStr ( const WStr ws )
Remarks:
Constructor. The string is initialized to the string passed.
WStr ( const MaxSDK::Util::MaxString ws )
Remarks:
Constructor. The string is initialized to the string passed.
WStr ( const MaxSDK::Util::MaxStringCast< WCHAR > &  ws )
Remarks:
Constructor. The string is initialized to the string passed.
~WStr ( )
Remarks:
Destructor. The string is deleted.

Member Function Documentation

wchar_t* 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 wchar_t* data ( ) const
Remarks:
Returns a const pointer to the string. If the string is NULL, a pointer to 0 is returned.
operator const wchar_t * ( ) 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
Remarks:
Returns the number of WCHAR that are used to represents this string, including spaces, but excluding the terminal NULL character.
int length ( ) const [inline]
Remarks:
Returns the number of WCHAR that are used to represents this string, including spaces, but excluding the terminal 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.

This may be equal or less than the amount of WCHAR used to store the string in memory. For example, a chinese character might take two WCHARs. Length() will count the character as two distinct WCHARs. LanguageCharacterCount() will count it as a single character.

size_t AllocatedChars ( ) const
Remarks:
Returns the total number of WCHAR allocated to store the string. Including the NULL character and any unused WCHAR.
bool isNull ( ) const [inline]
Remarks:
Returns TRUE if the string length is 0; otherwise FALSE.
{ return data()[0]==0; }
WStr& operator= ( const WStr ws )
Remarks:
Assignment operator. In release 3.0 and later this operator checks for self-assignment.
WStr& operator= ( const MaxSDK::Util::MaxString mstr )
Remarks:
Assignment operator.
WStr& operator= ( const wchar_t *  wcstr )
Remarks:
Assignment operator.
WStr& operator= ( const MaxSDK::Util::MaxStringCast< WCHAR > &  mstr )
Remarks:
Assignment operator.
WStr operator+ ( const WStr ws ) const
Deprecated:
Deprecated in 3ds Max 2013, use WStr::FromACP(), WStr::FromUTF8(), WStr::FromCP(), or WStr::FromMCHAR() instead if have char* pointer, use WStr::ToMCHAR() if have WStr value.

Assignment operator.

Remarks:
Concatenation operator. Returns a new string that is this string with string ws appended.
WStr& operator+= ( const WStr ws )
Remarks:
Concatenation. Returns this string with ws appended.
WStr& Append ( const WStr ws ) [inline]
Remarks:
Concatenation. Returns this string with ws appended.
{ return ((*this) += ws); }
WStr& append ( const WStr ws ) [inline]
Remarks:
Concatenation. Returns this string with ws appended.
{ return ((*this) += ws); }
WStr& remove ( int  pos )
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.
WStr& remove ( int  pos,
int  N 
)
WStr Substr ( int  start,
int  nchars 
) const
Remarks:
Returns a substring of this string, beginning at position start, of length nchars.
wchar_t 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 WStr::MultiByteCharacterSubString instead.

Parameters:
i Index of that character.
int first ( wchar_t  c ) const
Remarks:
Returns the index of the first occurrence of character c in this string. Returns -1 if not found.
int last ( wchar_t  c ) const
Remarks:
Returns the index of the last occurrence of character c in this string. Returns -1 if not found.
bool operator== ( const WStr ws ) const
Remarks:
Equality operator.
Returns:
true if the strings are equal; otherwise false.
bool operator== ( wchar_t  c ) const
Remarks:
Returns true if this string contain only the character c.
bool operator!= ( const WStr ws ) const
Remarks:
Inequality operator.
Returns:
False if the strings are equal; otherwise true.
bool operator!= ( wchar_t  c ) const
Remarks:
Returns true if this string does not contain only the character c.
bool operator< ( const WStr ws ) const
Remarks:
Returns true if this string is less than ws; otherwise false.
bool operator<= ( const WStr ws ) const
Remarks:
Returns true if this string is less than or equal to ws; otherwise false.
bool operator> ( const WStr ws ) const
Remarks:
Returns true if this string is greater than ws; otherwise false.
bool operator>= ( const WStr 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 wchar_t *  format,
  ... 
)

Write a formatted string into this WStr.

Writes the format string, filled in by the optional arguments into this WStr. 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 wchar_t *  format,
va_list  args 
)

Write a formatted string into this WStr.

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

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

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

This function overloads StartsWith().

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 wchar_t *  pFind,
const wchar_t *  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.