Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

MQe_String.h File Reference


Detailed Description

The generic multi-byte String definition header.

The MQeString class contains user defined and system strings and is an abstraction of character strings. It allows a string to be created or retrieved in a number of formats such as arrays containing Unicode code points (each code point stored in a 1, 2, or 4 bytes memory space) and UTF-8. The current implementation only supports these external formats. MQeString is used throughout the API where a string is required.


Data Structures

struct  MQeStaticString_st
 structure for external static constant String. More...


Defines

#define EXTERNAL_UTF8_STATIC_MQESTRING
 Initial signature of external MQeString.

#define MQESTRING_CURRENT_VERSION
 Current version number of MQeString.

#define CREATE_UTF8_STATIC_MQESTRING(var, val)
 This macro creates a static MQeString variable (structure). Its address can be used as a value for an MQeStringHndl (you may need to cast it).


Typedefs

typedef MQeStaticString_st MQeStaticString
 type definition of struct MQeStaticString_st


Functions

MQERETURN mqeString_newChar8 (MQeExceptBlock *pErrStruct, MQeStringHndl *phNewString, MQECONST MQECHAR *pInput)
 Creates a new MQeString and copies/converts the MQECHAR string pInput (each array element represents a Unicode code point) into the created MQeString.

MQERETURN mqeString_newChar16 (MQeExceptBlock *pErrStruct, MQeStringHndl *phNewString, MQECONST MQECHAR16 *pInput)
 Creates a new MQeString and copies/converts the MQECHAR16 string pInput (each array element represents a Unicode code point) into the created MQeString.

MQERETURN mqeString_newChar32 (MQeExceptBlock *pErrStruct, MQeStringHndl *phNewString, MQECONST MQECHAR32 *pInput)
 Creates a new MQeString and copies/converts the MQECHAR32 string pInput (each array element represents a Unicode code point) into the created MQeString.

MQERETURN mqeString_newUtf8 (MQeExceptBlock *pErrStruct, MQeStringHndl *phNewString, MQECONST MQECHAR *pInput)
 Creates a new MQeString and copies/converts the Unicode UTF-8 string pInput into the created MQeString.

MQERETURN mqeString_newUtf16 (MQeExceptBlock *pErrStruct, MQeStringHndl *phNewString, MQECONST MQECHAR16 *pInput)
 Creates a new MQeString and copies the Unicode UTF-16 string pInput (each array element represents a Unicode code point) into the created MQeString.It also supports surrogate pairs.

MQERETURN mqeString_free (MQeStringHndl hString, MQeExceptBlock *pErrStruct)
 Frees the MQeString pointed to by hString.

MQERETURN mqeString_getChar8 (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQECHAR *pOutputString, MQEINT32 *pSize)
 Copies (converts if the internal storage format is different) the text content of the MQeString hString into the MQECHAR buffer pointed to by pOutputString. The string will be stored in the C single byte string format. An error is raised if the string can not be converted into a single byte C string.

MQERETURN mqeString_getChar16 (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQECHAR16 *pOutputString, MQEINT32 *pSize)
 Copies (converts if the internal storage format is different) the text content of the MQeString hString into the MQECHAR16 buffer pointed to by pOutputString. The string will be stored in the UNICODE double-byte string format.

MQERETURN mqeString_getChar32 (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQECHAR32 *pOutputString, MQEINT32 *pSize)
 Copies (converts if the internal storage format is different) the text content of the MQeString hString into the MQECHAR32 buffer pointed to by pOutputString. The string will be stored in the UNICODE quad-byte string format.

MQERETURN mqeString_getUtf8 (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQECHAR *pOutputString, MQEINT32 *pSize)
 Copies (converts if the internal storage format is different) the text content of the MQeString hString into the buffer pointed to by pOutputString. The string will be stored in the UTF-8 format.

MQERETURN mqeString_getUtf16 (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQECHAR16 *pOutputString, MQEINT32 *pSize)
 Copies (converts if the internal storage format is different) the text content of the MQeString hString into the buffer pointed to by pOutputString. The string will be stored in the UTF-16 format.

