DWFCore::DWFString Class Reference
[Platform-specific Class and Function Definitions]

#include "dwfcore/String.h"

Inheritance diagram for DWFCore::DWFString:

Inheritance graph
[legend]
Collaboration diagram for DWFCore::DWFString:

Collaboration graph
[legend]
List of all members.

Detailed Description

A platform-independent Unicode string class.

Since:
1.0.1
This string class is used as an unambigious boundary object type especially where both "narrow" and "wide" character strings are used. This class always stores Unicode data in the system default wchar_t character type. This class will always assume a non-Unicode character string is encoded UTF-8.

Note:
This class does not perform any character set transcoding except where explicitly designated and only then the conversion will be wide Unicode to or from UTF-8.

This class has platform-specific implementations.

Examples:

Digest/main.cpp, Files/Files.cpp, Strings/Strings.cpp, and UUID/UUID.cpp.

Definition at line 93 of file String.h.

Public Member Functions

_DWFCORE_API ~DWFString () throw ()
_DWFCORE_API DWFString () throw ()
_DWFCORE_API DWFString (const char *pBuffer, size_t nBufferBytes) throw ( DWFException )
_DWFCORE_API DWFString (const char *zASCIIString) throw ( DWFException )
_DWFCORE_API DWFString (const wchar_t *pBuffer, size_t nBufferBytes) throw ( DWFException )
_DWFCORE_API DWFString (const wchar_t *zWideString) throw ( DWFException )
_DWFCORE_API DWFString (size_t nCharsHint) throw ( DWFException )
_DWFCORE_API DWFString (const DWFString &rDWFString) throw ( DWFException )
_DWFCORE_API DWFStringoperator= (const DWFString &rDWFString) throw ( DWFException )
_DWFCORE_API void assign (const DWFString &rDWFString) throw ( DWFException )
_DWFCORE_API void assign (const char *pBuffer, size_t nBufferBytes) throw ( DWFException )
_DWFCORE_API void assign (const char *zASCIIString) throw ( DWFException )
_DWFCORE_API void assign (const wchar_t *pBuffer, size_t nBufferBytes) throw ( DWFException )
_DWFCORE_API void assign (const wchar_t *zWideString) throw ( DWFException )
_DWFCORE_API bool operator== (const DWFString &rDWFString) const throw ()
_DWFCORE_API bool operator== (const wchar_t *zWideString) const throw ()
_DWFCORE_API bool operator!= (const DWFString &rDWFString) const throw ()
_DWFCORE_API bool operator!= (const wchar_t *zWideString) const throw ()
_DWFCORE_API bool operator< (const DWFString &rDWFString) const throw ()
_DWFCORE_API bool operator< (const wchar_t *zWideString) const throw ()
_DWFCORE_API bool operator> (const DWFString &rDWFString) const throw ()
_DWFCORE_API bool operator> (const wchar_t *zWideString) const throw ()
_DWFCORE_API void destroy () throw ( DWFException )
_DWFCORE_API void append (const DWFString &rDWFString) throw ( DWFException )
_DWFCORE_API void append (const char *pBuffer, size_t nBufferBytes) throw ( DWFException )
_DWFCORE_API void append (const char *zASCIIString) throw ( DWFException )
_DWFCORE_API void append (const wchar_t *pBuffer, size_t nBufferBytes) throw ( DWFException )
_DWFCORE_API void append (const wchar_t *zWideString) throw ( DWFException )
_DWFCORE_API size_t bytes () const throw ()
_DWFCORE_API size_t chars () const throw ()
_DWFCORE_API size_t getUTF8 (char *pBuffer, size_t nBufferBytes) const throw ( DWFException )
_DWFCORE_API size_t getUTF8 (char **ppBuffer) const throw ( DWFException )
_DWFCORE_API operator const wchar_t * () const throw ( DWFException )
_DWFCORE_API off_t find (const wchar_t cFind, off_t iOffset=0, bool bReverse=false) const throw ( DWFException )
_DWFCORE_API off_t find (const wchar_t *zFind, off_t iOffset=0, bool bReverse=false) const throw ( DWFException )
_DWFCORE_API off_t findFirst (const wchar_t cFind) const throw ( DWFException )
_DWFCORE_API off_t findLast (const wchar_t cFind) const throw ( DWFException )
_DWFCORE_API DWFString substring (size_t iPos, size_t iLen=(size_t)-1) const throw ( DWFException )

Static Public Member Functions

