IString

The IString class provides arrays of characters. These objects are functionally equivalent to objects of the class I0String with one major distinction: IStrings are indexed starting at 1 instead of 0. (Note that if you use an index of zero as a starting position in an IString member function, this index value is automatically converted to an index of 1.)

IString provides an operator char*. To access the actual string contained in an object of type IString, cast the assignment variable implicitly or explicitly. IString is null-terminated so that it can be cast to a char* safely. However, the terminating null is not counted in its length, and the IString can still have embedded nulls. When cast to a char*, the string is truncated at the first null encountered.

IString member functions provide the following functions beyond that available from the standard C char* arrays and the STRING.H library functions:

When a program using IString objects is run on a DBCS system, the IString objects support DBCS characters within the string contents. The various IString search functions do not accidentally match an SBCS character with the second byte of a DBCS character that has the same value. Also, IString functions that modify IString objects, such as subString, remove, and translate, never separate the two bytes of a DBCS character. If one of the two bytes of a DBCS character is removed, the remaining byte is replaced with the appropriate pad character (if the function performing the change has one) or a blank.

When working with IString objects that contain DBCS data, ensure that the contents are not altered in such a way as to corrupt the data. For example, the statement:

aString[ n ] = 'x';
would be in error if the nth character of the IString was the first or second byte of a DBCS character.
Note: Any function that reallocates an IString can throw an exception for out-of-range errors. These occur if you attempt to construct an IString with a length greater than UINT_MAX.

IString objects are held in IBuffer objects, which allocate the area for the character arrays using the C++ operator new. The only limitation for the size of an IString are the limitations imposed by the operating system.

AIX Considerations

DBCS is equivalent to multiple-byte character set (MBCS).

OS/2 Considerations

To obtain locale-sensitive result for many IString operations, such as comparison, searching, editing, etc., you must enable locale-based string operation by calling IString::enableInternationalization().

Windows Considerations

To obtain locale-sensitive result for many IString operations, such as comparison, searching, editing, etc., you must enable locale-based string operation by calling IString::enableInternationalization().


IString - Member Functions and Data by Group

Constructors & Destructor

Construct and destruct IString objects.


[view class]
~IString
public:
~IString()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

These constructors can throw exceptions under the following conditions:


Overload 1
public:
IString(long aLong)
Construct a string representation of a long numeric value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString(unsigned anUnsigned)
Construct a string representation of an unsigned numeric value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IString(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:
IString(unsigned short anUnsignedShort)
Construct a string representation of an unsigned short numeric value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
IString(double aDouble)
Construct a string representation of a double numeric value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
public:
IString(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:
IString(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:
IString(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:
IString(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:
IString(unsigned long anUnsignedLong)
Construct a string representation of an unsigned long numeric value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 11
public:
IString( 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:
IString( 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:
IString( 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:
IString(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 15
public:
IString(long long aLongLong)
Constructs a string representation of a long long value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 16
public:
IString(unsigned long long anUnsignedLongLong)
Constructs a string representation of an unsigned long long object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 17
public:
IString(const IString* pIString)
Constructs a string from a const string pointer.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 18
public:
IString(const IText& anIText)
Construct a string with a copy of the specified IText that is transcoded into the ISO 8859-1 (Latin1) character set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 19
public:
IString(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 20
public:
IString(short aShort)
Construct a string representation of a short numeric value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 21
public:
IString(int anInt)
Construct a string representation of an integer value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 22
public:
IString()
Construct a NULL string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Binary Conversions

These members work if isBinaryDigits() == true; if not, they return a null string. The static members by the same name can be applied to a string to return the modified string without changing the argument string.


[view class]
b2c

Converts a string of binary digits to a normal string of characters. For example, this function changes 01 to \x01 and 00110011 or 11110011 to 3.
Note: This function is not locale-sensitive.


Overload 1
public:
IString& b2c()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
static IString b2c(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
b2d
Converts a string of binary digits to a string of decimal digits. For example, this function changes 00011001 to 25 and 0001001000110100 to 4660.


Overload 1
public:
static IString b2d(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& b2d()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
b2x
Converts a string of binary digits to a string of hexadecimal digits. For example, this function changes 00011011 to 1b and 10001001000110100 to 11234.


Overload 1
public:
static IString b2x(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& b2x()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Bit Operations

Use these members to implement various public members of this class requiring bitwise operations.


[view class]
applyBitOp
protected:
IString& applyBitOp( const char* pArg, unsigned argLen, BitOperator op )

Implements the bitwise operators &, |, and ^.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Character Conversions

These members convert a string to binary, numeric, or hexadecimal representation. The static members by the same name can be applied to a string to return the modified string without changing the argument string. These members are used much like the similar REXX functions. For example:

  aString.c2b();                                         // Changes aString.
  String binaryDigits = IString::c2b( aString ); // Leaves aString alone.


[view class]
c2b

Converts a normal string of characters to a string of binary digits. For example, this function changes "a" to 01100001 and 12 to 11000100110010 or "a" to 10000001 and 12 to 1111000111110010.
Note: This function is not locale-sensitive.


Overload 1
public:
IString& c2b()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
static IString c2b(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
c2d

Converts a normal string of characters to a string of decimal digits. For example, this function changes "a" to 97 and "ab" to 24930 or "a" to 129 and "ab" to 33154.
Note: This function is not locale-sensitive.


Overload 1
public:
static IString c2d(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& c2d()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
c2x

Converts a normal string of characters to a string of hexadecimal digits. For example, this function changes "a" to 61 and "ab" to 6162 or "a" to 81 and "ab" to 8182.
Note: This function is not locale-sensitive.


Overload 1
public:
static IString c2x(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& c2x()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Diagnostics

These members provide IString diagnostic information for IString objects. Often, you use these members to write trace information when debugging.


[view class]
asDebugInfo
public:
IString asDebugInfo() const

Returns information about the IString's internal representation that you can use for debugging.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
asString
public:
IString asString() const

Returns the string itself, so that IString supports this common protocol supported by other classes in the Open Class Library.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Editing

Use these members to edit a string. All return a reference to the modified receiver. Many that are length-related, such as center and leftJustify, accept a pad character that defaults to a blank. In all cases, you can specify argument strings as either objects of the IString class or by using char*.

Static members by the same name can be applied to an IString to obtain the modified IString without affecting the argument. For example:

   aString.change('\t', '   ');                   // Changes all tabs in aString to 3 blanks.
   IString s = IString::change( aString, '\t', '   ' );  // Leaves aString as is.


[view class]
center

Centers the receiver within a string of the specified length.


Overload 1
public:
IString& center(unsigned length, char padCharacter = ' ')

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
static IString center( const IString& aString, unsigned length, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[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 1.
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:
IString& change( const IString& inputString, const IString& outputString, unsigned startPos = 1, unsigned numChanges = ( unsigned ) UINT_MAX )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& change( const IString& inputString, const char* pOutputString, unsigned startPos = 1, unsigned numChanges = ( unsigned ) UINT_MAX )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IString& change( const char* pInputString, const IString& outputString, unsigned startPos = 1, unsigned numChanges = ( unsigned ) UINT_MAX )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
public:
IString& change( const char* pInputString, const char* pOutputString, unsigned startPos = 1, unsigned numChanges = ( unsigned ) UINT_MAX )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 7
public:
static IString change( const IString& aString, const IString& inputString, const IString& outputString, unsigned startPos = 1, unsigned numChanges = ( unsigned ) UINT_MAX )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 9
protected:
IString& change( const char* pPattern, unsigned patternLen, const char* pReplacement, unsigned replacementLen, unsigned startPos, unsigned numChanges )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
copy

Replaces the receiver's contents with a specified number of replications of itself.


Overload 1
public:
IString& copy(unsigned numCopies)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
static IString copy( const IString& aString, unsigned numCopies )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
insert

Inserts the specified string after the specified location.


Overload 1
public:
IString& insert( const IString& aString, unsigned index = 0, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& insert( const char* pString, unsigned index = 0, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
static IString insert( const IString& aString, const IString& anInsert, unsigned index = 0, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
protected:
IString& insert( const char* pInsert, unsigned insertLen, unsigned startPos, char padCharacter )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
leftJustify

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.


Overload 1
public:
IString& leftJustify( unsigned length, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
static IString leftJustify( const IString& aString, unsigned length, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
lowerCase

Translates all uppercase letters in the receiver to lowercase.


Overload 1
public:
IString& lowerCase()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
static IString lowerCase(const IString& aString)

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 1. If index is beyond the end of the receiver's data, it is padded with the pad character (padCharacter).


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
static IString overlayWith( const IString& aString, const IString& anOverlay, unsigned index = 1, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
protected:
IString& overlayWith( const char* pOverlay, unsigned overlayLen, unsigned index, 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:
IString& remove(unsigned startPos, unsigned numChars)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& remove(unsigned startPos)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
reverse

Reverses the receiver's contents.


Overload 1
public:
static IString reverse(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& reverse()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
rightJustify

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.


Overload 1
public:
static IString rightJustify( const IString& aString, unsigned length, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& rightJustify( unsigned length, char padCharacter = ' ' )

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:
static IString strip( const IString& aString, const IString& aStringOfChars )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
static IString strip( const IString& aString, const IStringTest& aTest )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
static IString strip( const IString& aString, const char* pStringOfChars )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IString& strip(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
IString& strip()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
public:
IString& strip(const IStringTest& aTest)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 7
public:
IString& strip(const char* pString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 8
public:
static IString strip(const IString& aString, char aChar)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 9
public:
IString& strip(char aCharacter)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 10
protected:
IString& strip( const char* pChar, unsigned len, IStringEnum::StripMode mode )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 11
protected:
IString& strip( const IStringTest& aTest, IStringEnum::StripMode mode )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
stripBlanks
public:
static IString stripBlanks(const IString& aString)

Strips both leading and trailing white space.
Note: This function is the static version of IString::strip, which has been renamed to avoid a duplicate definition.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
stripLeading

Strips the leading character or characters.


Overload 1
public:
IString& stripLeading(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
static IString stripLeading( const IString& aString, char aChar )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IString& stripLeading(const IStringTest& aTest)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IString& stripLeading(const char* pString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
IString& stripLeading()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
public:
static IString stripLeading( const IString& aString, const IStringTest& aTest )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 7
public:
static IString stripLeading( const IString& aString, const char* pStringOfChars )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 8
public:
static IString stripLeading( const IString& aString, const IString& aStringOfChars )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 9
public:
IString& stripLeading(char aCharacter)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
stripLeadingBlanks
public:
static IString stripLeadingBlanks(const IString& aString)

Strips the leading character or characters.
Note: This function is the static version of IString::stripLeading, which has been renamed to avoid a duplicate definition.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
stripTrailing

Strips the trailing character or characters.


Overload 1
public:
IString& stripTrailing(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
static IString stripTrailing( const IString& aString, const char* pStringOfChars )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
static IString stripTrailing( const IString& aString, const IString& aStringOfChars )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IString& stripTrailing(const IStringTest& aTest)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
static IString stripTrailing( const IString& aString, const IStringTest& aTest )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
public:
static IString stripTrailing( const IString& aString, char aChar )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 7
public:
IString& stripTrailing(const char* pString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 8
public:
IString& stripTrailing(char aCharacter)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 9
public:
IString& stripTrailing()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
stripTrailingBlanks
public:
static IString stripTrailingBlanks(const IString& aString)

Strips the trailing character or characters.
Note: This function is the static version of IString::stripTrailing, which has been renamed to avoid a duplicate definition.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
translate

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


Overload 1
public:
static IString translate( const IString& aString, const IString& inputChars, const IString& outputChars, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
static IString translate( const IString& aString, const char* pInputChars, const IString& outputChars, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
static IString translate( const IString& aString, const char* pInputChars, const char* pOutputChars, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
static IString translate( const IString& aString, const IString& inputChars, const char* pOutputChars, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
IString& translate( const char* pInputChars, const char* pOutputChars, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
public:
IString& translate( const char* pInputChars, const IString& outputChars, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 7
public:
IString& translate( const IString& inputChars, const char* pOutputChars, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 8
public:
IString& translate( const IString& inputChars, const IString& outputChars, char padCharacter = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 9
protected:
IString& translate( const char* pInputChars, unsigned inputLen, const char* pOutputChars, unsigned outputLen, char padCharacter )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
upperCase

Translates all lowercase letters in the receiver to uppercase.


Overload 1
public:
IString& upperCase()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
static IString upperCase(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Forward Searches

These members support searching a string in various ways. You can specify an optional index that indicates the search start position. The default starts at the beginning of the string.


[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. In addition to IStrings, you can also specify a single character or an IStringTest.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
unsigned indexOf( const IString& aString, unsigned startPos = 1 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
unsigned indexOf( char aCharacter, unsigned startPos = 1 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
unsigned indexOfAnyBut( const char* pValidChars, unsigned startPos = 1 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
unsigned indexOfAnyBut( char validChar, unsigned startPos = 1 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
unsigned indexOfAnyBut( const IString& validChars, 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:
unsigned indexOfAnyOf( char searchChar, unsigned startPos = 1 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
protected:
unsigned occurrencesOf( const char* pSearchString, unsigned searchLen, unsigned startPos ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
findPhrase
protected:
unsigned findPhrase( const IString& aPhrase, unsigned startWord, IndexType charOrWord ) const

Locates a specified string of words for indexOfWord functions.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Hex Conversions

These members work if isHexDigits() == true; if not, they return a NULL string. The static members by the same name can be applied to a string to return the modified string without changing the argument string.


[view class]
x2b

Converts a string of hexadecimal digits to a string of binary digits. For example, this function changes a1c to 101000011100 and f3 to 11110011.


Overload 1
public:
IString& x2b()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
static IString x2b(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
x2c

Converts a string of hexadecimal digits to a normal string of characters. For example, this function changes 8 to \x08 and 31393935 to 1995. 8 to \x08 and F1F9F9F5 to 1995.
Note: This function is not locale-sensitive.


Overload 1
public:
static IString x2c(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& x2c()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
x2d

Converts a string of hexadecimal digits to a string of decimal digits. For example, this function changes a1c to 2588 and 10000 to 65536.


Overload 1
public:
static IString x2d(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& x2d()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Implementation

Use these members to implement this class; specifically, they initialize or set the underlying IBuffer data.


[view class]
initBuffer

Resets the contents from a specified buffer or buffers.


Overload 1
protected:
IString& initBuffer(unsigned long anUnsignedLong)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
IString& initBuffer( const void* p1, unsigned len1, const void* p2 = 0, unsigned len2 = 0, const void* p3 = 0, unsigned len3 = 0, char padChar = 0 )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
protected:
IString& initBuffer(double aDouble)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
protected:
IString& initBuffer(long long aLongLong)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
protected:
IString& initBuffer(unsigned long long anUnsignedLongLong)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
protected:
IString& initBuffer(long aLong)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setBuffer
protected:
IString& setBuffer(IBuffer* ibuff)

Sets the private data member to point to a new IBuffer object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Manipulation

Use these members to manipulate a string's contents. All are overloaded so that standard C strings can be used efficiently without constructing an equivalent string first.


[view class]
operator &

Performs bitwise AND. This function can handle the following three forms:

string1 & aString
Both operands are of type IString.
string1 & pString
The first operand is an IString and the second is a NULL-terminated character string.
pString & aString
The first operand is a NULL-terminated character string and the second is an IString.


Overload 1
public:
IString operator &(const char* pString) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString operator &(const IString& aString) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator &=

Performs bitwise AND and replaces the receiver. This function can handle the following two forms:

string1 &= aString
Both operands are of type IString.
string1 &= pString
The first operand is an IString and the second is a NULL-terminated character string.


Overload 1
public:
IString& operator &=(const char* pString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& operator &=(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator +

Concatenates two strings. This function can handle the following three forms:

string1 + aString
Both operands are of type IString.
string1 + pString
The first operand is an IString and the second is a NULL-terminated character string.
pString + aString
The first operand is a NULL-terminated character string and the second is an IString.


Overload 1
public:
IString operator +(const char* pString) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString operator +(const IString& aString) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator +=

Concatenates the specified string to the receiver and replaces the receiver. This function can handle the following two forms:

string1 += aString
Both operands are of type IString.
string1 += pString
The first operand is an IString and the second is a NULL-terminated character string.


Overload 1
public:
IString& operator +=(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& operator +=(const char* pString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator =
public:
IString& operator =(const IString& aString)

Replaces the contents of the string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator ^

Performs bitwise XOR. This function can handle the following three forms:

string1 ^ aString
Both operands are of type IString.
string1 ^ pString
The first operand is an IString and the second is a NULL-terminated character string.
pString ^ aString
The first operand is a NULL-terminated character string and the second is an IString.


Overload 1
public:
IString operator ^(const char* pString) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString operator ^(const IString& aString) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator ^=

Performs bitwise XOR and replaces the receiver. This function can handle the following two forms:

string1 ^= aString
Both operands are of type IString.
string1 ^= pString
The first operand is an IString and the second is a NULL-terminated character string.


Overload 1
public:
IString& operator ^=(const char* pString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& operator ^=(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator |

Performs bitwise OR. This function can handle the following three forms:

string1 | aString
Both operands are of type IString.
string1 | pString
The first operand is an IString and the second is a NULL-terminated character string.
pString | aString
The first operand is a NULL-terminated character string and the second is an IString.


Overload 1
public:
IString operator |(const IString& aString) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString operator |(const char* pString) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator |=

Performs bitwise OR and replaces the receiver with the resulting string. This function can handle the following two forms:

string1 |= aString
Both operands are of type IString.
string1 |= pString
The first operand is an IString and the second is a NULL-terminated character string.


Overload 1
public:
IString& operator |=(const char* pString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& operator |=(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator ~
public:
IString operator ~() const

Returns the string's bitwise negation (the string's complement).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


NLS Testing

Use these members to test the characters that comprise a string. Basically, you use these members to determine if an IString contains only characters from a specific NLS character set (SBCS, MBCS, DBCS).


[view class]
disableInternationalization
public:
static void disableInternationalization()

Disables locale-based string operations.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
enableInternationalization
public:
static void enableInternationalization(bool enable = true)

Enables locale-based string operations.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

If any characters are DBCS (double-byte character set), true is returned.
Note: This function is interchangeable with includesMBCS.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

If any characters are MBCS (multiple-byte character set), true is returned.
Note: This function is interchangeable with includesDBCS.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
includesSBCS
public:
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:
bool isDBCS() const

If all the characters are DBCS, true is returned.
Note: This function is interchangeable with isMBCS.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isInternationalized
public:
static bool isInternationalized()

Determines if locale-based string operation is in effect.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

If all the characters are MBCS, true is returned.
Note: This function is interchangeable with isDBCS.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isSBCS
public:
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:
bool isValidDBCS() const

If no DBCS characters have a second byte of 0, true is returned.
Note: This function is interchangeable with isValidMBCS.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

If no MBCS characters have a second byte of 0, true is returned.
Note: This function is interchangeable with isValidDBCS.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Numeric Conversions

These members work if isDigits() == true; if not, they return a NULL string. The static members by the same name can be applied to a string to return the modified string without changing the argument string.


[view class]
d2b

Converts a string of decimal digits to a string of binary digits. This function builds the string eight bits at a time. For example,

  '12' gets converted to '00001100'
  '17' gets converted to '00010001'  
  '123' gets converted to '01111011'
 
Use stripLeading('0') to strip the leading zeros.


Overload 1
public:
IString& d2b()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
static IString d2b(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
d2c

Converts a string of decimal digits to a normal string of characters. For example, this function changes 12 to \x0c and 56 to 8. 12 to \x0c and 248 to 8.
Note: This function is not locale-sensitive.


Overload 1
public:
static IString d2c(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& d2c()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
d2x

Converts a string of decimal digits to a string of hexadecimal digits. For example, this function changes 12 to c and 123 to 7b.


Overload 1
public:
static IString d2x(const IString& aString)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& d2x()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Pattern Matching

Use these members to determine if an object of this class contains a given pattern of characters.


[view class]
includes

If the receiver contains the specified search string, true is returned.


Overload 1
public:
bool includes(const IString& aString) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
bool includes(const char* pString) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
bool includes(const IStringTest& aTest) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
bool includes(char aChar) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isAbbreviationFor

If the receiver is a valid abbreviation of the specified string, true is returned.

The parameters are the following:

fullString
The full string for the abbreviation check is contained in another IString.
pFullString
The full string for the abbreviation check is a NULL-terminated character string.
minAbbrevLength
The minimum length to match for it to be a valid abbreviation. The default minimum length is 0, which means the minimum length is the length of the receiver's string.


Overload 1
public:
bool isAbbreviationFor( const IString& fullString, unsigned minAbbrevLength = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
bool isAbbreviationFor( const char* pFullString, unsigned minAbbrevLength = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isLike

If the receiver matches the specified pattern, which can contain global (or wildcard) characters, true is returned. (isLike does not guarantee to return correct result for comparison between SBCS and DBCS characters.)


Overload 1
public:
bool isLike( const IString& aPattern, char zeroOrMore = ' * ', char anyChar = '?' ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
bool isLike( const char* pPattern, char zeroOrMore = ' * ', char anyChar = '?' ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
protected:
bool isLike( const char* pPattern, unsigned patternLen, char zeroOrMore, char anyChar ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Queries

Use these members to access general information about the string.


[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]
length
public:
unsigned length() const

Returns the length of the string, not counting the terminating NULL character.

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:
char& operator [](unsigned index)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Exception

IInvalidRequest Passed an index larger than the string size. Possible causes include boundary errors and using this function instead of the non-const version, which grows the underlying IString buffer to accommodate the index value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
const char& operator [](unsigned 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 [](signed index) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
size
public:
unsigned size() const

Returns the length of the string, not counting the terminating NULL character.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
subString

Returns a 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(1, 7);
returns the substring concluding with index 7 and discards the rest of the string.


Overload 1
public:
IString subString( unsigned startPos, unsigned length, char padCharacter = ' ' ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString subString(unsigned startPos) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
buffer
protected:
IBuffer* buffer() const

Returns the address of the IBuffer referred to by this IString.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the address of the contents of the IString.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
defaultBuffer
protected:
static char* defaultBuffer()

Returns a pointer to the contents of the nullBuffer data member.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
lengthOf
protected:
static unsigned lengthOf(const char* pChar)

Returns the length of a C character array.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
nullBuf
protected:
static const char* nullBuf()

Return the value of nullBuffer.

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

If you specify 1 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 IString& aString, unsigned startPos = ( unsigned ) UINT_MAX ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
unsigned lastIndexOf( char aCharacter, unsigned startPos = ( unsigned ) UINT_MAX ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
unsigned lastIndexOf( const char* pString, unsigned startPos = ( unsigned ) UINT_MAX ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
unsigned lastIndexOf( const IStringTest& aTest, unsigned startPos = ( unsigned ) UINT_MAX ) 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 starts the search at the end of the receiver's string. If the search target is not found, 0 is returned.

If you specify 1 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 startPos = ( unsigned ) UINT_MAX ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
unsigned lastIndexOfAnyBut( const IString& validChars, unsigned startPos = ( unsigned ) UINT_MAX ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
unsigned lastIndexOfAnyBut( const char* pValidChars, unsigned startPos = ( unsigned ) UINT_MAX ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

If you specify 1 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( const IString& searchChars, unsigned startPos = ( unsigned ) UINT_MAX ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
unsigned lastIndexOfAnyOf( const char* pSearchChars, unsigned startPos = ( unsigned ) UINT_MAX ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Stream Input

Use these members to read IStrings from standard C++ streams.


[view class]
lineFrom
public:
static IString lineFrom( istream& aStream, char delim = '\n' )

Returns the next line from the specified input stream. This static function accepts an optional line delimiter, which defaults to \n. The resulting IString contains the characters up to the next occurrence of the delimiter. The delimiter character is skipped. If an EOF condition occurs, this function returns an IString whose contents are NULL.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Streaming Support

These methods supoprt binary and test mode streaming of strings.


[view class]
operator <<=
public:
void operator <<=(IDataStream& fromWhere)
Streams this string object in from the passed data stream.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator >>=
public:
void operator >>=(IDataStream& toWhere)
Streams this string object out ot the passed data stream.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
readFromStream
protected:
void readFromStream(IDataStream& fromWhere)
Support method for streaming in of string ojbects from data streams.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
writeToStream
protected:
void writeToStream(IDataStream& toWhere) const
Support method for streaming out of string objects to data streams.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Testing

Use these members to determine if an IString contains only characters from a predefined set.


[view class]
isAlphabetic
public:
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:
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:
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]
isBinaryDigits
public:
bool isBinaryDigits() const

If all the characters are either 0 or 1, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns true if all the characters are control characters. Control characters are determined using the iscntrl() C Library function 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:
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:
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. On ASCII systems, for example, graphics characters are those in the range {0x21-0x7E}.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isHexDigits
public:
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:
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:
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. On ASCII systems, for example, printable characters are those in the range {0x20-0x7E}.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isPunctuation
public:
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:
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:
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]
isAbbrevFor
protected:
bool isAbbrevFor( const char* pFullString, unsigned fullLen, unsigned minLen ) const

If the receiver is a valid abbreviation of the specified string, true is returned.

The parameters are the following:

pFullString
The full string for the abbreviation check. The string can be either a NULL-terminated character string or not.
fullLen
The full length of the specified pFullString minus the null terminator.
minLen
The minimum length to match for it to be a valid abbreviation. If you specify 0, the minimum length is the length of the receiver's string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Type Conversions

Use these members to convert a string to various other data types. The types supported are the same set as are supported by the IString constructors.


[view class]
asDouble
public:
double asDouble() const

Returns, as a double, the number that the string represents.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
asInt
public:
long asInt() const

Returns the number that the string represents as a long integer.
Note: If an IString contains nonnumeric characters, this function returns the integer for the portion of the IString up to, but not including, the nonnumeric character. The rest of the IString, following the invalid character, is not returned.

If an IString is larger than the maximum integer, this function returns the maximum integer, not the larger value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
asLongLong
public:
long long asLongLong() const

Returns the number that the string represents as a long long integer.
Note: If an IString contains nonnumeric characters, this function returns the integer for the portion of the IString up to, but not including, the nonnumeric character. The rest of the IString, following the invalid character, is not returned.

If an IString is larger than the maximum long long, this function returns the maximum long long, not the larger value.

This function only exist on platforms with long long support.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
asUnsigned
public:
unsigned long asUnsigned() const

Returns, as an unsigned long, the integer that the string represents.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
asUnsignedLongLong
public:
unsigned long long asUnsignedLongLong() const

Returns, as an unsigned long long, the long long that the string represents.
Note: This member function only exist on platforms with long long support.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator char *
public:
operator char *() const

Returns a char* pointer to the string's contents. IString is null-terminated so that it can be cast to a char* safely. However, the terminating null is not counted in its length, and the IString can still have embedded nulls. When cast to a char*, the string is truncated at the first null encountered.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator signed char *
public:
operator signed char *() const

Returns a signed char* pointer to the string's contents. IString is null-terminated so that it can be cast to a char* safely. However, the terminating null is not counted in its length, and the IString can still have embedded nulls. When cast to a char*, the string is truncated at the first null encountered.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator unsigned char *
public:
operator unsigned char *() const

Returns an unsigned char* pointer to the string's contents. IString is null-terminated so that it can be cast to a char* safely. However, the terminating null is not counted in its length, and the IString can still have embedded nulls. When cast to a char*, the string is truncated at the first null encountered.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Utility Data

These protected static data members provide useful values for implementing IString. IString uses the various representation of NULL and zero for initialization and comparison purposes.


[view class]
maxLong
protected:
static const char * const maxLong

The maximum value of a long, with 32-bit unsigned long integers.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

This value is "2147483647" on OS/2 with 32-bit unsigned long integers.


[view class]
null
protected:
static const char * const null

A string that contains no element.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
zero
protected:
static const char * const zero

The number 0.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Word Operations

These members operate on a string as a collection of words separated by white-space characters. They find, remove, and count words or phrases.


[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, 0 is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
indexOfWord

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


Overload 1
public:
unsigned indexOfWord(unsigned wordNumber) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
unsigned indexOfWord( unsigned wordNumber, unsigned startPos, unsigned numWords ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the length of the specified white-space-delimited word in the receiver.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
numWords
public:
unsigned numWords() const

Returns the number of words in the receiver.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeWords

Deletes the specified words from the receiver's contents. You can specify the words by using a starting word number and the number of words. The latter defaults to the rest of the string.
Note: The static functions IString::space and IString::removeWords obtain the same result but do not affect the String to which they are applied.


Overload 1
public:
static IString removeWords( const IString& aString, unsigned startWord, unsigned numWords )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& removeWords(unsigned firstWord)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IString& removeWords(unsigned firstWord, unsigned numWords)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
static IString removeWords( const IString& aString, unsigned startWord )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
space

Modifies the receiver so that all words are separated by the specified number of blanks. The default is one blank. All white space is converted to simple blanks.
Note: The static functions IString::space and IString::removeWords obtain the same result but do not affect the String to which they are applied.


Overload 1
public:
static IString space( const IString& aString, unsigned numSpaces = 1, char spaceChar = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString& space( unsigned numSpaces = 1, char spaceChar = ' ' )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
word
public:
IString word(unsigned wordNumber) const

Returns a copy of the specified white-space-delimited word in the receiver.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the word number of the first word in the receiver that matches the specified phrase. The function starts its search with the word number you specify in startWord, which defaults to 1. If the phrase is not found, 0 is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
words

Returns a substring of the receiver that starts at a specified word and is comprised of a specified number of words. The word separators are copied to the result intact.


Overload 1
public:
IString words(unsigned firstWord, unsigned numWords) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IString words(unsigned firstWord) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IString - Type Definitions


[view class]
IndexType
typedef enum { charIndex , wordIndex } IndexType

Use these enumerators to specify whether the result from the findPhrase function is a word index or a character index:

charIndex
Returns the result as the byte index within the string
wordIndex
Returns the result as the index of the matching word. For example, the first word is 1, the second word is 2, and so forth.

Related Enumeration

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
BitOperator
typedef enum { bitAnd , bitOr , bitExclusiveOr , and = bitAnd , or = bitOr , exclusiveOr = bitExclusiveOr } BitOperator

Use these enumerators to specify the bit operator to apply to the applyBitOp function. Valid bit operators are as follows:

and, or, exclusiveOr has the same value as bitAnd, bitOr, bitExclusiveOr and are slated for removal in the next release.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IString - Associated Globals


operator !=
bool operator !=(const char* pString1, const IString& string2)

If the strings are not bitwise identical, true is returned. This operator handles the following form of the comparison:

pString1!=string2
The first operand is a null-terminated character string and the second is an IString.


operator !=
bool operator !=(const IString& string1, const IString& string2)

If the strings are not bitwise identical, true is returned. This operator handles the following form of the comparison:

string1!=string2
Both operands are of type IString.


operator !=
bool operator !=(const IString& string1, const char* pString2)

If the strings are not bitwise identical, true is returned. This operator handles the following form of the comparison:

string1!=pString2
The first operand is an IString and the second is a NULL-terminated character string.


operator &
IString operator &(const char* pString, const IString& aString)

Performs bitwise AND. This operator handles the following form of the comparison:

pString & aString
The first operand is a NULL-terminated character string and the second is an IString.


operator +
IString operator +(const char* pString, const IString& aString)

Concatenates a null-terminated character string and the second is an IString.


operator <
bool operator <(const char* pString1, const IString& string2)

If the first string is less than the second, using the standard collating scheme (memcmp), true is returned. This operator can handles the following form of the comparison:

pString1 < string2
The first operand is a null-terminated character string and the second is an IString.

Note: This operator is not locale-sensitive. Because it uses memcmp and not strcoll, it compares the binary values representing the characters and is not based on the LC_COLLATE category of the current locale. Its results are reliable only for code pages and character sets in which the collating sequence matches the sequence of binary representations.


operator <
bool operator <(const IString& string1, const char* pString2)

If the first string is less than the second, using the standard collating scheme (memcmp), true is returned. This operator handles the following form of the comparison:

string1 < pString2
The first operand is an IString and the second is a NULL-terminated character string.

Note: This operator is not locale-sensitive. Because it uses memcmp and not strcoll, it compares the binary values representing the characters and is not based on the LC_COLLATE category of the current locale. Its results are reliable only for code pages and character sets in which the collating sequence matches the sequence of binary representations.


operator <
bool operator <(const IString& string1, const IString& string2)

If the first string is less than the second, using the standard collating scheme (memcmp), true is returned. This operator handles the following form of the comparison:

string1 < string2
Both operands are of type IString.

Note: This operator is not locale-sensitive. Because it uses memcmp and not strcoll, it compares the binary values representing the characters and is not based on the LC_COLLATE category of the current locale. Its results are reliable only for code pages and character sets in which the collating sequence matches the sequence of binary representations.


operator <<
ostream & operator <<(ostream& aStream, const IString& aString)

Puts an IString's contents to an output stream.


operator <=
bool operator <=(const IString& string1, const IString& string2)

Equivalent to (string1 < string2) || (string1 == string2). This operator handles the following form of the comparison:

string1 <= string2
Both operands are of type IString.

Note: This operator is not locale-sensitive. Because it uses memcmp and not strcoll, it compares the binary values representing the characters and is not based on the LC_COLLATE category of the current locale. Its results are reliable only for code pages and character sets in which the collating sequence matches the sequence of binary representations.


operator <=
bool operator <=(const IString& string1, const char* pString2)

Equivalent to (string1 < string2) || (string1 == string2). This operator handles the following form of the comparison:

string1 <= pString2
The first operand is an IString and the second is a null-terminated character string.

Note: This operator is not locale-sensitive. Because it uses memcmp and not strcoll, it compares the binary values representing the characters and is not based on the LC_COLLATE category of the current locale. Its results are reliable only for code pages and character sets in which the collating sequence matches the sequence of binary representations.


operator <=
bool operator <=(const char* pString1, const IString& string2)

Equivalent to (string1 < string2) || (string1 == string2). This operator can handle the following form of the comparison:

pString1 <= string2
The first operand is a null-terminated character string and the second is an IString.

Note: This operator is not locale-sensitive. Because it uses memcmp and not strcoll, it compares the binary values representing the characters and is not based on the LC_COLLATE category of the current locale. Its results are reliable only for code pages and character sets in which the collating sequence matches the sequence of binary representations.


operator ==
bool operator ==(const IString& string1, const char* pString2)

If the strings are bitwise identical, true is returned. This operator handles the following form of the comparison:

string1 == pString2
The first operand is an IString and the second is a null-terminated character string.


operator ==
bool operator ==(const IString& string1, const IString& string2)

If the strings are bitwise identical, true is returned. This operator handles the following form of the comparison:

string1 == string2
Both operands are of type IString.


operator ==
bool operator ==(const char* pString1, const IString& string2)

If the strings are bitwise identical, true is returned. This operator handles the following form of the comparison:

pString1 == string2
The first operand is a null-terminated character string and the second is an IString.


operator >
bool operator >(const char* pString1, const IString& string2)

Equivalent to !(string1 <= string2). This operator handles the following form of the comparison:

pString1 > string2
The first operand is a NULL-terminated character string and the second is an IString.

Note: This operator is not locale-sensitive. Because it uses memcmp and not strcoll, it compares the binary values representing the characters and is not based on the LC_COLLATE category of the current locale. Its results are reliable only for code pages and character sets in which the collating sequence matches the sequence of binary representations.


operator >
bool operator >(const IString& string1, const char* pString2)

Equivalent to !(string1 <= string2). This operator handles the following form of the comparison:

string1 > pString2
The first operand is an IString and the second is a null-terminated character string.

Note: This operator is not locale-sensitive. Because it uses memcmp and not strcoll, it compares the binary values representing the characters and is not based on the LC_COLLATE category of the current locale. Its results are reliable only for code pages and character sets in which the collating sequence matches the sequence of binary representations.


operator >
bool operator >(const IString& string1, const IString& string2)

Equivalent to !(string1 <= string2). This operator handles the following form of the comparison:

string1 > string2
Both operands are of type IString.

Note: This operator is not locale-sensitive. Because it uses memcmp and not strcoll, it compares the binary values representing the characters and is not based on the LC_COLLATE category of the current locale. Its results are reliable only for code pages and character sets in which the collating sequence matches the sequence of binary representations.


operator >=
bool operator >=(const IString& string1, const IString& string2)

Equivalent to !(string1 < string2). This operator handles the following form of the comparison:

string1 >= string2
Both operands are of type IString.

Note: This operator is not locale-sensitive. Because it uses memcmp and not strcoll, it compares the binary values representing the characters and is not based on the LC_COLLATE category of the current locale. Its results are reliable only for code pages and character sets in which the collating sequence matches the sequence of binary representations.


operator >=
bool operator >=(const IString& string1, const char* pString2)

Equivalent to !(string1 < string2). This operator handles the following form of the comparison:

string1 >= pString2
The first operand is an IString and the second is a null-terminated character string.

Note: This operator is not locale-sensitive. Because it uses memcmp and not strcoll, it compares the binary values representing the characters and is not based on the LC_COLLATE category of the current locale. Its results are reliable only for code pages and character sets in which the collating sequence matches the sequence of binary representations.


operator >=
bool operator >=(const char* pString1, const IString& string2)

Equivalent to !(string1 < string2). This operator handles the following form of the comparison:

pString1 >= string2
The first operand is a null-terminated character string and the second is an IString.

Note: This operator is not locale-sensitive. Because it uses memcmp and not strcoll, it compares the binary values representing the characters and is not based on the LC_COLLATE category of the current locale. Its results are reliable only for code pages and character sets in which the collating sequence matches the sequence of binary representations.


operator >>
istream & operator >>(istream& aStream, IString& aString)

Puts the next white-space-delimited word from an input stream into an IString.


operator ^
IString operator ^(const char* pString, const IString& aString)

Performs bitwise XOR. This operator handles the following form:

pString ^ aString
The first operand is a NULL-terminated character string and the second is an IString.


operator |
IString operator |(const char* pString, const IString& aString)

Performs bitwise OR. This operator handles the following form:

pString | aString
The first operand is a null-terminated character string and the second is an IString.


IString - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data