MQERETURN mqeString_equalTo (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQEBOOL *pIsEqual, MQECONST MQeStringHndl hEqualToString)
 Compare the text content of hString with that of hEqualToString for exact equality (storage format independent).

MQERETURN mqeString_codePointSize (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQEINT32 *pSize)
 Find the number of bytes required to store the largest code point in the string.

MQERETURN mqeString_isAsciiOnly (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQEBOOL *pIsAsciiOnly)
 Check if hString contains Ascii characters only, i.e. 32 <= val < 128 (can be represented in multi-byte form).

MQERETURN mqeString_isNull (MQeStringHndl hString, MQeExceptBlock *pErrStruct, MQEBOOL *pIsNull)
 Check if hString contains a NULL string.

MQERETURN mqeString_cat (MQeExceptBlock *pExceptBlock, MQeStringHndl *phNewString, MQECONST MQeStringHndl hString1, MQECONST MQeStringHndl hString2)
 This function creates a new string by concatenating two MQeStrings.

MQERETURN mqeString_catAll (MQeExceptBlock *pExceptBlock, MQeStringHndl *phNewString, MQECONST MQeStringHndl *phStrings, MQEINT32 noOfStrings)
 This function creates a new string by concatenating an array of MQeStrings.

MQERETURN mqeString_duplicate (MQeExceptBlock *pExceptBlock, MQeStringHndl *phNewString, MQECONST MQeStringHndl hString)
 This is a macro for duplicating an MQeString (only dynamic strings are actually duplicated).

MQERETURN mqeString_getSubMQeString (MQeStringHndl hString, MQeExceptBlock *pExceptBlock, MQeStringHndl *phOutString, MQEINT32 from, MQEINT32 to)
 This function creates an MQeString whose content is the substring of hString.

MQERETURN mqeString_getCharLocation (MQeStringHndl hString, MQeExceptBlock *pExceptBlock, MQEINT32 *pOutIndex, MQECHAR32 charToFind, MQEINT32 startFrom, MQEBOOL searchForward)
 This function searches an MQeString for a specific character and returns the index of the character found.


Define Documentation

#define EXTERNAL_UTF8_STATIC_MQESTRING
 

Initial signature of external MQeString.

This is the signature used in CREATE_UTF8_STATIC_MQESTRING to indicate a static string variable

#define CREATE_UTF8_STATIC_MQESTRING var,
val   
 

This macro creates a static MQeString variable (structure). Its address can be used as a value for an MQeStringHndl (you may need to cast it).

This is the only construct a user needs to create an MQeStaticString. For example:

       CREATE_UTF8_STATIC_MQESTRING(s,"a string")
  
creates an MQeStaticString s with string value "a string".
Parameters:
var  name of the variable to be created.
val  a static constant UTF-8 string.
Warning:
Once created, do not attempt to modify any of the structure components of the variable. It may have unpredictable consequences. The val string supplied must be in the UTF-8 format. (A string containing only invariant Ascii (7 bit) characters is a special case of UTF-8 strings.)


Typedef Documentation

typedef struct MQeStaticString_st MQeStaticString
 

type definition of struct MQeStaticString_st

This is the type of variable created by CREATE_UTF8_STATIC_MQESTRING.


Function Documentation

MQERETURN mqeString_newChar8 MQeExceptBlock   pErrStruct,
MQeStringHndl *    phNewString,
MQECONST MQECHAR *    pInput
 

Creates a new MQeString and copies/converts the MQECHAR string pInput (each array element represents a Unicode code point) into the created MQeString.

Parameters:
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
phNewString  [in/out] pointer to the new MQeString.
pInput  [in] pointer to a NULL terminated C input string.
Precondition:
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*phNewString).
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_ALLOCATION_FAILED 
  • Memory allocation failed
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_STRTYPE_UNKNOWN type unknown
  • MQEREASON_STRTYPE_NOT_SUPPORTED type not supported
  • MQEREASON_API_NULL_POINTER NULL pInput/phNewString
  • MQEREASON_API_VALUE_OUT_OF_RANGE negative length
Warning:
Users are expected to use mqeString_free() to free the object returned by this call after it is no longer needed. This will enable reuse of some system resources and avoid some avoidable system crashes.
The maximum Unicode code point this API call can handle is U+00FF.

