UTF8Str Class Reference

#include <strclass.h>

Class Description

See also

Class CStr, WStr and MaxString, Guidelines for Handling Character Strings.

Description:

A UTF8 encoded character string class. This class uses UTF8 encode to hold each character. This UTF8Str class provide very basic functionality Methods and operators are provided for calculating lengths, concatenation, case conversion, comparison.

Note

The memory occupied by a UTF8Str object is cannot be larger than 2Gb.

Inheritance diagram for UTF8Str:

Public Member Functions
	UTF8Str ()
	UTF8Str (const char *cs)
	UTF8Str (const UTF8Str &ws)
	UTF8Str (const MaxSDK::Util::MaxString &ws)
	UTF8Str (const MaxSDK::Util::MaxStringCastUTF8 &)
	UTF8Str (const QString &qstring)
	Conversion constructor, from QString. More...
	~UTF8Str ()
char *	dataForWrite (size_t nchars=(size_t)-1)
	Returns a pointer to this string which can be written to with up to 'nchars' characters. More...
const char *	data () const
	operator const char * () const
	operator QString () const
	Conversion operator to QString. More...
void	Resize (int nchars)
int	Length () const
int	length () const
int	ByteCount () const
int	LanguageCharacterCount () const
size_t	AllocatedChars () const
bool	isNull () const
UTF8Str &	operator= (const UTF8Str &cs)
UTF8Str &	operator= (const MaxSDK::Util::MaxString &mstr)
UTF8Str &	operator= (const MaxSDK::Util::MaxStringCastUTF8 &)
UTF8Str &	operator= (const char *cs)
UTF8Str	operator+ (const UTF8Str &cs) const
UTF8Str &	operator+= (const UTF8Str &cs)
UTF8Str &	Append (const UTF8Str &cs)
UTF8Str &	append (const UTF8Str &cs)
UTF8Str	MultiByteCharacterSubString (int firstCharacterIndex, int numberOfMBCharacters) const
int	FindMultiByteCharacterFirstByteIndex (int characterIndex) const
int	FindMultiByteCharacterLastByteIndex (int characterIndex) const
bool	operator== (const UTF8Str &cs) const
bool	operator!= (const UTF8Str &cs) const
bool	operator< (const UTF8Str &cs) const
bool	operator<= (const UTF8Str &ws) const
bool	operator> (const UTF8Str &ws) const
bool	operator>= (const UTF8Str &ws) const
void	toUpper ()
void	toLower ()
int	printf (const char *format,...)
	Write a formatted string into this UTF8Str. More...
int	vprintf (const char *format, va_list args)
	Write a formatted string into this UTF8Str. More...
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
UTF8Str	ToUTF8Str () const
WStr	ToWStr () const
MaxSDK::Util::MaxStringCast< wchar_t >	ToMCHAR (size_t *length=NULL) const
WStr	ToMSTR () const
bool	EndsWith (const UTF8Str &s, bool caseSensitive=true)
	Returns true if the string ends with s; otherwise returns false. More...
bool	StartsWith (const UTF8Str &s, bool caseSensitive=true)
	Returns true if the string starts with s; otherwise returns false. More...
size_t	NumberOfLines () const
	Returns the number of line feeds inside a string. More...

Static Public Member Functions
static UTF8Str	FromBSTR (const wchar_t *string, size_t length=(size_t)-1)
static UTF8Str	FromCP (UINT cp, const char *string, size_t length=(size_t)-1)
static UTF8Str	FromACP (const char *string, size_t length=(size_t)-1)
static UTF8Str	FromUTF8 (const char *string, size_t length=(size_t)-1)
static UTF8Str	FromOLESTR (const wchar_t *string, size_t length=(size_t)-1)
static UTF8Str	FromUTF16 (const wchar_t *string, size_t length=(size_t)-1)
static UTF8Str	FromUTF32 (const unsigned int *string, size_t length=(size_t)-1)
static UTF8Str	FromMaxString (MaxSDK::Util::MaxString &string)
static UTF8Str	FromUTF8Str (const UTF8Str &string)
static UTF8Str	FromWStr (const WStr &string)
static UTF8Str	FromMCHAR (const wchar_t *string, size_t length=(size_t)-1)
static UTF8Str	FromMSTR (const WStr &string)
Static Public Member Functions inherited from MaxHeapOperators
static UtilExport void *	operator new (size_t size)
	Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e)
	Standard new operator used to allocate objects if there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate objects that takes the type of memory, filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void	operator delete (void *ptr)
	Standard delete operator used to deallocate an object If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an object If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an object that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, void *placement_ptr)
	Placement new operator. More...
static UtilExport void	operator delete (void *ptr, void *placement_ptr)
	Placement delete operator. More...
static UtilExport void *	aligned_malloc (size_t size, size_t alignment)
	Allocates memory on a specified alignment boundary. More...
static UtilExport void *	aligned_realloc (void *ptr, size_t size, size_t alignment)
	Reallocates memory on a specified alignment boundary. More...
static UtilExport void	aligned_free (void *ptr)
	Frees a block of memory that was allocated with aligned_malloc/aligned_realloc. More...

Constructor & Destructor Documentation

UTF8Str

(

)

Remarks

Constructor. The string is set to NULL.

UTF8Str

(

const char *

cs

)

Remarks

Constructor. The string is initialized to the string passed.

UTF8Str

(

const UTF8Str &

ws

)

Remarks

Constructor. The string is initialized to the string passed.

UTF8Str

(

const MaxSDK::Util::MaxString &

ws

)

Remarks

Constructor. The string is initialized to the string passed.

