Tribblix: manual page: u8

U8_STRCMP(3C) Standard C Library Functions U8_STRCMP(3C)

NAME

u8_strcmp - UTF-8 string comparison function

SYNOPSIS

#include <sys/u8_textprep.h>

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 Normalization Form D.

U8_STRCMP_NFC

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

U8_STRCMP_NFKD

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

U8_STRCMP_NFKC

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

Only one case-sensitive or case-insensitive option is
allowed. Only one Unicode Normalization 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 available, 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 conflicting
and cannot be supported.

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 compares the result strings in
byte-by-byte, machine ordering.

When multiple comparison options are specified, Unicode Normalization
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 comparison is always returned.

EXAMPLES

Example 1: Perform simple default string comparison.

#include <sys/u8_textprep.h>

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);
if (errnum == EBADF)
return (-3);
if (errnum == ERANGE)
return (-4);

Example 2: Perform upper case based case-insensitive comparison with

Unicode 3.2.0 date.

#include <sys/u8_textprep.h>

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 <sys/u8_textprep.h>

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);
if (errnum == EBADF)
return (-3);
if (errnum == ERANGE)
return (-4);

return (result);
}

ATTRIBUTES