usr/src/man/man3c/u8_strcmp.3c

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH U8_STRCMP 3C "Sep 12, 2007"
   7 .SH NAME
   8 u8_strcmp \- UTF-8 string comparison function
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/u8_textprep.h>
  13
  14 \fBint\fR \fBu8_strcmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR,
  15      \fBint\fR \fIflag\fR, \fBsize_t\fR \fIversion\fR, \fBint *\fR\fIerrnum\fR);
  16 .fi
  17
  18 .SH PARAMETERS
  19 .sp
  20 .ne 2
  21 .na
  22 \fB\fIs1\fR, \fIs2\fR\fR
  23 .ad
  24 .RS 13n
  25 Pointers to null-terminated UTF-8 strings
  26 .RE
  27
  28 .sp
  29 .ne 2
  30 .na
  31 \fB\fIn\fR\fR
  32 .ad
  33 .RS 13n
  34 The maximum number of bytes to be compared.  If 0, the comparison is performed
  35 until either or both of the strings are examined to the string terminating null
  36 byte.
  37 .RE
  38
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fIflag\fR\fR
  43 .ad
  44 .RS 13n
  45 The possible comparison options constructed by a bit-wise-inclusive-OR of the
  46 following values:
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fBU8_STRCMP_CS\fR\fR
  51 .ad
  52 .sp .6
  53 .RS 4n
  54 Perform case-sensitive string comparison. This is the default.
  55 .RE
  56
  57 .sp
  58 .ne 2
  59 .na
  60 \fB\fBU8_STRCMP_CI_UPPER\fR\fR
  61 .ad
  62 .sp .6
  63 .RS 4n
  64 Perform case-insensitive string comparison based on Unicode upper case
  65 converted results of \fIs1\fR and \fIs2\fR.
  66 .RE
  67
  68 .sp
  69 .ne 2
  70 .na
  71 \fB\fBU8_STRCMP_CI_LOWER\fR\fR
  72 .ad
  73 .sp .6
  74 .RS 4n
  75 Perform case-insensitive string comparison based on Unicode lower case
  76 converted results of \fIs1\fR and \fIs2\fR.
  77 .RE
  78
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fBU8_STRCMP_NFD\fR\fR
  83 .ad
  84 .sp .6
  85 .RS 4n
  86 Perform string comparison after \fIs1\fR and \fIs2\fR have been normalized by
  87 using Unicode Normalization Form D.
  88 .RE
  89
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fBU8_STRCMP_NFC\fR\fR
  94 .ad
  95 .sp .6
  96 .RS 4n
  97 Perform string comparison after \fIs1\fR and \fIs2\fR have been normalized by
  98 using Unicode Normalization Form C.
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fBU8_STRCMP_NFKD\fR\fR
 105 .ad
 106 .sp .6
 107 .RS 4n
 108 Perform string comparison after \fIs1\fR and \fIs2\fR have been normalized by
 109 using Unicode Normalization Form KD.
 110 .RE
 111
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fBU8_STRCMP_NFKC\fR\fR
 116 .ad
 117 .sp .6
 118 .RS 4n
 119 Perform string comparison after \fIs1\fR and \fIs2\fR have been normalized by
 120 using Unicode Normalization Form KC.
 121 .RE
 122
 123 Only one case-sensitive or case-insensitive option is allowed. Only one Unicode
 124 Normalization option is allowed.
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fIversion\fR\fR
 131 .ad
 132 .RS 13n
 133 The version of Unicode data that should be used during comparison. The
 134 following values are supported:
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fBU8_UNICODE_320\fR\fR
 139 .ad
 140 .sp .6
 141 .RS 4n
 142 Use Unicode 3.2.0 data during comparison.
 143 .RE
 144
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fBU8_UNICODE_500\fR\fR
 149 .ad
 150 .sp .6
 151 .RS 4n
 152 Use Unicode 5.0.0 data during comparison.
 153 .RE
 154
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBU8_UNICODE_LATEST\fR\fR
 159 .ad
 160 .sp .6
 161 .RS 4n
 162 Use the latest Unicode version data available, which is Unicode 5.0.0.
 163 .RE
 164
 165 .RE
 166
 167 .sp
 168 .ne 2
 169 .na
 170 \fB\fIerrnum\fR\fR
 171 .ad
 172 .RS 13n
 173 A non-zero value indicates that an error has occurred during comparison. The
 174 following values are supported:
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fBEBADF\fR\fR
 179 .ad
 180 .RS 10n
 181 The specified option values are conflicting and cannot be supported.
 182 .RE
 183
 184 .sp
 185 .ne 2
 186 .na
 187 \fB\fBEILSEQ\fR\fR
 188 .ad
 189 .RS 10n
 190 There was an illegal character at \fIs1\fR, \fIs2\fR, or both.
 191 .RE
 192
 193 .sp
 194 .ne 2
 195 .na
 196 \fB\fBEINVAL\fR\fR
 197 .ad
 198 .RS 10n
 199 There was an incomplete character at \fIs1\fR, \fIs2\fR, or both.
 200 .RE
 201
 202 .sp
 203 .ne 2
 204 .na
 205 \fB\fBERANGE\fR\fR
 206 .ad
 207 .RS 10n
 208 The specified Unicode version value is not supported.
 209 .RE
 210
 211 .RE
 212
 213 .SH DESCRIPTION
 214 .sp
 215 .LP
 216 The \fBu8_stcmp()\fR function internally processes UTF-8 strings pointed to by
 217 \fIs1\fR and \fIs2\fR based on the corresponding version of the Unicode
 218 Standard and other input arguments and compares the result strings in
 219 byte-by-byte, machine ordering.
 220 .sp
 221 .LP
 222 When multiple comparison options are specified, Unicode Normalization is
 223 performed after case-sensitive or case-insensitive processing is performed.
 224 .SH RETURN VALUES
 225 .sp
 226 .LP
 227 The \fBu8_strcmp()\fR function returns an integer greater than, equal to, or
 228 less than 0 if the string pointed to by \fIs1\fR is greater than, equal to, or
 229 less than the string pointed to by \fIs2\fR, respectively.
 230 .sp
 231 .LP
 232 When \fBu8_strcmp()\fR detects an illegal or incomplete character, such
 233 character causes the function to set \fIerrnum\fR to indicate the error.
 234 Afterward, the comparison is still performed on the resultant strings and a
 235 value based on byte-by-byte comparison is always returned.
 236 .SH EXAMPLES
 237 .LP
 238 \fBExample 1 \fRPerform simple default string comparison.
 239 .sp
 240 .in +2
 241 .nf
 242 #include <sys/u8_textprep.h>
 243
 244 int
 245 docmp_default(const char *u1, const char *u2) {
 246     int result;
 247     int errnum;
 248
 249     result = u8_strcmp(u1, u2, 0, 0, U8_UNICODE_LATEST, &errnum);
 250     if (errnum == EILSEQ)
 251         return (-1);
 252     if (errnum == EINVAL)
 253         return (-2);
 254     if (errnum == EBADF)
 255         return (-3);
 256     if (errnum == ERANGE)
 257         return (-4);
 258 .fi
 259 .in -2
 260
 261 .LP
 262 \fBExample 2 \fRPerform upper case based case-insensitive comparison with
 263 Unicode 3.2.0 date.
 264 .sp
 265 .in +2
 266 .nf
 267 #include <sys/u8_textprep.h>
 268
 269 int
 270 docmp_caseinsensitive_u320(const char *u1, const char *u2) {
 271     int result;
 272     int errnum;
 273
 274     result = u8_strcmp(u1, u2, 0, U8_STRCMP_CI_UPPER,
 275         U8_UNICODE_320, &errnum);
 276     if (errnum == EILSEQ)
 277         return (-1);
 278     if (errnum == EINVAL)
 279         return (-2);
 280     if (errnum == EBADF)
 281         return (-3);
 282     if (errnum == ERANGE)
 283         return (-4);
 284
 285     return (result);
 286 }
 287 .fi
 288 .in -2
 289
 290 .LP
 291 \fBExample 3 \fRPerform Unicode Normalization Form D.
 292 .sp
 293 .LP
 294 Perform Unicode Normalization Form D and upper case based case-insensitive
 295 comparison with Unicode 3.2.0 date.
 296
 297 .sp
 298 .in +2
 299 .nf
 300 #include <sys/u8_textprep.h>
 301
 302 int
 303 docmp_nfd_caseinsensitive_u320(const char *u1, const char *u2) {
 304     int result;
 305     int errnum;
 306
 307     result = u8_strcmp(u1, u2, 0,
 308         (U8_STRCMP_NFD|U8_STRCMP_CI_UPPER), U8_UNICODE_320,
 309         &errnum);
 310     if (errnum == EILSEQ)
 311         return (-1);
 312     if (errnum == EINVAL)
 313         return (-2);
 314     if (errnum == EBADF)
 315         return (-3);
 316     if (errnum == ERANGE)
 317         return (-4);
 318
 319     return (result);
 320 }
 321 .fi
 322 .in -2
 323
 324 .SH ATTRIBUTES
 325 .sp
 326 .LP
 327 See \fBattributes\fR(5) for descriptions of the following attributes:
 328 .sp
 329
 330 .sp
 331 .TS
 332 box;
 333 c | c
 334 l | l .
 335 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 336 _
 337 Interface Stability     Committed
 338 _
 339 MT-Level        MT-Safe
 340 .TE
 341
 342 .SH SEE ALSO
 343 .sp
 344 .LP
 345 \fBu8_textprep_str\fR(3C), \fBu8_validate\fR(3C), \fBattributes\fR(5),
 346 \fBu8_strcmp\fR(9F), \fBu8_textprep_str\fR(9F), \fBu8_validate\fR(9F)
 347 .sp
 348 .LP
 349 The Unicode Standard (http://www.unicode.org)