UTF8Str

(

const MaxSDK::Util::MaxStringCastUTF8 &

)

Remarks

Constructor. The string is initialized to the string passed.

UTF8Str

(

const QString &

qstring

)

Conversion constructor, from QString.

~UTF8Str

(

)

Remarks

Destructor. The string is deleted.

Member Function Documentation

char* dataForWrite

(

size_t

nchars = (size_t)-1

)

Returns a pointer to this string which can be written to with up to 'nchars' characters.

Remarks

The terminating null character is not included in nchars, so technically up to nchars+1 characters may be written.

Parameters

nchars

The minimum number of characters to allocate in the string buffer (excluding the terminating null character). A value of -1 specifies that the existing buffer should be re-used.

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.

operator QString

(

)

const

Conversion operator to QString.

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. 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 up to 4 bytes. Length() or ByteCount() will count the character as up to 4 distinct chars. 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; }

UTF8Str& operator=

(

const UTF8Str &

cs

)

Remarks

Assignment operator.

UTF8Str& operator=

(

const MaxSDK::Util::MaxString &

mstr

)

Remarks

Assignment operator.

UTF8Str& operator=

(

const MaxSDK::Util::MaxStringCastUTF8 &

)

Remarks

Assignment operator.

UTF8Str& operator=

(

const char *

cs

)

Remarks

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

UTF8Str operator+

(

const UTF8Str &

cs

)

const

Remarks

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

UTF8Str& operator+=

(

const UTF8Str &

cs

)

Remarks

Concatenation. Returns this string with cs appended.

UTF8Str& Append ( const UTF8Str &  cs )

inline

Remarks

Concatenation. Returns this string with cs appended.

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

UTF8Str& append ( const UTF8Str &  cs )

inline

Remarks

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

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

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

bool operator==

(

const UTF8Str &

cs

)

const

Remarks

Equality operator.

Returns

true if the strings are equal; otherwise false.

bool operator!=

(

const UTF8Str &

cs

)

const

Remarks

Inequality operator.

Returns

false if the strings are equal; otherwise true.

bool operator<

(

const UTF8Str &

cs

)

const

Remarks

Returns true if this string is less than cs; otherwise false.

bool operator<=

(

const UTF8Str &

ws

)

const

Remarks

Returns true if this string is less than or equal to ws; otherwise false.

bool operator>

(

const UTF8Str &

ws

)

const

Remarks

Returns true if this string is greater than ws; otherwise false.

bool operator>=

(

const UTF8Str &

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

Writes the format string, filled in by the optional arguments into this UTF8Str. See the ISO C++ documentation for more information on printf and format strings. Note: do not use ls formatting since conversion from wide string to narrow string will occur using active code page encoding rather than utf8 encoding

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

This method is similar to UTF8Str::printf. Instead of taking a variable list of arguments as parameter, it takes a structure representing a variable list of argument. This allows UTF8Str objects to be used to build strings based on a format string and a variable number of arguments. Note: do not use ls formatting since conversion from wide string to narrow string will occur using active code page encoding rather than utf8 encoding

wchar_t* ToBSTR

(

)

const

Remarks

Returns the string in memory allocated by SysAllocString. Caller is responsible for freeing memory using SysFreeString.

static UTF8Str FromBSTR ( const wchar_t *  string, size_t  length = (size_t)-1  )

static

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

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

static

MaxSDK::Util::MaxStringCast<char> ToACP

(

size_t *

length = NULL

)

const

static UTF8Str FromACP ( const char *  string, size_t  length = (size_t)-1  )

static

MaxSDK::Util::MaxStringCastUTF8 ToUTF8

(

size_t *

length = NULL

)

const

static UTF8Str FromUTF8 ( const char *  string, size_t  length = (size_t)-1  )

static

MaxSDK::Util::MaxStringCast<WCHAR> ToOLESTR

(

size_t *

length = NULL

)

const

static UTF8Str FromOLESTR ( const wchar_t *  string, size_t  length = (size_t)-1  )

static

MaxSDK::Util::MaxStringCast<WCHAR> ToUTF16

(

size_t *

length = NULL

)

const

static UTF8Str FromUTF16 ( const wchar_t *  string, size_t  length = (size_t)-1  )

static

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

(

size_t *

length = NULL

)

const

static UTF8Str FromUTF32 ( const unsigned int *  string, size_t  length = (size_t)-1  )

static

MaxSDK::Util::MaxString ToMaxString

(

)

const

void ToMaxString

(

MaxSDK::Util::MaxString &

)

const

static UTF8Str FromMaxString ( MaxSDK::Util::MaxString &  string )

inlinestatic

{ return UTF8Str(string); }

UTF8Str ToUTF8Str ( ) const

inline

{ return *this; }

static UTF8Str FromUTF8Str ( const UTF8Str &  string )

inlinestatic

{ return UTF8Str(string); }

WStr ToWStr

(

)

const

static UTF8Str FromWStr ( const WStr &  string )

static

MaxSDK::Util::MaxStringCast<wchar_t> ToMCHAR ( size_t *  length = NULL ) const

inline

{ return ToUTF16(length); }

static UTF8Str FromMCHAR ( const wchar_t *  string, size_t  length = (size_t)-1  )

inlinestatic

{ return FromUTF16(string, length); }

WStr ToMSTR

(

)

const

static UTF8Str FromMSTR ( const WStr &  string )

static

bool EndsWith	(	const UTF8Str &	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 StartsWith	(	const UTF8Str &	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.

size_t NumberOfLines

(

)

const

Returns the number of line feeds inside a string.