UTF8Str Class Reference
 
 
 
UTF8Str Class Reference

#include <strclass.h>

Inheritance diagram for UTF8Str:
MaxHeapOperators

Class Description

See also:
Class CStr, WStr and MaxString, 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.

Public Member Functions

  UTF8Str ()
  UTF8Str (const char *cs)
  UTF8Str (const UTF8Str &ws)
  UTF8Str (const MaxSDK::Util::MaxString &ws)
  UTF8Str (const MaxSDK::Util::MaxStringCastUTF8 &)
  ~UTF8Str ()
char *  dataForWrite (size_t nchars=(size_t)-1)
const char *  data () const
  operator const char * () const
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.
int  vprintf (const char *format, va_list args)
  Write a formatted string into this UTF8Str.
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< char >  ToMCHAR (size_t *length=NULL) const
UTF8Str  ToMSTR () const
bool  EndsWith (const UTF8Str &s, bool caseSensitive=true)
  Returns true if the string ends with s; otherwise returns false.
bool  StartsWith (const UTF8Str &s, bool caseSensitive=true)
  Returns true if the string starts with s; otherwise returns false.
size_t  NumberOfLines () const
  Returns the number of lines inside a string.

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 char *string, size_t length=(size_t)-1)
static UTF8Str  FromMSTR (const UTF8Str &string)

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.
Remarks:
Constructor. The string is initialized to the string passed.
~UTF8Str ( )
Remarks:
Destructor. The string is deleted.

Member Function Documentation

char* 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 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.
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]
void ToMaxString ( MaxSDK::Util::MaxString ) const
static UTF8Str FromMaxString ( MaxSDK::Util::MaxString string ) [inline, static]
{ return UTF8Str(string); }
UTF8Str ToUTF8Str ( ) const [inline]
{ return *this; }
static UTF8Str FromUTF8Str ( const UTF8Str string ) [inline, static]
{ return UTF8Str(string); }
WStr ToWStr ( ) const
static UTF8Str FromWStr ( const WStr string ) [static]
MaxSDK::Util::MaxStringCast<char> ToMCHAR ( size_t *  length = NULL ) const [inline]
static UTF8Str FromMCHAR ( const char *  string,
size_t  length = (size_t)-1 
) [inline, static]
UTF8Str ToMSTR ( ) const [inline]
{ return *this; }
static UTF8Str FromMSTR ( const UTF8Str string ) [inline, static]
{ return UTF8Str(string); }
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 lines inside a string.