MQERETURN mqeString_newChar16 MQeExceptBlock   pErrStruct,
MQeStringHndl *    phNewString,
MQECONST MQECHAR16 *    pInput
 

Creates a new MQeString and copies/converts the MQECHAR16 string pInput (each array element represents a Unicode code point) into the created MQeString.

Parameters:
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
phNewString  [in/out] pointer to the new MQeString.
pInput  [in] pointer to a 0x0000 terminated UNICODE input string.
Precondition:
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*phNewString).
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_ALLOCATION_FAILED 
  • Memory allocation failed
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_STRTYPE_UNKNOWN type unknown
  • MQEREASON_STRTYPE_NOT_SUPPORTED type not supported
  • MQEREASON_API_NULL_POINTER NULL pInput/phNewString
  • MQEREASON_API_VALUE_OUT_OF_RANGE negative length
Warning:
Users are expected to use mqeString_free() to free the object returned by this call after it is no longer needed. This will enable reuse of some system resources and avoid some avoidable system crashes.
The maximum Unicode code point this API call can handle is U+FFFF.

MQERETURN mqeString_newChar32 MQeExceptBlock   pErrStruct,
MQeStringHndl *    phNewString,
MQECONST MQECHAR32 *    pInput
 

Creates a new MQeString and copies/converts the MQECHAR32 string pInput (each array element represents a Unicode code point) into the created MQeString.

Parameters:
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
phNewString  [in/out] pointer to the new MQeString.
pInput  [in] pointer to a 0x00000000 terminated UNICODE input string.
Precondition:
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*phNewString).
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_ALLOCATION_FAILED 
  • Memory allocation failed
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_STRTYPE_UNKNOWN type unknown
  • MQEREASON_STRTYPE_NOT_SUPPORTED type not supported
  • MQEREASON_API_NULL_POINTER NULL pInput/phNewString
  • MQEREASON_API_VALUE_OUT_OF_RANGE negative length
Warning:
Users are expected to use mqeString_free() to free the object returned by this call after it is no longer needed. This will enable reuse of some system resources and avoid some avoidable system crashes.

MQERETURN mqeString_newUtf8 MQeExceptBlock   pErrStruct,
MQeStringHndl *    phNewString,
MQECONST MQECHAR *    pInput
 

Creates a new MQeString and copies/converts the Unicode UTF-8 string pInput into the created MQeString.

Parameters:
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
phNewString  [in/out] pointer to the new MQeString.
pInput  [in] pointer to a NULL terminated UTF-8 input string.
Precondition:
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*phNewString).
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_ALLOCATION_FAILED 
  • Memory allocation failed
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_STRTYPE_UNKNOWN type unknown
  • MQEREASON_STRTYPE_NOT_SUPPORTED type not supported
  • MQEREASON_API_NULL_POINTER NULL pInput/phNewString
  • MQEREASON_API_VALUE_OUT_OF_RANGE negative length
Warning:
Users are expected to use mqeString_free() to free the object returned by this call after it is no longer needed. This will enable reuse of some system resources and avoid some avoidable system crashes.

MQERETURN mqeString_newUtf16 MQeExceptBlock   pErrStruct,
MQeStringHndl *    phNewString,
MQECONST MQECHAR16 *    pInput
 

Creates a new MQeString and copies the Unicode UTF-16 string pInput (each array element represents a Unicode code point) into the created MQeString.It also supports surrogate pairs.

Parameters:
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
phNewString  [in/out] pointer to the new MQeString.
pInput  [in] pointer to a 0x0000 terminated UNICODE input string.
Precondition:
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*phNewString).
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_ALLOCATION_FAILED 
  • Memory allocation failed
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_STRTYPE_UNKNOWN type unknown
  • MQEREASON_STRTYPE_NOT_SUPPORTED type not supported
  • MQEREASON_API_NULL_POINTER NULL pInput/phNewString
  • MQEREASON_API_VALUE_OUT_OF_RANGE negative length
Warning:
Users are expected to use mqeString_free() to free the object returned by this call after it is no longer needed. This will enable reuse of some system resources and avoid some avoidable system crashes.
The maximum Unicode code point this API call can handle is U+10FFFF.

