MaxString Class Reference
 
 
 
MaxString Class Reference

This reference page is linked to from the following overview topics: Unicode.


#include <maxstring.h>

Inheritance diagram for MaxString:
MaxHeapOperators

Class Description

Stores all the strings inside CStr and WStr.

CStr and WStr use this class to perform their internal operations and hold different encodings for a string. It has several goals:

  • Limit the number of conversions between codepage and string format. (ACP -> UTF8 -> UTF16) This is done by storing several version of the same string.
  • Limit the number of string copies. This class uses a lazy copy algorithm. Several MaxString objects will use the same memory blocks, and are copied prior to modification.
  • Prevent loss of information. String operations done with this object will use the most-optimized way of performing a string operation. ie. Concatenating an UTF-16 string with a ACP string will give a UTF-16 string. Note: ACP: Active Code Page is abbreviated as ACP. Depending on the Windows active language, the active code page can be different. ACP always refer to the code page that Windows API functions expect.

Public Member Functions

  MaxString ()
  Default Constructor.
  MaxString (const MaxString &)
  Copy Constructor The implementation of this function can be considered cheap in processor and memory usage.
  ~MaxString ()
  Destructor.
MaxString operator= (const MaxString &)
  Assignment operator for a MaxString.
MaxString  operator+ (const MaxString &) const
  Create a new string that is the concatenation of this string and another.
MaxString operator+= (const MaxString &)
  Appends a string at the end of this string.
int  Compare (const MaxString &) const
  Check if the strings are equal.
int  CompareIgnoreCase (const MaxString &) const
  Compare this string with another while ignoring the case.
bool  operator== (const MaxString &) const
  Equality operator.
bool  operator!= (const MaxString &) const
  Inequality operator.
bool  operator< (const MaxString &) const
  Returns true if this string is less than the other; otherwise false.
bool  operator<= (const MaxString &) const
  Returns true if this string is less than or equal to the other; otherwise false.
bool  operator> (const MaxString &) const
  Returns true if this string is greater than the other; otherwise false.
bool  operator>= (const MaxString &) const
  Returns true if this string is greater than or equal to the other; otherwise false.
bool  IsNull () const
  Determine if this string is null. Note: an empty string is not null.
void  SetNull ()
  Clears the data of this object.
char *  AllocBufferCP (UINT codepage, size_t bytes)
  Allocate a new string inside this object and returns a modifiable pointer to it.
char *  AllocBufferACP (size_t bytes)
char *  AllocBufferUTF8 (size_t bytes)
wchar_t *  AllocBufferUTF16 (size_t wchars)
unsigned int *  AllocBufferUTF32 (size_t uint)
void  SetCP (UINT codepage, const char *string, size_t length=(size_t)-1)
  Reinitializes the instance with the specified string and code page.
void  SetACP (const char *string, size_t length=(size_t)-1)
  Reinitializes the instance with the specified Active Code Page (ACP) string.
void  SetUTF8 (const char *string, size_t length=(size_t)-1)
  Reinitializes the instance with the specified UTF8 string.
void  SetUTF16 (const wchar_t *string, size_t length=(size_t)-1)
  Reinitializes the instance with the specified UTF16 string.
MaxStringCastCP  ToCP (UINT codepage, size_t *length=NULL) const
  Returns a MaxStringCastCP which in turn enables casting to a char array encoded with a specific code page.
MaxStringCast< char >  ToACP (size_t *length=NULL) const
  Cast this object to a char array using Active Code Page encoding.
MaxStringCastUTF8  ToUTF8 (size_t *length=NULL) const
  Cast this object to a UTF8 encoded string.
MaxStringCast< wchar_t >  ToUTF16 (size_t *length=NULL) const
  Cast this object to a UTF16 or UNICODE encoded string.
MaxStringCast< unsigned int >  ToUTF32 (size_t *length=NULL) const
  Cast this object to a UTF32 encoded string.
size_t  Length (UINT encoding) const
  Get the number of characters in the string, based on the encoding.
int  ConversionCount () const
  Returns the number of times this string has been converted to other encodings.
