ifx_gl_mbscoll

ifx_gl_mbscoll - multi-byte string comparison using collating information

SYNOPSIS


#include <ifxgls.h>
int ifx_gl_mbscoll(gl_mchar_t *mbs1, int mbs1_byte_length,
gl_mchar_t *mbs2, int mbs2_byte_length)

DESCRIPTION

This function compares the multi-byte character strings mbs1 and mbs2 according to the rules of the current locale.

If mbs1_byte_length is the value IFX_GL_NULL then the function will assume that mbs1 is a null-terminated string; otherwise the function assumes that mbs1_byte_length is the number of bytes in mbs1. If mbs2_byte_length is the value IFX_GL_NULL then the function will assume that mbs2 is a null-terminated string; otherwise the function assumes that mbs2_byte_length is the number of bytes in mbs2. See Multi-Byte Character String Termination for more general information about these lengths.

RETURN VALUES

This function returns an integer greater than, equal to, or less than zero, according to whether mbs1 is greater than, equal to, or less than mbs2, when they are compared according to the rules of the current locale.

ERRORS

If an error has occurred, this function returns -1 and sets ifx_gl_lc_errno() to one of the following,

[IFX_GL_PARAMERR]: Either mbs1_byte_length is not equal to IFX_GL_NULL and is not greater than or equal to zero, or mbs2_byte_length is not equal to IFX_GL_NULL and is not greater than or equal to zero.
[IFX_GL_TERMMISMAT]: Either mbs1_byte_length is equal to IFX_GL_NULL and mbs2_byte_length is greater than or equal to zero or mbs1_byte_length is greater than or equal to zero and mbs2_byte_length is equal to IFX_GL_NULL
[IFX_GL_EILSEQ]: Either mbs1 or mbs2 contains an invalid multi-byte character
[IFX_GL_EINVAL]: Either the function cannot determine whether the last character of mbs1 is a valid multi-byte character, because it would need to read more than mbs1_byte_length bytes from mbs1, or the function cannot determine whether the last character of mbs2 is a valid multi-byte character, because it would need to read more than mbs2_byte_length bytes from mbs2. See Keeping Multi-Byte Strings Consistent for more information about this error.

[IFX_GL_ENOMEM]

not enough memory to complete the operation Since this function does not return a special value if an error has occurred, to detect an error condition, the caller of this function must set ifx_gl_lc_errno() to zero before calling this function and check ifx_gl_lc_errno() after calling the function. For example,

  ifx_gl_lc_errno() = 0;

  value = ifx_gl_mbscoll(mbs1, mbs1_byte_length, mbs2, mbs2_byte_length);

  if ( ifx_gl_lc_errno() != 0 )
    /* Handle error */
  else if ( value < 0 )
    /* mbs1 is less than mbs2 */
  else if ( value == 0 )
    /* mbs1 is equal to mbs2 */
  else if ( value > 0 )
    /* mbs1 is greater than mbs2 */
  ...

ACKNOWLEDGEMENT