MQERETURN mqeString_free MQeStringHndl    hString,
MQeExceptBlock   pErrStruct
 

Frees the MQeString pointed to by hString.

Parameters:
hString  [in] the MQeString to be freed.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
Precondition:
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Return values:
MQERETURN_OK 
  • Operation successful

MQERETURN mqeString_getChar8 MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQECHAR *    pOutputString,
MQEINT32 *    pSize
 

Copies (converts if the internal storage format is different) the text content of the MQeString hString into the MQECHAR buffer pointed to by pOutputString. The string will be stored in the C single byte string format. An error is raised if the string can not be converted into a single byte C string.

Parameters:
hString  [in] source MQeString.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pOutputString  [in/out] a pre-allocated MQECHAR buffer.
pSize  [in/out] pointer to the size of buffer pointed to by pOutputString.
Precondition:
hString must be an MQeString created by mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*pOutputString) and (*pSize).
 * ----------------- ---------------------- ------------------------------- -------------------------
 * initial (*pSize)  initial pOutputString  returned (*pSize)               returned pOutputString
 * ----------------- ---------------------- ------------------------------- -------------------------
 * <= 0              any                    buffer size (in bytes) required not defined
 *                                          (including storage for
 *                                           termination character)
 * any               NULL                   ditto                           ditto
 * > 0               != NULL                buffer space used (in bytes)    points to the result
 * 
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_API_NULL_POINTER NULL pSize
  • MQEREASON_API_INVALID_SIGNATURE (*hString) not an MQeString
MQERETURN_BUFFER_OVERFLOW 
  • Supplied buffer not bigger enough
Warning:
The maximum Unicode code point this API call can handle is U+00FF.

MQERETURN mqeString_getChar16 MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQECHAR16 *    pOutputString,
MQEINT32 *    pSize
 

Copies (converts if the internal storage format is different) the text content of the MQeString hString into the MQECHAR16 buffer pointed to by pOutputString. The string will be stored in the UNICODE double-byte string format.

Parameters:
hString  [in] source MQeString.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pOutputString  [in/out] a pre-allocated MQECHAR16 buffer.
pSize  [in/out] pointer to the size (number of characters) of buffer pointed to by pOutputString.
Precondition:
hString must be an MQeString created by mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*pOutputString) and (*pSize).
 * ----------------- ---------------------- ------------------------------- -------------------------
 * initial (*pSize)  initial pOutputString  returned (*pSize)               returned pOutputString
 * ----------------- ---------------------- ------------------------------- -------------------------
 * <= 0              any                    buffer size (number of          not defined
 *                                          characters) required
 *                                          (including storage for
 *                                           termination char (0x0000))
 * any               NULL                   ditto                           ditto
 * > 0               != NULL                buffer space used (number of    points to the result
 *                                          characters)
 * 
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_API_NULL_POINTER NULL pSize
  • MQEREASON_API_INVALID_SIGNATURE (*hString) not an MQeString
MQERETURN_BUFFER_OVERFLOW 
  • Supplied buffer not bigger enough
Warning:
The maximum Unicode code point this API call can handle is U+FFFF.

MQERETURN mqeString_getChar32 MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQECHAR32 *    pOutputString,
MQEINT32 *    pSize
 

Copies (converts if the internal storage format is different) the text content of the MQeString hString into the MQECHAR32 buffer pointed to by pOutputString. The string will be stored in the UNICODE quad-byte string format.

Parameters:
hString  [in] source MQeString.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pOutputString  [in/out] a pre-allocated MQECHAR32 buffer.
pSize  [in/out] pointer to the size (number of characters) of buffer pointed to by pOutputString.
Precondition:
hString must be an MQeString created by mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*pOutputString) and (*pSize).
 * ----------------- ---------------------- ------------------------------- -------------------------
 * initial (*pSize)  initial pOutputString  returned (*pSize)               returned pOutputString
 * ----------------- ---------------------- ------------------------------- -------------------------
 * <= 0              any                    buffer size (number of          not defined
 *                                          characters) required
 *                                          (including storage for
 *                                           termination char (0x00000000))
 * any               NULL                   ditto                           ditto
 * > 0               != NULL                buffer space used (number of    points to the result
 *                                          characters)
 * 
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_API_NULL_POINTER NULL pSize
  • MQEREASON_API_INVALID_SIGNATURE (*hString) not an MQeString
