IBuffer

The IBuffer class defines the contents of an IString.


IBuffer - Member Functions and Data by Group

Constructors & Destructor

Construct and destructor IBuffer objects.


[view class]
~IBuffer
protected:
virtual ~IBuffer()
Does nothing at this time.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IBuffer
protected:
IBuffer(unsigned newLen)
Constructors a new buffer object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Allocation

Use these protected members to allocate and deallocate IBuffer objects.


[view class]
allocate
protected:
virtual IBuffer* allocate(unsigned bufLength) const
Returns a new buffer of the specified length.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator delete
Deallocates a buffer.


Overload 1
protected:
void operator delete( void* p, const char* filename, size_t linenum )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
void operator delete(void* p)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator new
Allocates space for a buffer of the specified length. The returned pointer is an area the size of an IBuffer large enough to hold data of size bufLen.


Overload 1
protected:
void* operator new(size_t t, unsigned bufLen)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
void* operator new( size_t t, const char* filename, size_t linenum, unsigned bufLen )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Comparisons

Use these members to compare the IBuffer'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


Diagnostics

Use these members to provide diagnostic information about the buffer.


[view class]
asDebugInfo
public:
virtual IString asDebugInfo() const
Returns information about the buffer's internal representation that you can use for debugging.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Editing

These members are called by the corresponding IString members to edit the buffer's contents.


[view class]
center
public:
virtual IBuffer* 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 IBuffer* 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]
copy
public:
virtual IBuffer* copy(unsigned numCopies)
Replaces the receiver's contents with a specified number of replications of itself.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
insert
public:
virtual IBuffer* 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 IBuffer* leftJustify( unsigned newLen, char padCharacter )
Left-justifies the receiver in a string of the specified length. If the new length (newLen) 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 IBuffer* lowerCase()
Translates all uppercase letters in the receiver to lowercase.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
overlayWith
public:
virtual IBuffer* 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 IBuffer* 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:

:xmp scale='0.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 IBuffer* reverse()
Reverses the receiver's contents.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
rightJustify
public:
virtual IBuffer* 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 (newLen), 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 IBuffer* strip( const IStringTest& aTest, IStringEnum::StripMode mode )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
translate
public:
virtual IBuffer* 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 IBuffer* upperCase()
Translates all lowercase letters in the receiver to uppercase.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Implementation

This member helps implement this class.


[view class]
initialize
protected:
static IBuffer* initialize()
Initializes the IBuffer object (sets up a NULL buffer, a DBCS table, and so forth).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


NLS Testing

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

This member helps implement this class.


[view class]
className
protected:
virtual const char* className() const
Returns the name of the class (IBuffer).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Queries

Use these members to access various attributes of a buffer.


[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]
contents
Returns the address of the buffer's contents.


Overload 1
public:
const char* contents() const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
char* contents()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
defaultBuffer
public:
static IBuffer* defaultBuffer()
Returns the address of the NULL buffer for the class. This is a static function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
fromContents
public:
static IBuffer* fromContents(const char* pBuffer)
Returns the address of IBuffer using the specified pointer to its contents. This is a static function.


Note: It is important that pBuffer point to the actual beginning of data from an IBuffer object. The Open Class Library can return only values from the contents function of this class. Otherwise, if the returned IBuffer pointer is used, errors could occur.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
length
public:
unsigned length() const
Returns the length of the buffer's contents.

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 char* next(const char* prev)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
null
public:
IBuffer* null() const
Returns the address of the NULL buffer.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
useCount
public:
unsigned useCount() const
Returns the number of IStrings referring to the buffer.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Reallocation

Use these members to manage reallocation of IBuffers when strings' contents are modified.


