IDBCSBuffer

The IDBCSBuffer class implements the version of IString contents that supports mixed double-byte character set (DBCS) characters. This class also supports UNIX multiple-byte character set (MBCS) characters. This class ensures that multiple-byte characters are processed properly.

The use of this class is transparent to the user of class IString.


IDBCSBuffer - Member Functions and Data by Group

Constructors & Destructor

The constructor for this class is protected. Only IDBCSBuffer::allocate and IBuffer::initialize can call the constructor.


[view class]
~IDBCSBuffer
protected:
~IDBCSBuffer()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IDBCSBuffer
protected:
IDBCSBuffer(unsigned bufLength)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Allocation

Use these members to reimplement the allocation members as public.


[view class]
allocate
public:
virtual IDBCSBuffer* allocate(unsigned newLen) const

Returns a new buffer of the specified length.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Comparisons

Use these members to compare the IDBCSBuffer's contents to some other character array.


[view class]
compare
public:
virtual Comparison compare( const void* p, unsigned len ) const

Compares the buffer's contents to the contents of the specified character array.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Editing

Use these members to reimplement the following IString versions of IBuffer members. The following members are called by the corresponding IString members to edit the buffer's contents.


[view class]
center
public:
virtual IDBCSBuffer* center( unsigned newLen, char padCharacter )

Centers the receiver within a string of the specified length.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
change
public:
virtual IDBCSBuffer* change( const char* pSource, unsigned sourceLen, const char* pTarget, unsigned targetLen, unsigned startPos, unsigned numChanges )

Changes occurrences of a specified pattern to a specified replacement string. You can specify the number of changes to perform. The default is to change all occurrences of the pattern. You can also specify the position in the receiver at which to begin.

The parameters are the following:

pSource
The pattern string as a NULL-terminated string. The library searches for the pattern string within the receiver's data.
sourceLen
The length of the source string.
pTarget
The target string as a NULL-terminated string. It replaces the occurrences of the pattern string in the receiver's data.
targetLen
The length of the target string.
startPos
The position to start the search at within the target's data.
numChanges
The number of patterns to search for and change.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
insert
public:
virtual IDBCSBuffer* insert( const char* pInsert, unsigned insertLen, unsigned pos, char padCharacter )

Inserts the specified string after the specified location.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
leftJustify
public:
virtual IDBCSBuffer* leftJustify( unsigned newLen, char padCharacter )

Left-justifies the receiver in a string of the specified length. If the new length (length) is larger than the current length, the string is extended by the pad character (padCharacter). The default pad character is a blank.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
lowerCase
public:
virtual IDBCSBuffer* lowerCase()

Translates all uppercase letters in the receiver to lowercase.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
overlayWith
public:
virtual IDBCSBuffer* overlayWith( const char* overlay, unsigned len, unsigned pos, char padCharacter )

Replaces a specified portion of the receiver's contents with the specified string. If pos is beyond the end of the receiver's data, it is padded with the pad character (padCharacter).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
remove
public:
virtual IDBCSBuffer* remove( unsigned startPos, unsigned numChars )

Deletes the specified portion of the string (that is, the substring) from the receiver. You can use this function to truncate an IString object at a specific position. For example:

aString.remove(8);
removes the substring beginning at index 8 and takes the rest of the string as a default.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
reverse
public:
virtual IDBCSBuffer* reverse()

Reverses the receiver's contents.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
rightJustify
public:
virtual IDBCSBuffer* rightJustify( unsigned newLen, char padCharacter )

Right-justifies the receiver in a string of the specified length. If the receiver's data is shorter than the requested length (length), it is padded on the left with the pad character (padCharacter). The default pad character is a blank.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
strip

Strips both the leading and trailing character or characters. You can specify the character or characters as the following:

The default is white space.


Overload 1
public:
virtual IDBCSBuffer* strip( const char* pChars, unsigned len, IStringEnum::StripMode mode )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IDBCSBuffer* strip( const IStringTest& aTest, IStringEnum::StripMode mode )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
translate
public:
virtual IDBCSBuffer* translate( const char* pInputChars, unsigned inputLen, const char* pOutputChars, unsigned outputLen, char padCharacter )

Converts all of the receiver's characters that are in the first specified string to the corresponding character in the second specified string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
upperCase
public:
virtual IDBCSBuffer* upperCase()

Translates all lowercase letters in the receiver to uppercase.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


NLS Testing

Use these members to reimplement the following IString versions of IBuffer members. The corresponding IString members use these members to test the buffer's contents. These tests are character-set-specific.


[view class]
includesDBCS
public:
virtual bool includesDBCS() const

If any characters are DBCS (double-byte character set), true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
includesMBCS
public:
virtual bool includesMBCS() const

If any characters are MBCS (multiple-byte character set), true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
includesSBCS
public:
virtual bool includesSBCS() const

If any characters are SBCS (single-byte character set), true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isDBCS
public:
virtual bool isDBCS() const

If all the characters are DBCS, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isMBCS
public:
virtual bool isMBCS() const