MQERETURN_BUFFER_OVERFLOW 
  • Supplied buffer not bigger enough

MQERETURN mqeString_getUtf8 MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQECHAR *    pOutputString,
MQEINT32 *    pSize
 

Copies (converts if the internal storage format is different) the text content of the MQeString hString into the buffer pointed to by pOutputString. The string will be stored in the UTF-8 format.

Parameters:
hString  [in] source MQeString.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pOutputString  [in/out] a pre-allocated MQECHAR buffer.
pSize  [in/out] pointer to the size (number of bytes) of buffer pointed to by pOutputString.
Precondition:
hString must be an MQeString created by mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*pOutputString) and (*pSize).
 * ----------------- ---------------------- ------------------------------- -------------------------
 * initial (*pSize)  initial pOutputString  returned (*pSize)               returned pOutputString
 * ----------------- ---------------------- ------------------------------- -------------------------
 * <= 0              any                    buffer size (number of          not defined
 *                                          bytes) required
 *                                          (including storage for
 *                                           termination char ('\0'))
 * any               NULL                   ditto                           ditto
 * > 0               != NULL                buffer space used (number of    points to the result
 *                                          bytes)
 * 
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_API_NULL_POINTER NULL pSize
  • MQEREASON_API_INVALID_SIGNATURE (*hString) not an MQeString
MQERETURN_BUFFER_OVERFLOW 
  • Supplied buffer not bigger enough

MQERETURN mqeString_getUtf16 MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQECHAR16 *    pOutputString,
MQEINT32 *    pSize
 

Copies (converts if the internal storage format is different) the text content of the MQeString hString into the buffer pointed to by pOutputString. The string will be stored in the UTF-16 format.

Parameters:
hString  [in] source MQeString.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pOutputString  [in/out] a pre-allocated MQECHAR16 buffer.
pSize  [in/out] pointer to the size (number of characters) of buffer pointed to by pOutputString.
Precondition:
hString must be an MQeString created by mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
Returns :
(*pOutputString) and (*pSize).
 * ----------------- ---------------------- ------------------------------- -------------------------
 * initial (*pSize)  initial pOutputString  returned (*pSize)               returned pOutputString
 * ----------------- ---------------------- ------------------------------- -------------------------
 * <= 0              any                    buffer size (number of          not defined
 *                                          characters) required
 *                                          (including storage for
 *                                           termination char (0x0000))
 * any               NULL                   ditto                           ditto
 * > 0               != NULL                buffer space used (number of    points to the result
 *                                          characters)
 * 
Return values:
MQERETURN_OK 
  • Operation successful
MQERETURN_SESSION_NOT_INITIALIZED 
  • MQeSession_initialize() not yet called
MQERETURN_INVALID_ARGUMENT 
  • MQEREASON_API_NULL_POINTER NULL pSize
  • MQEREASON_API_INVALID_SIGNATURE (*hString) not an MQeString
MQERETURN_BUFFER_OVERFLOW 
  • Supplied buffer not bigger enough
Warning:
The maximum Unicode code point this API call can handle is U+10FFFF.

MQERETURN mqeString_equalTo MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQEBOOL *    pIsEqual,
MQECONST MQeStringHndl    hEqualToString
 

Compare the text content of hString with that of hEqualToString for exact equality (storage format independent).

Parameters:
hString  [in] source string.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pIsEqual  [in/out] pointer to the result variable.
hEqualToString  [in/out] pointer to the MQeString to be compared with.
Precondition:
hString and pEqualToString must be MQeStrings created using mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
pIsEqual must point to an existing variable.
Returns :
(*pIsEqual).
Return values:
MQERETURN_OK 
  • Operation successful
Warning:
This function assumes that codes which represent characters in a language stored in the strings are unique. This may not be true for certain languages.

MQERETURN mqeString_codePointSize MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQEINT32 *    pSize
 

Find the number of bytes required to store the largest code point in the string.

