I0String

The I0String class provides arrays of characters. Objects of the I0String class are functionally equivalent to objects of the class IString with one major distinction: I0Strings are indexed starting at 0 instead of 1.
Note: A consequence of starting indexes at 0 is that you can no longer use the search functions as if they were boolean. For example:

a0String.indexOf( anotherString ) != a0String.includes( anotherString ).

You can freely intermix IStrings and I0Strings in a program. You can assign objects of one class values of the other type. You can pass objects of either class as parameters to functions requiring the other type.


Attention: UINT_MAX is a reserved value for I0String. If you use UINT_MAX for the startPos parameter in I0String functions, unpredictable results can occur.


I0String - Member Functions and Data by Group

Constructors & Destructor

You can construct objects of this class in the following ways:

These constructors can throw exceptions under the following conditions:


[view class]
~I0String
public:
~I0String()
Delete the string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
I0String
You can construct objects of this class in the following ways:

These constructors can throw exceptions under the following conditions:


Overload 1
public:
I0String(long aLong)

Construct a string with the ASCII representation of a long numeric value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
I0String(unsigned anUnsigned)

Construct a string with the ASCII representation of an unsigned numeric value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
I0String(const IString& aString)

Construct a string with a copy of the specified IString.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
I0String(unsigned short anUnsignedShort)

Construct a string with the ASCII representation of an unsigned short numeric value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
I0String(double aDouble)

Construct a string with the ASCII representation of a double numeric value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
public:
I0String(char aChar)

Construct a string with a copy of the character. The string length is set to 1.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 7
public:
I0String(unsigned char anUnsignedChar)

Construct a string with a copy of the unsigned character. The string length is set to 1.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 8
public:
I0String(const char* pChar)

Construct a string with a copy of the specified ASCIIZ string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 9
public:
I0String(signed char aSignedChar)

Construct a string with a copy of the signed character. The string length is set to 1.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 10
public:
I0String(unsigned long anUnsignedLong)

Construct a string with the ASCII representation of an unsigned long numeric value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 11
public:
I0String( const void* pBuffer1, unsigned lenBuffer1, char padCharacter = ' ' )

Construct a string with contents from one buffer of arbitrary data (void*).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 12
public:
I0String( const void* pBuffer1, unsigned lenBuffer1, const void* pBuffer2, unsigned lenBuffer2, char padCharacter = ' ' )

Construct a string with contents from two buffers of arbitrary data (void*).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 13
public:
I0String( const void* pBuffer1, unsigned lenBuffer1, const void* pBuffer2, unsigned lenBuffer2, const void* pBuffer3, unsigned lenBuffer3, char padCharacter = ' ' )

Construct a string with contents from three buffers of arbitrary data (void*).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 14
public:
I0String(unsigned long long anUnsignedLongLong)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 15
public:
I0String(long long aLongLong)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 16
public:
I0String(const unsigned char* pUnsignedChar)

Construct a string with a copy of the specified unsigned ASCIIZ string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 17
public:
I0String(const signed char* pSignedChar)

Construct a string with a copy of the specified signed ASCIIZ string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 18
public:
I0String(short aShort)

Construct a string with the ASCII representation of a short numeric value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 19
public:
I0String(int anInt)

Construct a string with the ASCII representation of an integer numeric value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 20
public:
I0String()

Construct a NULL string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Editing

These members are reimplemented to treat the position arguments as 0-based.


[view class]
change

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:

inputString
The pattern string as a reference to an object of type IString. The library searches for the pattern string within the receiver's data.
pInputString
The pattern string as a NULL-terminated string. The library searches for the pattern string within the receiver's data.
outputString
The replacement string as a reference to an object of type IString. It replaces the occurrences of the pattern string in the receiver's data.
pOutputString
The replacement string as a NULL-terminated string. It replaces the occurrences of the pattern string in the receiver's data.
startPos
The position to start the search at within the receiver's data. The default is 0.
numChanges
The number of patterns to search for and change. The default is UINT_MAX, which causes changes to all occurrences of the pattern.