[view class]
checkAddition
public:
static unsigned checkAddition( unsigned addend1, unsigned addend2 )
Verifies that the two parameters, when added, do not overflow an unsigned integer.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
checkMultiplication
public:
static unsigned checkMultiplication( unsigned factor1, unsigned factor2 )
Verifies that the two parameters, when multiplied, do not overflow an unsigned integer.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
newBuffer
public:
IBuffer* newBuffer( const void* p1, unsigned len1, const void* p2 = 0, unsigned len2 = 0, const void* p3 = 0, unsigned len3 = 0, char padChar = 0 ) const
Allocates a new buffer and initializes it with the contents of up to three specified buffers.

The parameters are the following:

p1
The pointer to the first part to be copied into the data area of the new buffer. The first part is len1 bytes long. If the pointer is NULL, the padChar is copied for len1 bytes.
len1
The length, in bytes, of the first part to be copied into the new buffer.
p2
A pointer to the second part, immediately following the first part, to be copied into the data area of the new buffer. The second part is len2 bytes long. If the pointer is NULL, the padChar is copied for len2 bytes. If nothing is specified for p2, it is NULL.
len2
The length, in bytes, of the second part to be copied into the new buffer. If nothing is specified for len2, it defaults to 0 bytes.
p3
The pointer to the third part, immediately following the second part, to be copied into the data area of the new buffer. The third part is len3 bytes long. If the pointer is NULL, the padChar is copied for len3 bytes. If nothing is specified for p3, it is NULL.
len3
The length, in bytes, of the third part to be copied into the new buffer. If nothing is specified for len3, it defaults to 0 bytes.
padChar
The character to use as the pad in the cases of p1, p2, or p3 being NULL. If you do not specify a padChar, it defaults to the character 0.


Note: If the sum of len1, len2, and len3 is 0, a reference to the NULL buffer for this class is added and the address is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
overflow
public:
static unsigned overflow()
Throws an exception when IBuffer::checkAddition or IBuffer::checkMultiplication detects an overflow.

Exception

IInvalidRequest You made an IBuffer request causing an overflow. Typically, this occurs during object construction or during an operation that grows an underlying IBuffer object. Likely culprits might be an IBuffer::newBuffer or IString::change call.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultBuffer
public:
static void setDefaultBuffer(IBuffer* newDefaultBuffer)
Sets the default (NULL) buffer. The specified buffer must be comprised of a single NULL byte.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Search Initialization

These members help implement this class.


[view class]
startBackwardsSearch
protected:
virtual unsigned startBackwardsSearch( unsigned startPos, unsigned searchLen ) const
Initializes a search of type IString::lastIndexOf using the following 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 using the following criteria:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Searches

These members are called by the corresponding IString members to search the buffer's contents.


[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 char* pString, unsigned len, unsigned startPos = 1 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual unsigned indexOf( const IStringTest& aTest, 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 for startPos, this function returns 0 indicating the search target was not found.


Overload 1
public:
virtual unsigned lastIndexOf( const IStringTest& aTest, unsigned startPos = 0 ) 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 IStringTest& aTest, unsigned startPos = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual unsigned lastIndexOfAnyBut( const char* pString, unsigned len, 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 for startPos, this function returns 0 indicating the search target was not found.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Subset

Use this member when a subset of characters is required.


[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 IBuffer* subString(unsigned startPos) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IBuffer* 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.


[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 the 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

Control characters are defined by the iscntrl() C Library function as defined in the cntrl locale source file and 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 isgraph() 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 isprint() 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 isspace() 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, white-space characters are those in the range {0x09-0x0D,0x20}.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isDBCSLead
protected:
static bool isDBCSLead(char inByte)
If the input character is the first byte of a DBCS character, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


IBuffer - Type Definitions


[view class]
Comparison
typedef enum { equal , greaterThan , lessThan } Comparison

These enumerators specify the possible valid return codes from IBuffer::compare.

equal
The buffer's contents are equal to the contents of the specified character array.
greaterThan
The buffer's contents are greater than the contents of the specified character array.
lessThan
The buffer's contents are less than the contents of the specified character array.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IBuffer - Inherited Member Functions and Data

Inherited Public Functions

IMRefCounted

Inherited Public Data

Inherited Protected Functions

IMRefCounted

Inherited Protected Data