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

#include <strclass.h>

Inheritance diagram for WStr:

List of all members.

Public Member Functions
UtilExport	WStr ()
UtilExport	WStr (const char *cs)
UtilExport	WStr (const mwchar_t *wcstr)
UtilExport	WStr (const WStr &ws)
UtilExport	~WStr ()
UtilExport mwchar_t *	data ()
UtilExport const mwchar_t *	data () const
UtilExport	operator mwchar_t * ()
UtilExport	operator const mwchar_t * () 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 WStr &	operator= (const WStr &ws)
UtilExport WStr &	operator= (const mwchar_t *wcstr)
UtilExport WStr &	operator= (const char *cstr)
UtilExport WStr	operator+ (const WStr &ws) const
UtilExport WStr &	operator+= (const WStr &ws)
WStr &	Append (const WStr &ws)
WStr &	append (const WStr &ws)
UtilExport WStr &	remove (int pos)
UtilExport WStr &	remove (int pos, int N)
UtilExport WStr	Substr (int start, int nchars) const
mwchar_t &	operator[] (int i)
mwchar_t	operator[] (int i) const
UtilExport int	first (mwchar_t c) const
UtilExport int	last (mwchar_t c) const
UtilExport int	operator== (const WStr &ws) const
UtilExport int	operator!= (const WStr &ws) const
UtilExport int	operator< (const WStr &ws) const
UtilExport int	operator<= (const WStr &ws) const
UtilExport int	operator> (const WStr &ws) const
UtilExport int	operator>= (const WStr &ws) const
UtilExport void	toUpper ()
UtilExport void	toLower ()
UtilExport int	printf (const mwchar_t *format,...)
	Write a formatted string into this WStr.
UtilExport int	vprintf (const mwchar_t *format, va_list args)
	Write a formatted string into this WStr.

---

Constructor & Destructor Documentation

UtilExport WStr

(

)

Remarks:

Constructor. The string is set to NULL.

UtilExport WStr

(

const char *

cs

)

Remarks:

Constructor. The string is initialized to the string passed.

UtilExport WStr

(

const mwchar_t *

wcstr

)

Remarks:

Constructor. The string is initialized to the string passed.

UtilExport WStr

(

const WStr &

ws

)

Remarks:

Constructor. The string is initialized to the string passed.

UtilExport ~WStr

(

)

Remarks:

Destructor. The string is deleted.

---

Member Function Documentation

UtilExport mwchar_t* data

(

)

Search for all occurrences

Remarks:

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

UtilExport const mwchar_t* data

(

)

const

Search for all occurrences

Remarks:

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

UtilExport operator mwchar_t *

(

)

Remarks:

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

UtilExport operator const mwchar_t *

(

)

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

Search for all occurrences

Remarks:

Returns the number of natural language characters represented by the string, including spaces, but excluding the terminal NULL character.

int length

(

)

const [inline]

Search for all occurrences

Remarks:

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

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 WStr& operator=

(

const WStr &

ws

)

Remarks:

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

UtilExport WStr& operator=

(

const mwchar_t *

wcstr

)

Remarks:

Assignment operator.

UtilExport WStr& operator=

(

const char *

cstr

)

Remarks:

Assignment operator.

UtilExport WStr operator+

(

const WStr &

ws

)

const

Remarks:

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

UtilExport 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); }

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

UtilExport WStr& remove	(	int	pos,
		int	N
	)

Search for all occurrences

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

mwchar_t& operator[]

(

int

i

)

[inline]

Remarks:

Returns a substring of this string beginning at position i.

                                    {
            DbgAssert((buf != NULL) && (i >= 0) && (i <= Length())); 
            return buf[i];
        }

mwchar_t operator[]

(

int

i

)

const [inline]

Remarks:

Returns a substring of this string beginning at position i.

                                         {
            DbgAssert((buf != NULL) && (i >= 0) && (i <= Length())); 
            return buf[i];
        }

UtilExport int first

(

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

UtilExport int last

(

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

UtilExport int operator==

(

const WStr &

ws

)

const

Remarks:

Equality operator.

Returns:

Nonzero if the strings are equal; otherwise 0.

UtilExport int operator!=

(

const WStr &

ws

)

const

Remarks:

Inequality operator.

Returns:

Zero if the strings are equal; otherwise 1.

UtilExport int operator<

(

const WStr &

ws

)

const

Remarks:

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

UtilExport int operator<=

(

const WStr &

ws

)

const

Remarks:

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

UtilExport int operator>

(

const WStr &

ws

)

const

Remarks:

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

UtilExport int operator>=

(

const WStr &

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

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