Object methods (public)

char & operator [ ] ( const size_t offset ) const ;

References the character at offset offset in the storage. Ensure that the relevant byte exists and is addressable.

ImqString operator ( ) ( const size_t offset, const size_t length = 1 ) const ;

Returns a substring by copying bytes from the characters starting at offset. If length is zero, returns the rest of the characters. If the combination of offset and length does not produce a reference within the characters, returns an empty ImqString.

void operator = ( const ImqString & string );

Copies instance data from string, replacing the existing instance data.

ImqString operator + ( const char c ) const ;

Returns the result of appending c to the characters.

ImqString operator + ( const char * text ) const ;

Returns the result of appending text to the characters. This can also be inverted. For example:

strOne + "string two" ;
"string one" + strTwo ;

Note:

Although most compilers accept strOne + "string two"; Microsoft Visual C++ requires strOne + (char *)"string two" ;

ImqString operator + ( const ImqString & string1 ) const ;

Returns the result of appending string1 to the characters.

ImqString operator + ( const double number ) const ;

Returns the result of appending number to the characters after conversion to text.

ImqString operator + ( const long number ) const ;

Returns the result of appending number to the characters after conversion to text.

void operator += ( const char c );

Appends c to the characters.

void operator += ( const char * text );

Appends text to the characters.

void operator += ( const ImqString & string );

Appends string to the characters.

void operator += ( const double number );

Appends number to the characters after conversion to text.

void operator += ( const long number );

Appends number to the characters after conversion to text.

operator char * ( ) const ;

Returns the address of the first byte in the storage. This value can be zero, and is volatile. Use this method only for read-only purposes.

ImqBoolean operator < ( const ImqString & string ) const ;

ImqBoolean operator > ( const ImqString & string ) const ;

ImqBoolean operator <= ( const ImqString & string ) const ;

ImqBoolean operator >= ( const ImqString & string ) const ;

ImqBoolean operator == ( const ImqString & string ) const ;

ImqBoolean operator != ( const ImqString & string ) const ;

Compares the characters with those of string using the compare method. It returns either TRUE or FALSE.

short compare( const ImqString & string ) const ;

Compares the characters with those of string. The result is zero if the characters are equal, negative if less than and positive if greater than. Comparison is case sensitive. A null ImqString is regarded as less than a nonnull ImqString.

ImqBoolean copyOut( char * buffer, const size_t length, const char pad = 0 );

Copies up to length bytes from the characters to the buffer. If the number of characters is insufficient, fills the remaining space in buffer with pad characters. buffer can be zero if length is also zero. It returns TRUE if successful.

size_t copyOut( long & number ) const ;

Sets number from the characters after conversion from text, and returns the number of characters involved in the conversion. If this is zero, no conversion has been performed and number is not set. A convertible character sequence must begin with the following values:

<blank(s)>
<+|->
digit(s)

size_t copyOut( ImqString & token, const char c = ' ' ) const ;

If the characters contain one or more characters that are different from c, identifies a token as the first contiguous sequence of such characters. In this case token is set to that sequence, and the value returned is the sum of the number of leading characters c and the number of bytes in the sequence. Otherwise, returns zero and does not set token.

size_t cutOut( long & number );

Sets number as for the copy method, but also removes from characters the number of bytes indicated by the return value. For example, the string shown in the following example can be cut into three numbers by using cutOut( number ) three times:

strNumbers = "-1 0     +55 ";
 
while ( strNumbers.cutOut( number ) );
number becomes -1, then 0, then 55
leaving strNumbers == " "

size_t cutOut( ImqString & token, const char c = ' ' );

Sets token as for the copyOut method, and removes from characters the strToken characters and also any characters c that precede the token characters. If c is not a blank, removes characters c that directly succeed the token characters. Returns the number of characters removed. For example, the string shown in the following example can be cut into three tokens by using cutOut( token ) three times:

strText = "  Program V1.1  ";
 
while ( strText.cutOut( token ) );
 
// token becomes "Program", then "Version",
// then "1.1" leaving strText == "  "

The following example shows how to parse a DOS path name:

strPath = "C:\OS2\BITMAP\OS2LOGO.BMP"
 
strPath.cutOut( strDrive, ':' );
strPath.stripLeading( ':' );
while ( strPath.cutOut( strFile, '\' ) );
 
// strDrive becomes "C".
// strFile becomes "OS2", then "BITMAP",
// then "OS2LOGO.BMP" leaving strPath empty.

ImqBoolean find( const ImqString & string );

Searches for an exact match for string anywhere within the characters. If no match is found, it returns FALSE. Otherwise, it returns TRUE. If string is null, it returns TRUE.

ImqBoolean find( const ImqString & string, size_t & offset );

Searches for an exact match for string somewhere within the characters from offset offset onwards. If string is null, it returns TRUE without updating offset. If no match is found, it returns FALSE (the value of offset might have been increased). If a match is found, it returns TRUE and updates offset to the offset of string within the characters.

size_t length( ) const ;

Returns the length.

ImqBoolean pasteIn( const double number, const char * format = "%f" );

Appends number to the characters after conversion to text. It returns TRUE if successful.

The specification format is used to format the floating point conversion. If specified, it must be one suitable for use with printf and floating point numbers, for example %.3f.

ImqBoolean pasteIn( const long number );

Appends number to the characters after conversion to text. It returns TRUE if successful.

ImqBoolean pasteIn( const void * buffer, const size_t length );

Appends length bytes from buffer to the characters, and adds a final trailing null. Substitutes any null characters copied. The substitution character is a period (.). No special consideration is given to any other nonprintable or nondisplayable characters copied. This method returns TRUE if successful.

ImqBoolean set( const char * buffer, const size_t length );

Sets the characters from a fixed-length character field, which might contain a null. Appends a null to the characters from the fixed-length field if necessary. This method returns TRUE if successful.

size_t storage( ) const ;

Returns the number of bytes in the storage.

ImqBoolean setStorage( const size_t length );

Allocates (or reallocates) the storage. Preserves any original characters, including any trailing null, if there is still room for them, but does not initialize any additional storage.

This method returns TRUE if successful.

size_t stripLeading( const char c = ' ' );

Strips leading characters c from the characters and returns the number removed.

size_t stripTrailing( const char c = ' ' );

Strips trailing characters c from the characters and returns the number removed.

ImqString upperCase( ) const ;

Returns an uppercase copy of the characters.