ifx_gl_wcscoll

ifx_gl_wcscoll - wide-character string comparison using collating information

SYNOPSIS


#include <ifxgls.h>
int ifx_gl_wcscoll(gl_wchar_t *wcs1, int wcs1_char_length,
                   gl_wchar_t *wcs2, int wcs2_char_length)

DESCRIPTION

This function compares the wide-character strings wcs1 and wcs2 according to the rules of the current locale.

If wcs1_char_length is the value IFX_GL_NULL then the function will assume that wcs1 is a null-terminated string; otherwise the function assumes that wcs1_char_length is the number of characters in wcs1. If wcs2_char_length is the value IFX_GL_NULL then the function will assume that wcs2 is a null-terminated string; otherwise the function assumes that wcs2_char_length is the number of characters in wcs2. See Wide-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 wcs1 is greater than, equal to, or less than wcs2, 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 wcs1_char_length is not equal to IFX_GL_NULL and is not greater than or equal to zero, or wcs2_char_length is not equal to IFX_GL_NULL and is not greater than or equal to zero.
[IFX_GL_TERMMISMAT]: Either wcs1_char_length is equal to IFX_GL_NULL and wcs2_char_length is greater than or equal to zero or wcs1_char_length is greater than or equal to zero and wcs2_char_length is equal to IFX_GL_NULL
[IFX_GL_EILSEQ]: Either wcs1 or wcs2 contains an invalid wide-character
[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_wcscoll(wcs1, wcs1_char_length, wcs2, wcs2_char_length);

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

ACKNOWLEDGEMENT