static _DWFCORE_API size_t EncodeUTF8 (const UCS2_char_t *zUCS2String, size_t nUCS2StringBytes, ASCII_char_t *pUTF8Buffer, size_t nUTF8BufferBytes) throw ( DWFOverflowException )
static _DWFCORE_API size_t EncodeUTF8 (const UCS4_char_t *zUCS4String, size_t nUCS4StringBytes, ASCII_char_t *pUTF8Buffer, size_t nUTF8BufferBytes) throw ( DWFOverflowException )
static _DWFCORE_API size_t DecodeUTF8 (const ASCII_char_t *zUTF8String, size_t nUTF8StringBytes, UCS2_char_t *pUCS2Buffer, size_t nUCS2BufferBytes) throw ( DWFOverflowException )
static _DWFCORE_API size_t DecodeUTF8 (const ASCII_char_t *zUTF8String, size_t nUTF8StringBytes, UCS4_char_t *pUCS4Buffer, size_t nUCS4BufferBytes) throw ( DWFOverflowException )
static _DWFCORE_API size_t EncodeXML (const ASCII_char_t *zASCIIString, size_t nASCIIStringBytes, ASCII_char_t *pXMLBuffer, size_t nXMLBufferBytes) throw ( DWFException )
static _DWFCORE_API size_t EncodeXML (const wchar_t *zWideString, size_t nWideStringBytes, wchar_t *pXMLBuffer, size_t nXMLBufferBytes, bool bHTMLEncodeNonASCII=true) throw ( DWFException )
static _DWFCORE_API size_t DecodeXML (const ASCII_char_t *zXMLString, size_t nXMLStringBytes, ASCII_char_t *pASCIIBuffer, size_t nASCIIBufferBytes) throw ( DWFException )
static _DWFCORE_API size_t DecodeXML (const wchar_t *zXMLString, size_t nXMLStringBytes, wchar_t *pWideStringBuffer, size_t nWideStringBufferBytes) throw ( DWFException )
static _DWFCORE_API size_t EncodeBase64 (const void *pRawBuffer, size_t nRawBufferBytes, void *pOutBuffer, size_t nOutBufferBytes, bool bRFC1521Compliant=true) throw ( DWFOverflowException )
static _DWFCORE_API size_t DecodeBase64 (const void *pRawBuffer, size_t nRawBufferBytes, void *pOutBuffer, size_t nOutBufferBytes, bool bRFC1521Compliant=true) throw ( DWFOverflowException )
static _DWFCORE_API double StringToDouble (const char *zString) throw ( DWFException )
static _DWFCORE_API double StringToDouble (const wchar_t *zString) throw ( DWFException )
static _DWFCORE_API DWFString DoubleToString (double dValue, short nPrecision, short nWidth=-1) throw ( DWFException )
static _DWFCORE_API void DoubleToString (wchar_t *pBuffer, size_t nBufferChars, double dValue, short nPrecision, short nWidth=-1) throw ( DWFException )
static _DWFCORE_API void DoubleToString (char *pBuffer, size_t nBufferChars, double dValue, short nPrecision, short nWidth=-1) throw ( DWFException )
static _DWFCORE_API wchar_t * RepairDecimalSeparators (wchar_t *zString) throw ( DWFException )
static _DWFCORE_API char * RepairDecimalSeparators (char *zString) throw ( DWFException )
static _DWFCORE_API off_t Find (const wchar_t *zString, const wchar_t cFind, off_t iOffset=0, bool bReverse=false) throw ( DWFInvalidArgumentException )
static _DWFCORE_API off_t Find (const wchar_t *zString, const wchar_t *zFind, off_t iOffset=0, bool bReverse=false) throw ( DWFInvalidArgumentException )
static _DWFCORE_API off_t FindFirst (const wchar_t *zString, const wchar_t cFind) throw ()
static _DWFCORE_API off_t FindLast (const wchar_t *zString, const wchar_t cFind) throw ()
static _DWFCORE_API DWFStringBuildFixedASCIIString (const char *zASCIIString) throw ( DWFException )


Constructor & Destructor Documentation

_DWFCORE_API DWFCore::DWFString::~DWFString  )  throw ()
 

Destructor

Exceptions:
None 

_DWFCORE_API DWFCore::DWFString::DWFString  )  throw ()
 

Constructor

Exceptions:
None 

_DWFCORE_API DWFCore::DWFString::DWFString const char *  pBuffer,
size_t  nBufferBytes
throw ( DWFException )
 

Constructor

Build content from an ASCII character buffer. This buffer is assumed to be a valid UTF-8 encoded string and will be decoded as such and stored internally as Unicode.

Parameters:
pBuffer The buffer from which to build.
nBufferBytes The number of bytes in pBuffer.
Exceptions:
DWFException 

_DWFCORE_API DWFCore::DWFString::DWFString const char *  zASCIIString  )  throw ( DWFException )
 

Constructor

Build content from an ASCII character string. This buffer is assumed to be a valid UTF-8 encoded string and will be decoded as such and stored internally as Unicode.

Parameters:
zASCIIString The null-terminated string from which to build.
Exceptions:
DWFException 

_DWFCORE_API DWFCore::DWFString::DWFString const wchar_t *  pBuffer,
size_t  nBufferBytes
throw ( DWFException )
 

Constructor

Build content from a wide character buffer.

Parameters:
pBuffer The buffer from which to build.
nBufferBytes The number of bytes in pBuffer.
Exceptions:
DWFException 