Overload 1
public:
I0String& change( const char* pPattern, const char* pReplacement, unsigned startPos = 0, unsigned numChanges = ( unsigned ) UINT_MAX )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
I0String& change( const IString& aPattern, const IString& aReplacement, unsigned startPos = 0, unsigned numChanges = ( unsigned ) UINT_MAX )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
static I0String change( const IString& aString, const IString& inputString, const IString& outputString, unsigned startPos = 0, unsigned numChanges = ( unsigned ) UINT_MAX )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
static I0String change( const IString& aString, const char* pInputString, const char* pOutputString, unsigned startPos = 0, unsigned numChanges = ( unsigned ) UINT_MAX )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
static I0String change( const IString& aString, const IString& inputString, const char* pOutputString, unsigned startPos = 0, unsigned numChanges = ( unsigned ) UINT_MAX )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
public:
static I0String change( const IString& aString, const char* pInputString, const IString& outputString, unsigned startPos = 0, unsigned numChanges = ( unsigned ) UINT_MAX )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 7
public:
I0String& change( const char* pPattern, const IString& aReplacement, unsigned startPos = 0, unsigned numChanges = ( unsigned ) UINT_MAX )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 8
public:
I0String& change( const IString& aPattern, const char* pReplacement, unsigned startPos = 0, unsigned numChanges = ( unsigned ) UINT_MAX )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
insert

Inserts the specified string at the specified location.