If all the characters are MBCS, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isSBCS
public:
virtual bool isSBCS() const

If all the characters are SBCS, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isValidDBCS
public:
virtual bool isValidDBCS() const

If no DBCS characters have a 0 second byte, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isValidMBCS
public:
virtual bool isValidMBCS() const

If no MBCS characters have a 0 second byte, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Protected Queries

These members help implement this class.


[view class]
charLength

Returns the number of bytes in the character beginning at the specified offset.


Overload 1
protected:
size_t charLength(unsigned pos) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
static size_t charLength(char const* pChar)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
protected:
static size_t charLength( char const* pChar, mbstate_t* pMBState )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
protected:
size_t charLength(unsigned pos, mbstate_t* pMBState) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
className
protected:
const char* className() const

Returns the name of the class (IDBCSBuffer).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
maxCharLength
protected:
static size_t maxCharLength()

Returns the maximum number of bytes in a multiple-byte character. This is a static function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
prevCharLength

Returns the number of bytes in the preceding character to the one at the specified offset.


Overload 1
protected:
size_t prevCharLength( unsigned pos, mbstate_t* pMBState ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
size_t prevCharLength(unsigned pos) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Protected Testing

These members help implement this class.


[view class]
isCharValid
protected:
bool isCharValid( unsigned pos, const char* pValidChars, unsigned numValidChars ) const

If the character at the specified index is in the set of valid characters, true is returned.

The parameters are the following:

pos
The position in the receiver's buffer for the validity check.


Attention: It is important that this position not be the second byte of a DBCS character. If it is, you might get false results.

pValidChars
The string of the valid characters. It can contain a mixture of DBCS and SBCS characters.
numValidChars
The size of this string of valid characters.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isDBCS1
protected:
bool isDBCS1(unsigned pos) const

If the byte at the specified offset is the first byte of DBCS, true is returned.
Note: The Open Class Library provides this function only for compatibility with prior library versions. We recommend using IDBCSBuffer::charLength to determine if the byte is part of a multiple-byte character.

Supported Platforms

Windows OS/2 AIX
No Yes No


[view class]
isPrevDBCS
protected:
bool isPrevDBCS(unsigned pos) const

If the preceding character to the one at the specified offset is a DBCS character, true is returned.
Note: The Open Class Library provides this function only for compatibility with prior library versions. We recommend using IDBCSBuffer::prevCharLength to determine if the preceding byte is part of a multiple-byte character.

Supported Platforms

Windows OS/2 AIX
No Yes No


[view class]
isSBC

If the byte pointed to by the specified character is a single-byte character, true is returned. This is a static function.


Overload 1
protected:
static bool isSBC(char const* pChar, mbstate_t* pMBState)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
static bool isSBC(char const* pChar)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Queries

Use these members to reimplement the following IString versions of IBuffer members.


[view class]
charType
public:
virtual IStringEnum::CharType charType( unsigned index ) const

Returns the type of a character at the specified index.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
next

Returns a pointer to the next character, not the next byte, in the buffer.


Overload 1
public:
virtual const char* next(const char* prev) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual char* next(const char* prev)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Search Initialization

These members initialize search data.


[view class]
startBackwardsSearch
protected:
virtual unsigned startBackwardsSearch( unsigned startPos, unsigned searchLen ) const

Initializes a search of type IString::lastIndexOf following these criteria:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
startSearch
protected:
virtual unsigned startSearch( unsigned startPos, unsigned searchLen ) const

Initializes a search of type IString::indexOf following these criteria:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Searches

Use these members to reimplement the following IString versions of IBuffer search members.


[view class]
indexOf

Returns the byte index of the first occurrence of the specified string within the receiver. If there are no occurrences, 0 is returned.


Overload 1
public:
virtual unsigned indexOf( const IStringTest& aTest, unsigned startPos = 1 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual unsigned indexOf( const char* pString, unsigned len, unsigned startPos = 1 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
indexOfAnyBut

Returns the index of the first character of the receiver that is not in the specified set of characters. If there are no characters, 0 is returned. Alternatively, this function returns the index of the first character that fails the test prescribed by a specified IStringTest object.


Overload 1
public:
virtual unsigned indexOfAnyBut( const char* pString, unsigned len, unsigned startPos = 1 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual unsigned indexOfAnyBut( const IStringTest& aTest, unsigned startPos = 1 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
indexOfAnyOf

Returns the index of the first character of the receiver that is a character in the specified set of characters. If there are no characters, 0 is returned. Alternatively, this function returns the index of the first character that passes the test prescribed by a specified IStringTest object.


Overload 1
public:
virtual unsigned indexOfAnyOf( const char* pString, unsigned len, unsigned startPos = 1 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual unsigned indexOfAnyOf( const IStringTest& aTest, unsigned startPos = 1 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
lastIndexOf

Returns the index of the last occurrence of the specified string or character. The search starts at the position specified by startPos (inclusive) and proceeds backward. The returned value is in the range 0 <= x <= startPos. The default of 0 starts the search at the end of the receiver's string. If the search target is not found, 0 is returned.

If you specify 0 or 1 for startPos, this function returns 0 indicating the search target was not found.


Overload 1
public:
virtual unsigned lastIndexOf( const IStringTest& aTest, unsigned startPos = 1 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual unsigned lastIndexOf( const char* pString, unsigned len, unsigned startPos = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
lastIndexOfAnyBut

Returns the index of the last character not in the specified string or character. The search starts at the position specified by startPos (inclusive) and proceeds backward. The default of 0 starts the search at the end of the receiver's string. If the search target is not found, 0 is returned.

If you specify 0 for startPos, this function returns 0 indicating the search target was not found.


Overload 1
public:
virtual unsigned lastIndexOfAnyBut( const char* pString, unsigned len, unsigned startPos = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual unsigned lastIndexOfAnyBut( const IStringTest& aTest, unsigned startPos = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
lastIndexOfAnyOf

Returns the index of the last character in the specified string or character. The search starts at the position specified by startPos (inclusive) and proceeds backward. The default of 0 starts the search at the end of the receiver's string. If the search target is not found, 0 is returned.

If you specify 0 or 1 for startPos, this function returns 0 indicating the search target was not found.


Overload 1
public:
virtual unsigned lastIndexOfAnyOf( const char* pString, unsigned len, unsigned startPos = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual unsigned lastIndexOfAnyOf( const IStringTest& aTest, unsigned startPos = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Subset

Use these members to reimplement the following IString versions of IBuffer subsetting members.


[view class]
subString

Returns a new IBuffer, of the same type as the previous one, containing the specified subset of characters.

The parameters are the following:

startPos
The index at which to start the substring. If startPos is 0, the function uses position 1. If startPos is beyond the end of the buffer, nothing is copied. The buffer is filled out by the specified padding character.
len
The length to copy from the buffer. If the length extends beyond the end of the buffer, only the portion up to the end is copied. The buffer is then padded. If len is 0, a reference to the NULL buffer is returned.
padCharacter
Specifies the character the function uses to pad the copied string if less than len bytes have been copied from the source buffer.


Overload 1
public:
virtual IDBCSBuffer* subString(unsigned startPos) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IDBCSBuffer* subString( unsigned startPos, unsigned len, char padCharacter ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Testing

Corresponding IString members use these members to test the buffer's contents.
Note: In the Windows environment, the Testing functions are implemented using the wide char functions of the C runtime library.

On other platforms, IDBCSBuffer inherits the Testing functions from the IBuffer class.


[view class]
isAlphabetic
public:
virtual bool isAlphabetic() const

If all the characters are in {'A'-'Z','a'-'z'}, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isAlphanumeric
public:
virtual bool isAlphanumeric() const

If all characters are in {'A'-'Z','a'-'z','0'-'9'}, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isASCII
public:
virtual bool isASCII() const

If all the characters are in {0x00-0x7F}, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isControl
public:
virtual bool isControl() const

Returns true if all the characters are control characters.

Control characters are defined by the iswcntrl() C Library function as defined in the cntrl locale source file in the cntrl class of the LC_CTYPE category of the current locale. For example, on ASCII operating systems, control characters are those in the range {0x00-0x1F,0x7F}.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isDigits
public:
virtual bool isDigits() const

If all the characters are in {'0'-'9'}, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isGraphics
public:
virtual bool isGraphics() const

Returns true if all the characters are graphics characters.

Graphics characters are printable characters excluding the space character, as defined by the iswgraph() C Library function in the graph locale source file and in the graph class of the LC_CTYPE category of the current locale. For example, on ASCII operating systems, graphics characters are those in the range {0x21-0x7E}.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isHexDigits
public:
virtual bool isHexDigits() const

If all the characters are in {'0'-'9','A'-'F','a'-'f'}, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isLowerCase
public:
virtual bool isLowerCase() const

If all the characters are in {'a'-'z'}, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isPrintable
public:
virtual bool isPrintable() const

Returns true if all the characters are printable characters.

Printable characters are defined by the iswprint() C Library function as defined in the print locale source file and in the print class of the LC_CTYPE category of the current locale. For example, on ASCII systems, printable characters are those in the range {0x20-0x7E}.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isPunctuation
public:
virtual bool isPunctuation() const

If none of the characters is white space, a control character, or an alphanumeric character, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isUpperCase
public:
virtual bool isUpperCase() const

If all the characters are in {'A'-'Z'}, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isWhiteSpace
public:
virtual bool isWhiteSpace() const

Returns true if all the characters are white-space characters.

White-space characters are defined by the iswspace() C Library function as defined in the space locale source file and in the space class of the LC_CTYPE category of the current locale. For example, on ASCII systems, printable white-space characters are those in the range {0x09-0x0D,0x20}.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IDBCSBuffer - Inherited Member Functions and Data

Inherited Public Functions

IMRefCounted
IBuffer

Inherited Public Data

Inherited Protected Functions

IBuffer
IMRefCounted

Inherited Protected Data