Parameters:
hString  [in] source string.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pSize  [in/out] pointer to the result variable.
Precondition:
hString must be an MQeString created by mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
pSize must point to an existing variable.
Returns :
(*pSize).
Return values:
MQERETURN_OK 
  • Operation successful

MQERETURN mqeString_isAsciiOnly MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQEBOOL *    pIsAsciiOnly
 

Check if hString contains Ascii characters only, i.e. 32 <= val < 128 (can be represented in multi-byte form).

Parameters:
hString  [in] source string.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pIsAsciiOnly  [in/out] pointer to the result variable.
Precondition:
hString must be an MQeString created by mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
pIsAsciiOnly must point to an existing variable.
Returns :
(*pIsAsciiOnly).
Return values:
MQERETURN_OK 
  • Operation successful

MQERETURN mqeString_isNull MQeStringHndl    hString,
MQeExceptBlock   pErrStruct,
MQEBOOL *    pIsNull
 

Check if hString contains a NULL string.

Parameters:
hString  [in] source string handle.
pErrStruct  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pIsNull  [in/out] pointer to the result variable.
Precondition:
hString must be an MQeString created by mqeString_new().
pErrStruct should point to a pre-allocated MQeExceptBlock structure (no error information will be returned if pErrStruct is null).
pIsNull must point to an existing variable.
Returns :
(*pIsNull).
Return values:
MQERETURN_OK 
  • Operation successful

MQERETURN mqeString_cat MQeExceptBlock   pExceptBlock,
MQeStringHndl *    phNewString,
MQECONST MQeStringHndl    hString1,
MQECONST MQeStringHndl    hString2
 

This function creates a new string by concatenating two MQeStrings.

Parameters:
pExceptBlock  [in/out] pointer to a pre-allocated MQeExceptBlock structure
phNewString  [in/out] pointer to the output handle
hString1  [in] first string to concatenate
hString2  [in] second string to concatenate

MQERETURN mqeString_catAll MQeExceptBlock   pExceptBlock,
MQeStringHndl *    phNewString,
MQECONST MQeStringHndl *    phStrings,
MQEINT32    noOfStrings
 

This function creates a new string by concatenating an array of MQeStrings.

Parameters:
pExceptBlock  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
phNewString  [in/out] pointer to the output handle.
phStrings  [in] array of input MQeStrings.
noOfStrings  [in] number of input MQeStrings in phStrings.

MQERETURN mqeString_duplicate MQeExceptBlock   pExceptBlock,
MQeStringHndl *    phNewString,
MQECONST MQeStringHndl    hString
 

This is a macro for duplicating an MQeString (only dynamic strings are actually duplicated).

Parameters:
hString  [in] handle to input MQeString.
pExceptBlock  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
phNewString  [in/out] pointer to the output handle.

MQERETURN mqeString_getSubMQeString MQeStringHndl    hString,
MQeExceptBlock   pExceptBlock,
MQeStringHndl *    phOutString,
MQEINT32    from,
MQEINT32    to
 

This function creates an MQeString whose content is the substring of hString.

Parameters:
hString  [in] handle to input MQeString.
pExceptBlock  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
phOutString  [in/out] pointer to the handle of output string.
from  [in] index of the first character of the substring (index starts from 0).
to  [in] index of the last character of the substring.

MQERETURN mqeString_getCharLocation MQeStringHndl    hString,
MQeExceptBlock   pExceptBlock,
MQEINT32 *    pOutIndex,
MQECHAR32    charToFind,
MQEINT32    startFrom,
MQEBOOL    searchForward
 

This function searches an MQeString for a specific character and returns the index of the character found.

Parameters:
pExceptBlock  [in/out] pointer to a pre-allocated MQeExceptBlock structure.
pOutIndex  [in/out] pointer to the output index variable.
hString  [in] handle to input MQeString.
charToFind  [in] character to search for.
startFrom  [in] index of character (0 for the 1st character) from where the search starts.
searchForward  [in] search direction: forward(MQE_TRUE) / backward(MQE_FALSE).


Generated Thu Aug 11 23:27:13 2005 for Websphere MQ Everyplace for Multiplatforms C Programming Reference