CStr Class Reference

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

---

Search for all occurrences

---

Detailed Description

See also:

Class WStr, 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.

#include <strclass.h>

Inheritance diagram for CStr:

List of all members.

Public Member Functions
UtilExport	CStr ()
UtilExport	CStr (const char *cs)
UtilExport	CStr (const mwchar_t *wcstr)
UtilExport	CStr (const CStr &ws)
UtilExport	~CStr ()
UtilExport char *	data ()
UtilExport const char *	data () const
UtilExport	operator char * ()
UtilExport	operator const char * () const
UtilExport void	Resize (int nchars)
UtilExport int	Length () const
int	length () const
UtilExport int	ByteCount () const
UtilExport int	LanguageCharacterCount () const
BOOL	isNull () const
UtilExport CStr &	operator= (const CStr &cs)
UtilExport CStr &	operator= (const mwchar_t *wcstr)
UtilExport CStr &	operator= (const char *cs)
UtilExport CStr	operator+ (const CStr &cs) const
UtilExport CStr &	operator+= (const CStr &cs)
CStr &	Append (const CStr &cs)
CStr &	append (const CStr &cs)
UtilExport CStr &	remove (int pos)
UtilExport CStr &	remove (int pos, int N)
UtilExport CStr	Substr (int start, int nchars) const
UtilExport CStr	MultiByteCharacterSubString (int firstCharacterIndex, int numberOfMBCharacters) const
UtilExport int	FindMBCharacterFirstByteIndex (int characterIndex) const
UtilExport int	FindMBCharacterLastByteIndex (int characterIndex) const
UtilExport char &	operator[] (int i)
UtilExport char	operator[] (int i) const
UtilExport int	first (char c) const
UtilExport int	last (char c) const
UtilExport int	operator== (const CStr &cs) const
UtilExport int	operator!= (const CStr &cs) const
UtilExport int	operator< (const CStr &cs) const
UtilExport int	operator<= (const CStr &ws) const
UtilExport int	operator> (const CStr &ws) const
UtilExport int	operator>= (const CStr &ws) const
UtilExport void	toUpper ()
UtilExport void	toLower ()
UtilExport int	printf (const char *format,...)
	Write a formatted string into this CStr.
UtilExport int	vprintf (const char *format, va_list args)
	Write a formatted string into this CStr.

---

Constructor & Destructor Documentation

UtilExport CStr

(

)

Remarks:

Constructor. The string is set to NULL.

UtilExport CStr

(

const char *

cs

)

Remarks:

Constructor. The string is initialized to the string passed.

UtilExport CStr

(

const mwchar_t *

wcstr

)

Remarks:

Constructor. The string is initialized to the string passed.

UtilExport CStr

(

const CStr &

ws

)

Remarks:

Constructor. The string is initialized to the string passed.

UtilExport ~CStr

(

)

Remarks:

Destructor. The string is deleted.

---

Member Function Documentation

UtilExport char* data

(

)

Search for all occurrences

Remarks:

Returns a pointer to the string. If the string is NULL, 0 is returned.

UtilExport const char* data

(

)

const

Search for all occurrences

Remarks:

Returns a pointer to the string. If the string is NULL, 0 is returned.

UtilExport operator char *

(

)

Remarks:

Returns a pointer to the string. If the string is NULL, 0 is returned.

UtilExport operator const char *

(

)

const

Remarks:

Returns a const pointer to the string. If the string is NULL, 0 is returned.

UtilExport 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.

UtilExport int Length

(

)

const [inline]

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.

{ return ByteCount(); }

int length

(

)

const [inline]

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.

{ return Length(); }

UtilExport 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.

UtilExport int LanguageCharacterCount

(

)

const

Search for all occurrences

Remarks:

Returns the number of natural language characters represented by the string, 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.

BOOL isNull

(

)

const [inline]

Search for all occurrences

Remarks:

Returns TRUE if the string length is 0; otherwise FALSE.