_DWFCORE_API DWFCore::DWFString::DWFString const wchar_t *  zWideString  )  throw ( DWFException )
 

Constructor

Build content from a wide character string.

Parameters:
zWideString The null-terminated string from which to build.
Exceptions:
DWFException 

_DWFCORE_API DWFCore::DWFString::DWFString size_t  nCharsHint  )  throw ( DWFException )
 

Constructor

Build an empty string with a given pre-allocation size. This will cause the string to always have at least that many characters in its heap buffer. As the string is used, the heap buffer may grow, but will never be reduced in size. This will disable the memory reduction optimization specified by DWFCORE_STRING_PREFER_HEAP_LIMIT_IN_BYTES.

Parameters:
nCharsHint The number of characters to pre-allocate.
Exceptions:
DWFException 
Since:
1.4.0

_DWFCORE_API DWFCore::DWFString::DWFString const DWFString rDWFString  )  throw ( DWFException )
 

Copy Constructor

Parameters:
rDWFString The string from which to build.
Exceptions:
DWFException 


Member Function Documentation

_DWFCORE_API void DWFCore::DWFString::append const wchar_t *  zWideString  )  throw ( DWFException )
 

Add content from a wide character string.

Parameters:
zWideString The null-terminated string from which to build.
Exceptions:
DWFException 

_DWFCORE_API void DWFCore::DWFString::append const wchar_t *  pBuffer,
size_t  nBufferBytes
throw ( DWFException )
 

Add content from a wide character buffer.

Parameters:
pBuffer The buffer from which to build.
nBufferBytes The number of bytes in pBuffer.
Exceptions:
DWFException 

_DWFCORE_API void DWFCore::DWFString::append const char *  zASCIIString  )  throw ( DWFException )
 

Add content from an ASCII character string. This buffer is assumed to be a valid UTF-8 encoded string and will be decoded as such and stored internally as Unicode.

Parameters:
zASCIIString The null-terminated string from which to build.
Exceptions:
DWFException 

_DWFCORE_API void DWFCore::DWFString::append const char *  pBuffer,
size_t  nBufferBytes
throw ( DWFException )
 

Add content from an ASCII character buffer. This buffer is assumed to be a valid UTF-8 encoded string and will be decoded as such and stored internally as Unicode.

Parameters:
pBuffer The buffer from which to build.
nBufferBytes The number of bytes in pBuffer.
Exceptions:
DWFException 

_DWFCORE_API void DWFCore::DWFString::append const DWFString rDWFString  )  throw ( DWFException )
 

Add content from another DWFString.

Parameters:
rDWFString The string from which to copy content.
Exceptions:
DWFException 
Examples:
Digest/main.cpp, and Strings/Strings.cpp.

_DWFCORE_API void DWFCore::DWFString::assign const wchar_t *  zWideString  )  throw ( DWFException )
 

Build content from a wide character string.

Parameters:
zWideString The null-terminated string from which to build.
Exceptions:
DWFException 

_DWFCORE_API void DWFCore::DWFString::assign const wchar_t *  pBuffer,
size_t  nBufferBytes
throw ( DWFException )
 

Build content from a wide character buffer.

Parameters:
pBuffer The buffer from which to build.
nBufferBytes The number of bytes in pBuffer.
Exceptions:
DWFException 

_DWFCORE_API void DWFCore::DWFString::assign const char *  zASCIIString  )  throw ( DWFException )
 

Set the string content from an ASCII character string. This buffer is assumed to be a valid UTF-8 encoded string and will be decoded as such and stored internally as Unicode.

Parameters:
zASCIIString The null-terminated string from which to build.
Exceptions:
DWFException 

_DWFCORE_API void DWFCore::DWFString::assign const char *  pBuffer,
size_t  nBufferBytes
throw ( DWFException )
 

Set the string content from an ASCII character buffer. This buffer is assumed to be a valid UTF-8 encoded string and will be decoded as such and stored internally as Unicode.

Parameters:
pBuffer The buffer from which to build.
nBufferBytes The number of bytes in pBuffer.
Exceptions:
DWFException 

_DWFCORE_API void DWFCore::DWFString::assign const DWFString rDWFString  )  throw ( DWFException )
 

Set the string content from another DWFString.

Parameters:
rDWFString The string from which to copy content.
Exceptions:
DWFException 
Examples:
Files/Files.cpp, and Strings/Strings.cpp.

static _DWFCORE_API DWFString* DWFCore::DWFString::BuildFixedASCIIString const char *  zASCIIString  )  throw ( DWFException ) [static]
 

Builds a restricted, immutable DWFString with ASCII data.

