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.

---

Search for all occurrences

#include <strclass.h>

Inheritance diagram for WStr:

---

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

)

Search for all occurrences

Remarks:

Returns a pointer to this string. But the returned string can be modified safely up to nchars.

const wchar_t* data

(

)

const

Search for all occurrences

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

)

Search for all occurrences

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

Search for all occurrences

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]

Search for all occurrences

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

Search for all occurrences

Remarks:

Returns the number of bytes used to store the string in memory, including spaces, but excluding the terminating NULL character.

int LanguageCharacterCount

(

)

const

Search for all occurrences

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

Search for all occurrences

Remarks:

Returns the total number of WCHAR allocated to store the string. Including the NULL character and any unused WCHAR.

bool isNull

(

)

const [inline]

Search for all occurrences

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]

Search for all occurrences

Remarks:

Concatenation. Returns this string with ws appended.

{ return ((*this) += ws); }

WStr& append

(

const WStr &

ws

)

[inline]

Search for all occurrences

Remarks:

Concatenation. Returns this string with ws appended.

{ return ((*this) += ws); }

WStr& remove

(

int

pos

)

Search for all occurrences

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
	)

Search for all occurrences

WStr Substr	(	int	start,
		int	nchars
	)		const

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

(

)

Search for all occurrences

Remarks:

Converts all character of this string to uppercase.

void toLower

(

)

Search for all occurrences

Remarks:

Converts all character of this string to lowercase.

int printf	(	const wchar_t *	format,
			...
	)

Search for all occurrences

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
	)

Search for all occurrences

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

Search for all occurrences

wchar_t* ToBSTR

(

)

const

Search for all occurrences

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]

Search for all occurrences

MaxSDK::Util::MaxStringCastCP ToCP	(	UINT	cp,
		size_t *	length = NULL
	)		const

Search for all occurrences

static WStr FromCP	(	UINT	cp,
		const char *	string,
		size_t	length = (size_t)-1
	)		[static]

Search for all occurrences

MaxSDK::Util::MaxStringCast<char> ToACP

(

size_t *

length = NULL

)

const

Search for all occurrences

static WStr FromACP	(	const char *	string,
		size_t	length = (size_t)-1
	)		[static]

Search for all occurrences

MaxSDK::Util::MaxStringCastUTF8 ToUTF8

(

size_t *

length = NULL

)

const

Search for all occurrences

static WStr FromUTF8	(	const char *	string,
		size_t	length = (size_t)-1
	)		[static]

Search for all occurrences

MaxSDK::Util::MaxStringCast<WCHAR> ToOLESTR

(

size_t *

length = NULL

)

const

Search for all occurrences

static WStr FromOLESTR	(	const wchar_t *	string,
		size_t	length = (size_t)-1
	)		[static]

Search for all occurrences

MaxSDK::Util::MaxStringCast<WCHAR> ToUTF16

(

size_t *

length = NULL

)

const

Search for all occurrences

static WStr FromUTF16	(	const wchar_t *	string,
		size_t	length = (size_t)-1
	)		[static]

Search for all occurrences

MaxSDK::Util::MaxStringCast<unsigned int> ToUTF32

(

size_t *

length = NULL

)

const

Search for all occurrences

static WStr FromUTF32	(	const unsigned int *	string,
		size_t	length = (size_t)-1
	)		[static]

Search for all occurrences

MaxSDK::Util::MaxString ToMaxString

(

)

const

Search for all occurrences

void ToMaxString

(

MaxSDK::Util::MaxString &

)

const

Search for all occurrences

static WStr FromMaxString

(

MaxSDK::Util::MaxString &

string

)

[inline, static]

Search for all occurrences

{ return WStr(string); }

CStr ToCStr

(

)

const

Search for all occurrences

static WStr FromCStr

(

const CStr &

string

)

[static]

Search for all occurrences

WStr ToWStr

(

)

const [inline]

Search for all occurrences

{ return *this; }

static WStr FromWStr

(

const WStr &

string

)

[inline, static]

Search for all occurrences

{ return WStr(string); }

MaxSDK::Util::MaxStringCast<char> ToMCHAR

(

size_t *

length = NULL

)

const [inline]

Search for all occurrences

{ return ToACP(length); }

static WStr FromMCHAR	(	const char *	string,
		size_t	length = (size_t)-1
	)		[inline, static]

Search for all occurrences

{ return FromACP(string, length); }

CStr ToMSTR

(

)

const

Search for all occurrences

static WStr FromMSTR

(

const CStr &

string

)

[static]

Search for all occurrences

bool EndsWith	(	const WStr &	s,
		bool	caseSensitive = true
	)

Search for all occurrences

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
	)

Search for all occurrences

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
	)

Search for all occurrences

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
	)

Search for all occurrences

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

Search for all occurrences

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
	)

Search for all occurrences

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.