{ return Length()==0?1:0; }

UtilExport CStr& operator=

(

const CStr &

cs

)

Remarks:

Assignment operator.

UtilExport CStr& operator=

(

const mwchar_t *

wcstr

)

Remarks:

Assignment operator.

UtilExport CStr& operator=

(

const char *

cs

)

Remarks:

Assignment operator. In release 3.0 and later this method check for self-assignment.

UtilExport CStr operator+

(

const CStr &

cs

)

const

Remarks:

Concatenation operator. Returns a new string that is this string with string cs appended.

UtilExport CStr& operator+=

(

const CStr &

cs

)

Remarks:

Concatenation. Returns this string with cs appended.

CStr& Append

(

const CStr &

cs

)

[inline]

Search for all occurrences

Remarks:

Concatenation. Returns this string with cs appended.

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

CStr& append

(

const CStr &

cs

)

[inline]

Search for all occurrences

Remarks:

Concatenation. Returns this string with cs appended to the end.

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

UtilExport CStr& remove

(

int

pos

)

Search for all occurrences

Remarks:

Returns this string with all characters from pos to the end removed.

Parameters:

int pos

Specifies the last position in the string.

UtilExport CStr& remove	(	int	pos,
		int	N
	)

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.

UtilExport CStr Substr	(	int	start,
		int	nchars
	)		const

Search for all occurrences

Remarks:

Returns a substring of this string, beginning at position start, of length nchars.

UtilExport CStr MultiByteCharacterSubString	(	int	firstCharacterIndex,
		int	numberOfMBCharacters
	)		const

Search for all occurrences

Remarks:

Returns a substring of this string, beginning at multi-byte character position firstCharacterIndex, of length numberOfMBCharacters.

UtilExport int FindMBCharacterFirstByteIndex

(

int

characterIndex

)

const

Search for all occurrences

Remarks:

Returns the first byte index value of the multi-byte character position characterIndex.

UtilExport int FindMBCharacterLastByteIndex

(

int

characterIndex

)

const

Search for all occurrences

Remarks:

Returns the last byte index value of the multi-byte character position characterIndex.

UtilExport char& operator[]

(

int

i

)

Remarks:

Returns a substring of this string beginning at position i.

UtilExport char operator[]

(

int

i

)

const

Remarks:

Returns a substring of this string beginning at position i.

UtilExport int first

(

char

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.

UtilExport int last

(

char

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.

UtilExport int operator==

(

const CStr &

cs

)

const

Remarks:

Equality operator.

Returns:

Nonzero if the strings are equal; otherwise 0.

UtilExport int operator!=

(

const CStr &

cs

)

const

Remarks:

Inequality operator.

Returns:

Zero if the strings are equal; otherwise 1.

UtilExport int operator<

(

const CStr &

cs

)

const

Remarks:

Returns nonzero if this string is less than cs; otherwise 0.

UtilExport int operator<=

(

const CStr &

ws

)

const

Remarks:

Returns nonzero if this string is less than or equal to ws; otherwise 0.

UtilExport int operator>

(

const CStr &

ws

)

const

Remarks:

Returns nonzero if this string is greater than ws; otherwise 0.

UtilExport int operator>=

(

const CStr &

ws

)

const

Remarks:

Returns nonzero if this string is greater than or equal to ws; otherwise 0.

UtilExport void toUpper

(

)

Search for all occurrences

Remarks:

Converts all character of this string to uppercase.

UtilExport void toLower

(

)

Search for all occurrences

Remarks:

Converts all character of this string to lowercase.

UtilExport int printf	(	const char *	format,
			...
	)

Search for all occurrences

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.

UtilExport int vprintf	(	const char *	format,
		va_list	args
	)

Search for all occurrences

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(CStr* format, ...) {
            va_list args;
            va_start(args, format);
            CStr buf;
            buf.printf(format, args);
            va_end(args);
            // log the message contained by buf
        }