This method should be used with extreme care, if at all. Since DWFString is used as the API currency for string data, there inevitably arises the situation where raw ASCII, and sometimes MBCS, string data must be communicated via a DWFString object. The very nature of this class (and in fact its documentation) demands any ASCII data be UTF-8 encoded. This will corrupt any non US-ASCII wishing to stay as such. Fixed ASCII DWFStrings are not as functional as Unicode versions. These objects will throw exceptions when certain methods are used. Exercise caution when using these objects. It is best to restrict usage to this method as getUTF8() which will return the raw ASCII data unmodified.

Parameters:
zASCIIString The character data to store. This data may not be modified for the lifetime of the object.
Returns:
The restricted, immutable string object. This pointer must be deleted by the caller using the DWFCORE_FREE_OBJECT macro.
Exceptions:
DWFException 

_DWFCORE_API size_t DWFCore::DWFString::bytes  )  const throw () [inline]
 

Returns the content length as byte count.

Returns:
The number of bytes in the string.
Examples:
Files/Files.cpp, and Strings/Strings.cpp.

Definition at line 1069 of file String.h.

_DWFCORE_API size_t DWFCore::DWFString::chars  )  const throw () [inline]
 

Returns the content length as wide character count.

Returns:
The number of wide characters in the string.
Examples:
Strings/Strings.cpp.

Definition at line 1093 of file String.h.

static _DWFCORE_API size_t DWFCore::DWFString::DecodeBase64 const void *  pRawBuffer,
size_t  nRawBufferBytes,
void *  pOutBuffer,
size_t  nOutBufferBytes,
bool  bRFC1521Compliant = true
throw ( DWFOverflowException ) [static]
 

Performs fast Base64 decoding of base64 strings.

This method handles encodings that are RFC1521 Compliant, or those that are of the DWF modified form, as produced by DWFString::EncodeBase64

All buffers are assummed to be pre-allocated.

Note that Output is not null terminated string

Parameters:
pRawBuffer input buffer
nRawBufferBytes input buffer size
pOutBuffer The destintation buffer into which the resultant decoded string will be written. If this buffer is NULL, the function will return the number of bytes that will be required to hold the resultant decoded string.
nOutBufferBytes The length of pOutBuffer in bytes.
bRFC1521Compliant indicates if input buffer was encoded to RFC1521 spec
Returns:
size of output buffer, 0 if function fails.
Exceptions:
DWFOverflowException 

static _DWFCORE_API size_t DWFCore::DWFString::DecodeUTF8 const ASCII_char_t zUTF8String,
size_t  nUTF8StringBytes,
UCS4_char_t pUCS4Buffer,
size_t  nUCS4BufferBytes
throw ( DWFOverflowException ) [static]
 

Performs fast UTF-8 decoding into 32-bit UCS-4 character strings.

Parameters:
zUTF8String The source string encoded in UTF-8 to decode.
nUTF8StringBytes The length of zUTF8String in bytes.
pUCS4Buffer The destintation buffer into which the resultant decoded UCS-4 string will be written. If this buffer is NULL, the function will return the number of bytes that will be required to hold the resultant decoded UCS-4 string.
nUCS4BufferBytes The length of pUCS4Buffer in bytes.
Returns:
The actual length (in bytes) of the decoded UCS-4 string written into pUCS4Buffer. This value does not include any null termination bytes.
Exceptions:
DWFOverflowException 

static _DWFCORE_API size_t DWFCore::DWFString::DecodeUTF8 const ASCII_char_t zUTF8String,
size_t  nUTF8StringBytes,
UCS2_char_t pUCS2Buffer,
size_t  nUCS2BufferBytes
throw ( DWFOverflowException ) [static]
 

Performs fast UTF-8 decoding into 16-bit UCS-2 character strings.

Parameters:
zUTF8String The source string encoded in UTF-8 to decode.
nUTF8StringBytes The length of zUTF8String in bytes.
pUCS2Buffer The destintation buffer into which the resultant decoded UCS-2 string will be written. If this buffer is NULL, the function will return the number of bytes that will be required to hold the resultant decoded UCS-2 string.
nUCS2BufferBytes The length of pUCS2Buffer in bytes.
Returns:
The actual length (in bytes) of the decoded UCS-2 string written into pUCS2Buffer. This value does not include any null termination bytes.
Exceptions:
DWFOverflowException 

static _DWFCORE_API size_t DWFCore::DWFString::DecodeXML const wchar_t *  zXMLString,
size_t  nXMLStringBytes,
wchar_t *  pWideStringBuffer,
size_t  nWideStringBufferBytes
throw ( DWFException ) [static]
 

Performs fast XML decoding for character strings.

Parameters:
zXMLString The source string with XML character encoding. This string is processed one wide character at a time.
nXMLStringBytes The length of zXMLString in bytes.
pWideStringBuffer The destintation buffer into which the resultant decoded string will be written. If this buffer is NULL, the function will return the number of bytes that will be required to hold the resultant decoded string.
nWideStringBufferBytes The length of pWideStringBuffer in bytes.
Returns:
The actual length (in bytes) of the decoded string written into pWideStringBuffer. This value does not include any null termination bytes.
Exceptions:
DWFException 