size_t  AllocatedChars () const
  Returns the number of characters allocated in memory, in which the string is stored.
UINT  CommonLosslessCP (MaxString &)
  Gets a common code page.
char *  AllocBuffer (size_t s)
const MaxStringCast< char >  ToMCHAR (size_t *length=NULL) const
wchar_t *  ToBSTR () const
  Return a BSTR of this string.
const MaxStringCast< wchar_t >  ToOLESTR (size_t *length=NULL) const
  Construct a OLE string.

Static Public Member Functions

static MaxString  FromCP (UINT codepage, const char *string, size_t length=(size_t)-1)
  Construct a MaxString that will contain a copy of a string passed in.
static MaxString  FromACP (const char *string, size_t length=(size_t)-1)
  Construct a MaxString from an Active Code Page encoded string.
static MaxString  FromUTF8 (const char *string, size_t length=(size_t)-1)
  Construct a MaxString from a UTF8 encoded string.
static MaxString  FromUTF16 (const wchar_t *, size_t length=(size_t)-1)
  Construct a MaxString from a UTF16 encoded wide string.
static MaxString  FromUTF32 (const unsigned int *, size_t length=(size_t)-1)
  Construct a MaxString from a UTF32 encoded wide string.
static MaxString  FromWin32Error (DWORD err)
  Generate a MaxString out of Win32 error code.
static MaxString  FromAnsiError (int err)
  Generate a MaxString out of an ANSI error code.
static UINT  NormalizeCP (UINT code)
  Normalize the code page.
static UINT  CommonLosslessCP (UINT codepage1, UINT codepage2)
  Gets a common code page.
static MaxString  FromMCHAR (const char *string, size_t length=(size_t)-1)
static MaxString  FromBSTR (const wchar_t *string, size_t length=(size_t)-1)
  Construct a MaxString out of a BSTR.
static MaxString  FromOLESTR (const wchar_t *string, size_t length=(size_t)-1)
  Construct a MaxString out of a OLESTR.

Protected Member Functions

  MaxString (MaxStringData *data)
  Alternate protected constructor.
MaxString operator= (MaxStringData *data)
  protected assignment operator for an internal data type.

Protected Attributes

MaxStringData *  p
  The data member that holds all encoding and string information.

Friends

class  MaxStringInternal

Constructor & Destructor Documentation

MaxString ( MaxStringData *  data ) [protected]

Alternate protected constructor.


Member Function Documentation

MaxString& operator= ( MaxStringData *  data ) [protected]

protected assignment operator for an internal data type.

bool IsNull ( ) const

Determine if this string is null. Note: an empty string is not null.

void SetNull ( )

Clears the data of this object.

char* AllocBufferCP ( UINT  codepage,
size_t  bytes 
)

Allocate a new string inside this object and returns a modifiable pointer to it.

You can modify this string as long as you don't perform any other operation with this object's instance.

char* AllocBufferACP ( size_t  bytes )
char* AllocBufferUTF8 ( size_t  bytes )
wchar_t* AllocBufferUTF16 ( size_t  wchars )
unsigned int* AllocBufferUTF32 ( size_t  uint )
size_t Length ( UINT  encoding ) const

Get the number of characters in the string, based on the encoding.

int ConversionCount ( ) const

Returns the number of times this string has been converted to other encodings.

size_t AllocatedChars ( ) const

Returns the number of characters allocated in memory, in which the string is stored.

(Including the NULL character). This is different from the number of characters actually stored for the string. Thus this can be bigger than the length of the string. It might actually be a little bit bigger than the length of the string if this object was manipulated with AllocBufferCP() or AllocBufferUTF16().

char* AllocBuffer ( size_t  s ) [inline]
const MaxStringCast< char > ToMCHAR ( size_t *  length = NULL ) const [inline]
{
        return ToACP(length);
}
static MaxString FromMCHAR ( const char *  string,
size_t  length = (size_t)-1 
) [inline, static]
{ return FromACP(string, length); }

Friends And Related Function Documentation

friend class MaxStringInternal [friend]

Member Data Documentation

MaxStringData* p [protected]

The data member that holds all encoding and string information.