This class provides character string storage and manipulation for
null-terminated strings. An ImqString can be used in place of a
char * in most situations where a parameter calls for a char
*.
- char & operator [ ] ( const size_t
offset ) const ;
- References the character at offset offset in the
storage. It is the user's responsibility to 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, the rest of
the characters are returned. If the combination of
offset and length does not produce a reference within the
characters, an empty ImqString is returned.
- void operator = ( const ImqString &
string );
- Instance data is copied 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 );
- c is appended 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.
- void 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, then the remaining space in buffer is filled with
pad characters. buffer may 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 different from
c, a token is identified 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, zero is returned
and token is not set.
- 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 which precede the token characters. If c
is not a blank, characters c that directly succeed the token
characters are also removed. The number of characters removed is
returned. For example, the string shown in the following example can be
cut into three tokens by using cutOut( token )
three times:
strText = " Program Version 1.1 ";
while ( strText.cutOut( token ) );
// token becomes "Program", then "Version",
// then "1.1" leaving strText == " "
The following example shows how a DOS path name can be parsed:
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; note that
the value of offset may 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" );
- number is appended 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 should be one suitable for use with
printf and floating point numbers, for example
"%.3f".
- ImqBoolean pasteIn( const long number
);
- number is appended 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. A substitution
is made for 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. A null is appended 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
);
- (Re)allocates the storage. Any original characters, including any trailing
null, are preserved if there is still room for them, but any additional
storage is not initialized.
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.