static _DWFCORE_API size_t DWFCore::DWFString::DecodeXML const ASCII_char_t zXMLString,
size_t  nXMLStringBytes,
ASCII_char_t pASCIIBuffer,
size_t  nASCIIBufferBytes
throw ( DWFException ) [static]
 

Performs fast XML decoding for character strings.

Parameters:
zXMLString The source string with XML character encoding. This string is processed one 8-bit character at a time.
nXMLStringBytes The length of zXMLString in bytes.
pASCIIBuffer The destintation buffer into which the resultant decoded string will be written. If this buffer is NULL, the function will return the number of bytes that will be required to hold the resultant decoded string.
nASCIIBufferBytes The length of pASCIIBuffer in bytes.
Returns:
The actual length (in bytes) of the decoded string written into pASCIIBuffer. This value does not include any null termination bytes.
Exceptions:
DWFException 

_DWFCORE_API void DWFCore::DWFString::destroy  )  throw ( DWFException )
 

Frees all current resources and resets the object.

Exceptions:
None 
Examples:
Strings/Strings.cpp.

static _DWFCORE_API void DWFCore::DWFString::DoubleToString char *  pBuffer,
size_t  nBufferChars,
double  dValue,
short  nPrecision,
short  nWidth = -1
throw ( DWFException ) [static]
 

Perform locale-independent conversion from a double primitive type to ASCII string representation.

This algorithm will convert double value to wide string representation using snprintf regardless of the character used (in the double) to represent the decimal separator.

Parameters:
pBuffer The buffer in which to write the string
pBufferChars The length of pBuffer in characters
dValue The floating point number to be converted into String
nPrecision Number of digits to be printed as a precision
nWidth Number of digits to be printed before decimal point
Exceptions:
DWFException 

static _DWFCORE_API void DWFCore::DWFString::DoubleToString wchar_t *  pBuffer,
size_t  nBufferChars,
double  dValue,
short  nPrecision,
short  nWidth = -1
throw ( DWFException ) [static]
 

Perform locale-independent conversion from a double primitive type to wide string representation.

This algorithm will convert double value to wide string representation using snwprintf regardless of the character used (in the double) to represent the decimal separator.

Parameters:
pBuffer The buffer in which to write the string
pBufferChars The length of pBuffer in characters
dValue The floating point number to be converted into String
nPrecision Number of digits to be printed as a precision
nWidth Number of digits to be printed before decimal point
Exceptions:
DWFException 

static _DWFCORE_API DWFString DWFCore::DWFString::DoubleToString double  dValue,
short  nPrecision,
short  nWidth = -1
throw ( DWFException ) [static]
 

Perform locale-independent conversion from a double primitive type to wide string representation.

This algorithm will convert double value to wide string representation using sprintf regardless of the character used (in the double) to represent the decimal separator.

Parameters:
dValue The floating point number to be converted into String
nPrecision Number of digits to be printed as a precision
nWidth Number of digits to be printed before decimal point
Returns:
The number.
Exceptions:
DWFException 

static _DWFCORE_API size_t DWFCore::DWFString::EncodeBase64 const void *  pRawBuffer,
size_t  nRawBufferBytes,
void *  pOutBuffer,
size_t  nOutBufferBytes,
bool  bRFC1521Compliant = true
throw ( DWFOverflowException ) [static]
 

Performs fast Base64 encoding.

This method produces two flavors of encoded output. The first, as would be expected, complies with RFC 1521 (Section 5.2) and will always bad leftover bytes with '='. The second is a modification made for DWF where no byte padding is used and the 64th character '/' has been replaced by '_'. This was done to allow encoded [UUID - see DWFCore::DWFUUID::uuid(bSquash = true)] strings to be used in DWF section path naming.

Parameters:
pRawBuffer The source byte buffer to encode. This string is processed one 8-bit character at a time.
nRawBufferBytes The length of pRawBuffer in bytes.
pOutBuffer The destintation buffer into which the resultant Base64 encoded string will be written. If this buffer is NULL, the function will return the number of bytes that will be required to hold the resultant Base64 encoded string.
nOutBufferBytes The length of pOutBuffer in bytes.
bRFC1521Compliant If true, this method will produce a Base64 Content-Transfer-Encoding compliant with the specification in which it has been detailed, otherwise the encoding will be optimized for DWF usage.
Returns:
The actual length (in bytes) of the XML encoded string written into pOutBuffer. This value does not include any null termination bytes.
Exceptions:
DWFOverflowException 
Examples:
UUID/UUID.cpp.

static _DWFCORE_API size_t DWFCore::DWFString::EncodeUTF8 const UCS4_char_t zUCS4String,
size_t  nUCS4StringBytes,
ASCII_char_t pUTF8Buffer,
size_t  nUTF8BufferBytes
throw ( DWFOverflowException ) [static]
 

Performs fast UTF-8 encoding for 32-bit UCS-4 character strings.

