Manual Pages for UNIX Operating System command usage for man u8_strcmp

Standard C Library Functions                        u8_strcmp(3C)



NAME
     u8_strcmp - UTF-8 string comparison function

SYNOPSIS
     #include 

     int u8_strcmp(const char *s1, const char *s2, size_t n,
          int flag, size_t version, int *errnum);


PARAMETERS
     s1, s2       Pointers to null-terminated UTF-8 strings


     n            The maximum number of bytes to be compared.  If
                  0,  the comparison is performed until either or
                  both of the strings are examined to the  string
                  terminating null byte.


     flag         The possible comparison options constructed  by
                  a   bit-wise-inclusive-OR   of   the  following
                  values:

                  U8_STRCMP_CS

                      Perform case-sensitive  string  comparison.
                      This is the default.


                  U8_STRCMP_CI_UPPER

                      Perform case-insensitive string  comparison
                      based   on  Unicode  upper  case  converted
                      results of s1 and s2.


                  U8_STRCMP_CI_LOWER

                      Perform case-insensitive string  comparison
                      based   on  Unicode  lower  case  converted
                      results of s1 and s2.


                  U8_STRCMP_NFD

                      Perform string comparison after s1  and  s2
                      have  been normalized by using Unicode Nor-
                      malization Form D.






SunOS 5.11          Last change: 12 Sep 2007                    1






Standard C Library Functions                        u8_strcmp(3C)



                  U8_STRCMP_NFC

                      Perform string comparison after s1  and  s2
                      have  been normalized by using Unicode Nor-
                      malization Form C.


                  U8_STRCMP_NFKD

                      Perform string comparison after s1  and  s2
                      have  been normalized by using Unicode Nor-
                      malization Form KD.


                  U8_STRCMP_NFKC

                      Perform string comparison after s1  and  s2
                      have  been normalized by using Unicode Nor-
                      malization Form KC.

                  Only  one  case-sensitive  or  case-insensitive
                  option  is allowed. Only one Unicode Normaliza-
                  tion option is allowed.


     version      The version of Unicode data that should be used
                  during  comparison.  The  following  values are
                  supported:

                  U8_UNICODE_320

                      Use Unicode 3.2.0 data during comparison.


                  U8_UNICODE_500

                      Use Unicode 5.0.0 data during comparison.


                  U8_UNICODE_LATEST

                      Use the latest Unicode version data  avail-
                      able, which is Unicode 5.0.0.



     errnum       A non-zero value indicates that  an  error  has
                  occurred   during   comparison.  The  following
                  values are supported:

                  EBADF     The specified option values are  con-
                            flicting and cannot be supported.



SunOS 5.11          Last change: 12 Sep 2007                    2






Standard C Library Functions                        u8_strcmp(3C)



                  EILSEQ    There was an illegal character at s1,
                            s2, or both.


                  EINVAL    There was an incomplete character  at
                            s1, s2, or both.


                  ERANGE    The specified Unicode  version  value
                            is not supported.



DESCRIPTION
     The u8_stcmp() function internally processes  UTF-8  strings
     pointed  to  by s1 and s2 based on the corresponding version
     of the Unicode Standard and other input arguments  and  com-
     pares the result strings in byte-by-byte, machine ordering.


     When multiple comparison options are specified, Unicode Nor-
     malization   is  performed  after  case-sensitive  or  case-
     insensitive processing is performed.

RETURN VALUES
     The u8_strcmp() function returns an  integer  greater  than,
     equal  to,  or less than 0 if the string pointed to by s1 is
     greater than, equal to, or less than the string  pointed  to
     by s2, respectively.


     When u8_strcmp() detects an illegal or incomplete character,
     such character causes the function to set errnum to indicate
     the error. Afterward, the comparison is still  performed  on
     the resultant strings and a value based on byte-by-byte com-
     parison is always returned.

EXAMPLES
     Example 1 Perform simple default string comparison.

       #include 

       int
       docmp_default(const char *u1, const char *u2) {
           int result;
           int errnum;

           result = u8_strcmp(u1, u2, 0, 0, U8_UNICODE_LATEST, &errnum);
           if (errnum == EILSEQ)
               return (-1);
           if (errnum == EINVAL)
               return (-2);



SunOS 5.11          Last change: 12 Sep 2007                    3






Standard C Library Functions                        u8_strcmp(3C)



           if (errnum == EBADF)
               return (-3);
           if (errnum == ERANGE)
               return (-4);


     Example 2 Perform upper  case  based  case-insensitive  com-
     parison with Unicode 3.2.0 date.

       #include 

       int
       docmp_caseinsensitive_u320(const char *u1, const char *u2) {
           int result;
           int errnum;

           result = u8_strcmp(u1, u2, 0, U8_STRCMP_CI_UPPER,
               U8_UNICODE_320, &errnum);
           if (errnum == EILSEQ)
               return (-1);
           if (errnum == EINVAL)
               return (-2);
           if (errnum == EBADF)
               return (-3);
           if (errnum == ERANGE)
               return (-4);

           return (result);
       }


     Example 3 Perform Unicode Normalization Form D.


     Perform Unicode Normalization Form D and  upper  case  based
     case-insensitive comparison with Unicode 3.2.0 date.


       #include 

       int
       docmp_nfd_caseinsensitive_u320(const char *u1, const char *u2) {
           int result;
           int errnum;

           result = u8_strcmp(u1, u2, 0,
               (U8_STRCMP_NFD|U8_STRCMP_CI_UPPER), U8_UNICODE_320,
               &errnum);
           if (errnum == EILSEQ)
               return (-1);
           if (errnum == EINVAL)
               return (-2);



SunOS 5.11          Last change: 12 Sep 2007                    4






Standard C Library Functions                        u8_strcmp(3C)



           if (errnum == EBADF)
               return (-3);
           if (errnum == ERANGE)
               return (-4);

           return (result);
       }


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|


SEE ALSO
     u8_textprep_str(3C),     u8_validate(3C),     attributes(5),
     u8_strcmp(9F), u8_textprep_str(9F), u8_validate(9F)


     The Unicode Standard (http://www.unicode.org)

























SunOS 5.11          Last change: 12 Sep 2007                    5