Overload 1
public:
static I0String insert( const IString& aString, const char* pInsert, unsigned index = ( unsigned ) UINT_MAX, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
I0String& insert( const IString& aString, unsigned index = ( unsigned ) UINT_MAX, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
I0String& insert( const char* pString, unsigned index = ( unsigned ) UINT_MAX, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
static I0String insert( const IString& aString, const IString& anInsert, unsigned index = ( unsigned ) UINT_MAX, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
overlayWith

Replaces a specified portion of the receiver's contents with the specified string. The overlay starts in the receiver's data at the index, which defaults to 0. If index is beyond the end of the receiver's data, it is padded with the pad character (padCharacter).


Overload 1
public:
I0String& overlayWith( const char* pString, unsigned index = 0, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
static I0String overlayWith( const IString& aString, const IString& anOverlay, unsigned index = 0, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
I0String& overlayWith( const IString& aString, unsigned index = 0, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
static I0String overlayWith( const IString& aString, const char* pOverlay, unsigned index = 0, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
remove

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.


Overload 1
public:
static I0String remove( const IString& aString, unsigned startPos, unsigned numChars )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
I0String& remove(unsigned startPos)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
static I0String remove( const IString& aString, unsigned startPos )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
I0String& remove(unsigned startPos, unsigned numChars)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Forward Searches

These members are reimplemented to treat the starting position of the search as a 0-based index.


[view class]
indexOf

Returns the byte index of the first occurrence of the specified string within the receiver. If there are no occurrences, I0String::notFound is returned. In addition to IStrings, you can also specify a single character or an IStringTest.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
unsigned indexOf( const char* pString, unsigned startPos = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
unsigned indexOf( const IString& aString, unsigned startPos = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
unsigned indexOf( char aCharacter, unsigned startPos = 0 ) 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, I0String::notFound 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:
unsigned indexOfAnyBut( char validChar, unsigned startPos = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
unsigned indexOfAnyBut( const IString& aString, unsigned startPos = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
unsigned indexOfAnyBut( const char* pValidChars, unsigned startPos = 0 ) 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, I0String::notFound 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:
unsigned indexOfAnyOf( const IStringTest& aTest, unsigned startPos = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
unsigned indexOfAnyOf( const IString& searchChars, unsigned startPos = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
unsigned indexOfAnyOf( const char* pSearchChars, unsigned startPos = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
unsigned indexOfAnyOf( char searchChar, unsigned startPos = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
occurrencesOf

Returns the number of occurrences of the specified IString, char*, char, or IStringTest. If you just want a boolean test, this is slower than IString::indexOf.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
unsigned occurrencesOf( char aCharacter, unsigned startPos = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
unsigned occurrencesOf( const char* pString, unsigned startPos = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
unsigned occurrencesOf( const IString& aString, unsigned startPos = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
notFound
public:
static const unsigned notFound

You use this static constant in conjunction with the searching functions. It specifies the value searching functions return indicating the search failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Index Mapping

Use these members to convert arguments and results to the proper index base: 1 for arguments (because it relies on IString) and 0 for results (because it is 0-based itself).


[view class]
adjustArg

Adjusts the specified index from 0- to 1-based.


Overload 1
protected:
static signed adjustArg(signed index)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
static unsigned adjustArg(unsigned index)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
adjustResult

Adjusts a function result from 1- to 0-based.


Overload 1
protected:
static signed adjustResult(signed index)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
static unsigned adjustResult(unsigned index)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Queries

These members are overridden to permit specification of the index as a 0-based value.


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

Returns the type of the character at the specified index.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator []

Returns a reference to the specified character of the string.
Note: If you call the non-const version of this function with an index beyond the end, the function extends the string.


Overload 1
public:
const char& operator [](signed long index) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
char& operator [](signed index)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
char& operator [](unsigned long index)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
const char& operator [](signed index) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
const char& operator [](unsigned long index) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
public:
char& operator [](signed long index)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 7
public:
const char& operator [](unsigned index) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 8
public:
char& operator [](unsigned index)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
subString

Returns the specified portion of the string (that is, the substring) of the receiver.

The parameters are the following:

startPos
The starting position of the substring being extracted. If this position is beyond the end of the data in the receiver, this function returns a NULL IString.
length
The length of the substring to be extracted. If the length extends beyond the end of the receiver's data, the returned IString is padded to the specified length with padCharacter. If you do not specify length and it defaults, this function uses the rest of the receiver's data starting from startPos for padding.
padCharacter
The character the function uses as padding if the requested length extends beyond the end of the receiver's data. The default padCharacter is a blank.
You can use this function to truncate an IString object at a specific position. For example:
aString = aString.subString(0, 7);
returns the substring concluding with index 7 and discards the rest of the string.


Overload 1
public:
I0String subString(unsigned startPos) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
I0String subString( unsigned startPos, unsigned len, char padCharacter = ' ' ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Reverse Searches

These members permit searching the string in various ways. The lastIndexOf versions correspond to forward search indexOf members but start the search from the end of the string. These members return the index of the last character in the receiver IString that satisfies the search criteria. Also, they accept an optional argument that specifies where the search is to begin. The default is to start searching at the end of the string. Searching proceeds from right to left for these members.


[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 or I0String::notFound. The default of UINT_MAX-1 starts the search at the end of the receiver's string. If the search target is not found, I0String::notFound is returned.

If you specify 0 for startPos, the search starts at the beginning of the string. Therefore, because the search proceeds backward from its starting position, in this case the search target must occur at the beginning of the string for it to be found.


Overload 1
public:
unsigned lastIndexOf( const char* pString, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 ) ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
unsigned lastIndexOf( const IStringTest& aTest, unsigned startPos = ( unsigned ) ( UINT_MAX - 1 ) ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
unsigned lastIndexOf( char aCharacter, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 ) ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
unsigned lastIndexOf( const IString& aString, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 ) ) 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 UINT_MAX-1 starts the search at the end of the receiver's string. If the search target is not found, I0String::notFound is returned.

If you specify 0 for startPos, the search starts at the beginning of the string. Therefore, because the search proceeds backward from its starting position, in this case the search target must occur at the beginning of the string for it to be found.


Overload 1
public:
unsigned lastIndexOfAnyBut( const IStringTest& aTest, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 ) ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
unsigned lastIndexOfAnyBut( const IString& validChars, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 ) ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
unsigned lastIndexOfAnyBut( const char* pValidChars, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 ) ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
unsigned lastIndexOfAnyBut( char validChar, unsigned startPos = ( unsigned ) ( UINT_MAX - 1 ) ) 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 UINT_MAX-1 starts the search at the end of the receiver's string. If the search target is not found, I0String::notFound is returned.

If you specify 0 for startPos, the search starts at the beginning of the string. Therefore, because the search proceeds backward from its starting position, in this case the search target must occur at the beginning of the string for it to be found.


Overload 1
public:
unsigned lastIndexOfAnyOf( char searchChar, unsigned startPos = ( unsigned ) ( UINT_MAX - 1 ) ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
unsigned lastIndexOfAnyOf( const char* pSearchChars, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 ) ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
unsigned lastIndexOfAnyOf( const IStringTest& aTest, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 ) ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
unsigned lastIndexOfAnyOf( const IString& searchChars, unsigned endPos = ( unsigned ) ( UINT_MAX - 1 ) ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Word Operations

These members are reimplemented to treat the result index as 0-based.


[view class]
indexOfPhrase
public:
unsigned indexOfPhrase( const IString& wordString, unsigned startWord = 1 ) const

Returns the position of the first occurrence of the specified phrase in the receiver. If the phrase is not found, I0String::notFound is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
indexOfWord
public:
unsigned indexOfWord(unsigned wordNumber) const

Returns the index of the specified white-space-delimited word in the receiver. If the word is not found, I0String::notFound is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


I0String - Inherited Member Functions and Data

Inherited Public Functions

IString

Inherited Public Data

Inherited Protected Functions

IString

Inherited Protected Data

IString