Parameters:
zUCS4String The source string to encode as UTF-8. The character data type must be 32-bit UCS-4 (or equivalently, 32-bit UTF-32.)
nUCS4StringBytes The length of zUCS4String in bytes.
pUTF8Buffer The destintation buffer into which the resultant UTF-8 encoded string will be written. If this buffer is NULL, the function will return the number of bytes that will be required to hold the resultant UTF-8 encoded string.
nUTF8BufferBytes The length of pUTF8Buffer in bytes.
Returns:
The actual length (in bytes) of the UTF-8 encoded string written into pUTF8Buffer. This value does not include any null termination bytes.
Exceptions:
DWFOverflowException 

static _DWFCORE_API size_t DWFCore::DWFString::EncodeUTF8 const UCS2_char_t zUCS2String,
size_t  nUCS2StringBytes,
ASCII_char_t pUTF8Buffer,
size_t  nUTF8BufferBytes
throw ( DWFOverflowException ) [static]
 

Performs fast UTF-8 encoding for 16-bit UCS-2 character strings.

Parameters:
zUCS2String The source string to encode as UTF-8. The character data type must be 16-bit UCS-2 (or equivalently, 16-bit UTF-16 with no surrogate pairs or byte-order marker.)
nUCS2StringBytes The length of zUCS2String in bytes.
pUTF8Buffer The destintation buffer into which the resultant UTF-8 encoded string will be written. If this buffer is NULL, the function will return the number of bytes that will be required to hold the resultant UTF-8 encoded string.
nUTF8BufferBytes The length of pUTF8Buffer in bytes.
Returns:
The actual length (in bytes) of the UTF-8 encoded string written into pUTF8Buffer. This value does not include any null termination bytes.
Exceptions:
DWFOverflowException 

static _DWFCORE_API size_t DWFCore::DWFString::EncodeXML const wchar_t *  zWideString,
size_t  nWideStringBytes,
wchar_t *  pXMLBuffer,
size_t  nXMLBufferBytes,
bool  bHTMLEncodeNonASCII = true
throw ( DWFException ) [static]
 

Performs a restricted, fast XML encoding for wide character strings.

This is special method that only encodes explicit characters in the source string:

L'<' (less than) -> L"<" L'>' (greater than) -> L">" L'&' (ampersand) -> L"&" L'"' (quote) -> L""" L''' (apostrophe) -> L"'"

All other source characters are left unchanged. Care should be taken when using this method since it is definitely a special-case algorithm made available for those situations when a "reverse-encoding process" Unicode -> Unicode XML -> UTF-8 is required.

Parameters:
zWideString The source string to encode for XML. The character data type must be match the system wchar_t type definition.
nWideStringBytes The length of zWideString in bytes.
pXMLBuffer The destintation buffer into which the resultant "special" XML string will be written. Note that this is a wchar_t character type string. If this buffer is NULL, the function will return the number of bytes that will be required to hold the resultant string.
nXMLBufferBytes The length of pXMLBuffer in bytes.
bHTMLEncodeNonASCII If true, all non-ascii characters will be html-encoded. In a perfect world, this should not be necessary. However, the 6.X series of DWF toolkits was incapable of correctly reading non-ascii UTF-8 characters and required that all such characters be HTML-encoded. As of spring 2007, the DWF round-tripping loader in AutoCAD is still using the 6.X library, so we are forced to keep outputting these characters in this encoding by default.
Returns:
The actual length (in bytes) of the "special" XML encoded string written into pXMLBuffer. This value does not include any null termination bytes.
Exceptions:
DWFException 

static _DWFCORE_API size_t DWFCore::DWFString::EncodeXML const ASCII_char_t zASCIIString,
size_t  nASCIIStringBytes,
ASCII_char_t pXMLBuffer,
size_t  nXMLBufferBytes
throw ( DWFException ) [static]
 

Performs fast XML encoding for character strings.

Parameters:
zASCIIString The source string to encode for XML. This string is processed one 8-bit character at a time.
nASCIIStringBytes The length of zASCIIString in bytes.
pXMLBuffer The destintation buffer into which the resultant XML encoded string will be written. If this buffer is NULL, the function will return the number of bytes that will be required to hold the resultant XML encoded string.
nXMLBufferBytes The length of pXMLBuffer in bytes.
Returns:
The actual length (in bytes) of the XML encoded string written into pXMLBuffer. This value does not include any null termination bytes.
Exceptions:
DWFException 

_DWFCORE_API off_t DWFCore::DWFString::find const wchar_t *  zFind,
off_t  iOffset = 0,
bool  bReverse = false
const throw ( DWFException )
 

Searches for a substring in a string from a given position in the string.

Parameters:
zFind The substring to search for.
iOffset The index (inclusive) from which to start the search. For reverse finds this is relative to the end of zString. This value must always be greater than or equal to zero.
bReverse If true, the search will start from the end of the content.
Returns:
The index of the first occurence of zFind after iOffset or -1 if not found.
Exceptions:
DWFException 

_DWFCORE_API off_t DWFCore::DWFString::find const wchar_t  cFind,
off_t  iOffset = 0,
bool  bReverse = false
const throw ( DWFException )
 

Searches for a character in a string from a given position in the string.

Parameters:
cFind The character to search for.
iOffset The index (inclusive) from which to start the search. For reverse finds this is relative to the end of zString. This value must always be greater than or equal to zero.
bReverse If true, the search will start from the end of the content.
Returns:
The index of the first occurence of cFind after iOffset or -1 if not found.
Exceptions:
DWFException 
Examples:
Strings/Strings.cpp.

static _DWFCORE_API off_t DWFCore::DWFString::Find const wchar_t *  zString,
const wchar_t *  zFind,
off_t  iOffset = 0,
bool  bReverse = false
throw ( DWFInvalidArgumentException ) [static]
 

Searches for a substring in a string from a given position in the string.

Parameters:
zString The string to search.
zFind The substring to search for.
iOffset The index (inclusive) from which to start the search. For reverse finds this is relative to the end of zString. This value must always be greater than or equal to zero.
bReverse If true, the search will start from the end of zString.
Returns:
The index of the first occurence of zFind in zString after iOffset or -1 if not found.
Exceptions:
DWFInvalidArgumentException 

static _DWFCORE_API off_t DWFCore::DWFString::Find const wchar_t *  zString,
const wchar_t  cFind,
off_t  iOffset = 0,
bool  bReverse = false
throw ( DWFInvalidArgumentException ) [static]
 

Searches for a character in a string from a given position in the string.

Parameters:
zString The string to search.
cFind The character to search for.
iOffset The index (inclusive) from which to start the search. For reverse finds this is relative to the end of zString. This value must always be greater than or equal to zero.
bReverse If true, the search will start from the end of zString.
Returns:
The index of the first occurence of cFind in zString after iOffset or -1 if not found.
Exceptions:
DWFInvalidArgumentException 
Examples:
Strings/Strings.cpp.

_DWFCORE_API off_t DWFCore::DWFString::findFirst const wchar_t  cFind  )  const throw ( DWFException )
 

Searches for the first occurence of a character in this string.

Parameters:
cFind The character to search for.
Returns:
The index of the first occurence of cFind in or -1 if not found.
Exceptions:
DWFException 

static _DWFCORE_API off_t DWFCore::DWFString::FindFirst const wchar_t *  zString,
const wchar_t  cFind
throw () [static]
 

Searches for the first occurence of a character in a string.

Parameters:
zString The string to search.
cFind The character to search for.
Returns:
The index of the first occurence of cFind in zString or -1 if not found.
Exceptions:
None 

_DWFCORE_API off_t DWFCore::DWFString::findLast const wchar_t  cFind  )  const throw ( DWFException )
 

Searches for the last occurence of a character in this string.

Parameters:
cFind The character to search for.
Returns:
The index of the last occurence of cFind in or -1 if not found.
Exceptions:
DWFException 

static _DWFCORE_API off_t DWFCore::DWFString::FindLast const wchar_t *  zString,
const wchar_t  cFind
throw () [static]
 

Searches for the last occurence of a character in a string.

Parameters:
zString The string to search.
cFind The character to search for.
Returns:
The index of the last occurence of cFind in zString or -1 if not found.
Exceptions:
None 

_DWFCORE_API size_t DWFCore::DWFString::getUTF8 char **  ppBuffer  )  const throw ( DWFException )
 

Returns a UTF-8 encoded representation of the content into a newly allocated memory buffer. The caller must free this buffer with the DWFCORE_FREE_MEMORY macro.

For fixed ASCII restricted DWFString objects, this method will return the original ASCII data, unmodified.

Parameters:
ppBuffer A pointer to the newly allocated buffer containing the UTF-8 encoded string representation.
Returns:
The number of bytes used in ppBuffer by the UTF-8 encoded string.
Exceptions:
DWFException 

_DWFCORE_API size_t DWFCore::DWFString::getUTF8 char *  pBuffer,
size_t  nBufferBytes
const throw ( DWFException )
 

Returns a UTF-8 encoded representation of the content into the buffer provided.

For fixed ASCII restricted DWFString objects, this method will return the original ASCII data, unmodified.

Parameters:
pBuffer The buffer to hold the UTF-8 encoded string. If NULL, the method will return the number of bytes required to hold the encoded string.
nBufferBytes The number of bytes in pBuffer.
Returns:
The number of bytes used in pBuffer by the UTF-8 encoded string.
Exceptions:
DWFException 
Examples:
Strings/Strings.cpp.

_DWFCORE_API DWFCore::DWFString::operator const wchar_t *  )  const throw ( DWFException ) [inline]
 

Cast Operator

Returns:
A pointer to the internal content. This pointer will be NULL if the string has no content.
Exceptions:
DWFException 

Definition at line 1107 of file String.h.

_DWFCORE_API bool DWFCore::DWFString::operator!= const wchar_t *  zWideString  )  const throw ()
 

Inequality Operator

Parameters:
zWideString A null-terminated wide character string to compare.
Returns:
true if the content of the two strings differs, false otherwise.
Exceptions:
None 

_DWFCORE_API bool DWFCore::DWFString::operator!= const DWFString rDWFString  )  const throw ()
 

Inequality Operator

Parameters:
rDWFString The string to compare.
Returns:
true if the content of the two strings differs, false otherwise.
Exceptions:
None 

_DWFCORE_API bool DWFCore::DWFString::operator< const wchar_t *  zWideString  )  const throw ()
 

Less Than Operator

Parameters:
zWideString A null-terminated wide character string to compare.
Returns:
true if the content this object is ordered 'less than' zWideString, false otherwise.
Exceptions:
None 

_DWFCORE_API bool DWFCore::DWFString::operator< const DWFString rDWFString  )  const throw ()
 

Less Than Operator

Parameters:
rDWFString The string to compare.
Returns:
true if the content this object is ordered 'less than' the content of rDWFString, false otherwise.
Exceptions:
None 

_DWFCORE_API DWFString& DWFCore::DWFString::operator= const DWFString rDWFString  )  throw ( DWFException )
 

Assignment Operator

Parameters:
rDWFString The string from which to build.
Exceptions:
DWFException 

_DWFCORE_API bool DWFCore::DWFString::operator== const wchar_t *  zWideString  )  const throw ()
 

Equality Operator

Parameters:
zWideString A null-terminated wide character string to compare.
Returns:
true if the content of the two strings are equal, false otherwise.
Exceptions:
None 

_DWFCORE_API bool DWFCore::DWFString::operator== const DWFString rDWFString  )  const throw ()
 

Equality Operator

Parameters:
rDWFString The string to compare.
Returns:
true if the content of the two strings are equal, false otherwise.
Exceptions:
None 

_DWFCORE_API bool DWFCore::DWFString::operator> const wchar_t *  zWideString  )  const throw ()
 

Greater Than Operator

Parameters:
zWideString A null-terminated wide character string to compare.
Returns:
true if the content this object is ordered 'greater than' zWideString, false otherwise.
Exceptions:
None 

_DWFCORE_API bool DWFCore::DWFString::operator> const DWFString rDWFString  )  const throw ()
 

Greater Than Operator

Parameters:
rDWFString The string to compare.
Returns:
true if the content this object is ordered 'greater than' the content of rDWFString, false otherwise.
Exceptions:
None 

static _DWFCORE_API char* DWFCore::DWFString::RepairDecimalSeparators char *  zString  )  throw ( DWFException ) [static]
 

This function will convert any non-whitespace, non-numeric character that occurs between two numeric characters into a decimal point (period) '.'

Warning:
This function will modify the original string.
Note:
This function expects zString to represent one number.
Parameters:
zString The ASCII string representation of the number.
Returns:
The repaired string (this will match zString.)
Exceptions:
DWFException 

static _DWFCORE_API wchar_t* DWFCore::DWFString::RepairDecimalSeparators wchar_t *  zString  )  throw ( DWFException ) [static]
 

This function will convert any non-whitespace, non-numeric character that occurs between two numeric characters into a decimal point (period) '.'

Warning:
This function will modify the original string.
Note:
This function expects zString to represent one number.
Parameters:
zString The wide string representation of the number.
Returns:
The repaired string (this will match zString.)
Exceptions:
DWFException 

static _DWFCORE_API double DWFCore::DWFString::StringToDouble const wchar_t *  zString  )  throw ( DWFException ) [static]
 

Perform locale-independent conversion from a wide string representation to double primitive type.

This algorithm will convert a wide string representation of double precision floating-point number into a double precision native type regardless of the character used (in the string) to represent the decimal separator.

Parameters:
zString The wide string representation of the number.
Returns:
The number.
Exceptions:
DWFException 

static _DWFCORE_API double DWFCore::DWFString::StringToDouble const char *  zString  )  throw ( DWFException ) [static]
 

Perform locale-independent conversion from a string representation to double primitive type.

This algorithm will convert a string representation of double precision floating-point number into a double precision native type regardless of the character used (in the string) to represent the decimal separator.

Parameters:
zString The string representation of the number.
Returns:
The number.
Exceptions:
DWFException 

_DWFCORE_API DWFString DWFCore::DWFString::substring size_t  iPos,
size_t  iLen = (size_t)-1
const throw ( DWFException )
 

Creates a substring.

Parameters:
iPos The index (inclusive) of first character in the new string.
iLen The number of characters to copy into the new string, or -1 to copy to end of string.
Returns:
The new substring.
Exceptions:
DWFException 


The documentation for this class was generated from the following file:
Generated on Tue Jan 6 22:39:42 2009 for Autodesk DWF Core Library by  doxygen 1.4.5