ImqString C++ class

This class provides character string storage and manipulation for null-terminated strings.

Figure 1. ImqString class

Use an ImqString in place of a char * in most situations where a parameter calls for a char *.


Object attributes

    characters
    Characters in the storage that precede a trailing null.

    length
    Number of bytes in the characters. If there is no storage, the length is zero. The initial value is zero.

    storage
    A volatile array of bytes of arbitrary size. A trailing null must always be present in the storage after the characters, so that the end of the characters can be detected. Methods ensure that this situation is maintained, but ensure, when setting bytes in the array directly, that a trailing null exists after modification. Initially, there is no storage attribute.


Constructors

    ImqString( );
    The default constructor.

    ImqString( const ImqString & string );
    The copy constructor.

    ImqString( const char c );
    The characters comprise c.

    ImqString( const char * text );
    The characters are copied from text.

    ImqString( const void * buffer, const size_t length );
    Copies length bytes starting from buffer and assigns them to the characters. Substitution is made for any null characters copied. The substitution character is a period (.). No special consideration is given to any other non-printable or non-displayable characters copied.


Class methods (public)

    static ImqBoolean copy( char * destination-buffer, const size_t length, const char * source-buffer, const char pad = 0 );
    Copies up to length bytes from source-buffer to destination-buffer. If the number of characters in source-buffer is insufficient, fills the remaining space in destination-buffer with pad characters. source-buffer can be zero. destination-buffer can be zero if length is also zero. Any error codes are lost. This method returns TRUE if successful.

    static ImqBoolean copy ( char * destination-buffer, const size_t length, const char * source-buffer, ImqError & error-object, const char pad = 0 );
    Copies up to length bytes from source-buffer to destination-buffer. If the number of characters in source-buffer is insufficient, fills the remaining space in destination-buffer with pad characters. source-buffer can be zero. destination-buffer can be zero if length is also zero. Any error codes are set in error-object. This method returns TRUE if successful.


Overloaded ImqItem methods

    virtual ImqBoolean copyOut ( ImqMessage & msg );
    Copies the characters to the message buffer, replacing any existing content. Sets the msg format to MQFMT_STRING.

    See the parent class method description for further details.

    virtual ImqBoolean pasteIn ( ImqMessage & msg );
    Sets the characters by transferring the remaining data from the message buffer, replacing the existing characters.

    To be successful, the encoding of the msg object must be MQENC_NATIVE. Retrieve messages with MQGMO_CONVERT to MQENC_NATIVE.

    To be successful, the ImqMessage format must be MQFMT_STRING.

    See the parent class method description for further details.


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 ;
    Compares the characters with those of string using the compare method. The result is TRUE if less than and FALSE if greater than or equal to.

    ImqBoolean operator > ( const ImqString & string ) const ;
    Compares the characters with those of string using the compare method. The result is TRUE if greater than and FALSE if less than or equal to.

    ImqBoolean operator <= ( const ImqString & string ) const ;
    Compares the characters with those of string using the compare method. The result is TRUE if less than or equal to and FALSE if greater than.

    ImqBoolean operator >= ( const ImqString & string ) const ;
    Compares the characters with those of string using the compare method. The result is TRUE if greater than or equal to and FALSE if less than.

    ImqBoolean operator == ( const ImqString & string ) const ;
    Compares the characters with those of string using the compare method. It returns either TRUE or FALSE.

    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 Version 1.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.

    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 storage( ) const ;
    Returns the number of bytes in the storage.

    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.


Object methods (protected)

    ImqBoolean assign ( const ImqString & string );
    Equivalent to the equivalent operator = method, but non-virtual. It returns TRUE if successful.


Reason codes

  • MQRC_DATA_TRUNCATED
  • MQRC_NULL_POINTER
  • MQRC_STORAGE_NOT_AVAILABLE
  • MQRC_BUFFER_ERROR
  • MQRC_INCONSISTENT_FORMAT