1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ********************************************************************** 5 * Copyright (C) 1998-2014, International Business Machines 6 * Corporation and others. All Rights Reserved. 7 ********************************************************************** 8 * 9 * File ustring.h 10 * 11 * Modification History: 12 * 13 * Date Name Description 14 * 12/07/98 bertrand Creation. 15 ****************************************************************************** 16 */ 17 18 #ifndef USTRING_H 19 #define USTRING_H 20 21 #include "unicode/utypes.h" 22 #include "unicode/putil.h" 23 #include "unicode/uiter.h" 24 25 /** 26 * \def UBRK_TYPEDEF_UBREAK_ITERATOR 27 * @internal 28 */ 29 30 #ifndef UBRK_TYPEDEF_UBREAK_ITERATOR 31 # define UBRK_TYPEDEF_UBREAK_ITERATOR 32 /** Simple declaration for u_strToTitle() to avoid including unicode/ubrk.h. @stable ICU 2.1*/ 33 typedef struct UBreakIterator UBreakIterator; 34 #endif 35 36 /** 37 * \file 38 * \brief C API: Unicode string handling functions 39 * 40 * These C API functions provide general Unicode string handling. 41 * 42 * Some functions are equivalent in name, signature, and behavior to the ANSI C <string.h> 43 * functions. (For example, they do not check for bad arguments like NULL string pointers.) 44 * In some cases, only the thread-safe variant of such a function is implemented here 45 * (see u_strtok_r()). 46 * 47 * Other functions provide more Unicode-specific functionality like locale-specific 48 * upper/lower-casing and string comparison in code point order. 49 * 50 * ICU uses 16-bit Unicode (UTF-16) in the form of arrays of UChar code units. 51 * UTF-16 encodes each Unicode code point with either one or two UChar code units. 52 * (This is the default form of Unicode, and a forward-compatible extension of the original, 53 * fixed-width form that was known as UCS-2. UTF-16 superseded UCS-2 with Unicode 2.0 54 * in 1996.) 55 * 56 * Some APIs accept a 32-bit UChar32 value for a single code point. 57 * 58 * ICU also handles 16-bit Unicode text with unpaired surrogates. 59 * Such text is not well-formed UTF-16. 60 * Code-point-related functions treat unpaired surrogates as surrogate code points, 61 * i.e., as separate units. 62 * 63 * Although UTF-16 is a variable-width encoding form (like some legacy multi-byte encodings), 64 * it is much more efficient even for random access because the code unit values 65 * for single-unit characters vs. lead units vs. trail units are completely disjoint. 66 * This means that it is easy to determine character (code point) boundaries from 67 * random offsets in the string. 68 * 69 * Unicode (UTF-16) string processing is optimized for the single-unit case. 70 * Although it is important to support supplementary characters 71 * (which use pairs of lead/trail code units called "surrogates"), 72 * their occurrence is rare. Almost all characters in modern use require only 73 * a single UChar code unit (i.e., their code point values are <=0xffff). 74 * 75 * For more details see the User Guide Strings chapter (https://unicode-org.github.io/icu/userguide/strings/). 76 * For a discussion of the handling of unpaired surrogates see also 77 * Jitterbug 2145 and its icu mailing list proposal on 2002-sep-18. 78 */ 79 80 /** 81 * Determine the length of an array of UChar. 82 * 83 * @param s The array of UChars, NULL (U+0000) terminated. 84 * @return The number of UChars in <code>chars</code>, minus the terminator. 85 * @stable ICU 2.0 86 */ 87 U_CAPI int32_t U_EXPORT2 88 u_strlen(const UChar *s); 89 90 /** 91 * Count Unicode code points in the length UChar code units of the string. 92 * A code point may occupy either one or two UChar code units. 93 * Counting code points involves reading all code units. 94 * 95 * This functions is basically the inverse of the U16_FWD_N() macro (see utf.h). 96 * 97 * @param s The input string. 98 * @param length The number of UChar code units to be checked, or -1 to count all 99 * code points before the first NUL (U+0000). 100 * @return The number of code points in the specified code units. 101 * @stable ICU 2.0 102 */ 103 U_CAPI int32_t U_EXPORT2 104 u_countChar32(const UChar *s, int32_t length); 105 106 /** 107 * Check if the string contains more Unicode code points than a certain number. 108 * This is more efficient than counting all code points in the entire string 109 * and comparing that number with a threshold. 110 * This function may not need to scan the string at all if the length is known 111 * (not -1 for NUL-termination) and falls within a certain range, and 112 * never needs to count more than 'number+1' code points. 113 * Logically equivalent to (u_countChar32(s, length)>number). 114 * A Unicode code point may occupy either one or two UChar code units. 115 * 116 * @param s The input string. 117 * @param length The length of the string, or -1 if it is NUL-terminated. 118 * @param number The number of code points in the string is compared against 119 * the 'number' parameter. 120 * @return Boolean value for whether the string contains more Unicode code points 121 * than 'number'. Same as (u_countChar32(s, length)>number). 122 * @stable ICU 2.4 123 */ 124 U_CAPI UBool U_EXPORT2 125 u_strHasMoreChar32Than(const UChar *s, int32_t length, int32_t number); 126 127 /** 128 * Concatenate two ustrings. Appends a copy of <code>src</code>, 129 * including the null terminator, to <code>dst</code>. The initial copied 130 * character from <code>src</code> overwrites the null terminator in <code>dst</code>. 131 * 132 * @param dst The destination string. 133 * @param src The source string. 134 * @return A pointer to <code>dst</code>. 135 * @stable ICU 2.0 136 */ 137 U_CAPI UChar* U_EXPORT2 138 u_strcat(UChar *dst, 139 const UChar *src); 140 141 /** 142 * Concatenate two ustrings. 143 * Appends at most <code>n</code> characters from <code>src</code> to <code>dst</code>. 144 * Adds a terminating NUL. 145 * If src is too long, then only <code>n-1</code> characters will be copied 146 * before the terminating NUL. 147 * If <code>n<=0</code> then dst is not modified. 148 * 149 * @param dst The destination string. 150 * @param src The source string (can be NULL/invalid if n<=0). 151 * @param n The maximum number of characters to append; no-op if <=0. 152 * @return A pointer to <code>dst</code>. 153 * @stable ICU 2.0 154 */ 155 U_CAPI UChar* U_EXPORT2 156 u_strncat(UChar *dst, 157 const UChar *src, 158 int32_t n); 159 160 /** 161 * Find the first occurrence of a substring in a string. 162 * The substring is found at code point boundaries. 163 * That means that if the substring begins with 164 * a trail surrogate or ends with a lead surrogate, 165 * then it is found only if these surrogates stand alone in the text. 166 * Otherwise, the substring edge units would be matched against 167 * halves of surrogate pairs. 168 * 169 * @param s The string to search (NUL-terminated). 170 * @param substring The substring to find (NUL-terminated). 171 * @return A pointer to the first occurrence of <code>substring</code> in <code>s</code>, 172 * or <code>s</code> itself if the <code>substring</code> is empty, 173 * or <code>NULL</code> if <code>substring</code> is not in <code>s</code>. 174 * @stable ICU 2.0 175 * 176 * @see u_strrstr 177 * @see u_strFindFirst 178 * @see u_strFindLast 179 */ 180 U_CAPI UChar * U_EXPORT2 181 u_strstr(const UChar *s, const UChar *substring); 182 183 /** 184 * Find the first occurrence of a substring in a string. 185 * The substring is found at code point boundaries. 186 * That means that if the substring begins with 187 * a trail surrogate or ends with a lead surrogate, 188 * then it is found only if these surrogates stand alone in the text. 189 * Otherwise, the substring edge units would be matched against 190 * halves of surrogate pairs. 191 * 192 * @param s The string to search. 193 * @param length The length of s (number of UChars), or -1 if it is NUL-terminated. 194 * @param substring The substring to find (NUL-terminated). 195 * @param subLength The length of substring (number of UChars), or -1 if it is NUL-terminated. 196 * @return A pointer to the first occurrence of <code>substring</code> in <code>s</code>, 197 * or <code>s</code> itself if the <code>substring</code> is empty, 198 * or <code>NULL</code> if <code>substring</code> is not in <code>s</code>. 199 * @stable ICU 2.4 200 * 201 * @see u_strstr 202 * @see u_strFindLast 203 */ 204 U_CAPI UChar * U_EXPORT2 205 u_strFindFirst(const UChar *s, int32_t length, const UChar *substring, int32_t subLength); 206 207 /** 208 * Find the first occurrence of a BMP code point in a string. 209 * A surrogate code point is found only if its match in the text is not 210 * part of a surrogate pair. 211 * A NUL character is found at the string terminator. 212 * 213 * @param s The string to search (NUL-terminated). 214 * @param c The BMP code point to find. 215 * @return A pointer to the first occurrence of <code>c</code> in <code>s</code> 216 * or <code>NULL</code> if <code>c</code> is not in <code>s</code>. 217 * @stable ICU 2.0 218 * 219 * @see u_strchr32 220 * @see u_memchr 221 * @see u_strstr 222 * @see u_strFindFirst 223 */ 224 U_CAPI UChar * U_EXPORT2 225 u_strchr(const UChar *s, UChar c); 226 227 /** 228 * Find the first occurrence of a code point in a string. 229 * A surrogate code point is found only if its match in the text is not 230 * part of a surrogate pair. 231 * A NUL character is found at the string terminator. 232 * 233 * @param s The string to search (NUL-terminated). 234 * @param c The code point to find. 235 * @return A pointer to the first occurrence of <code>c</code> in <code>s</code> 236 * or <code>NULL</code> if <code>c</code> is not in <code>s</code>. 237 * @stable ICU 2.0 238 * 239 * @see u_strchr 240 * @see u_memchr32 241 * @see u_strstr 242 * @see u_strFindFirst 243 */ 244 U_CAPI UChar * U_EXPORT2 245 u_strchr32(const UChar *s, UChar32 c); 246 247 /** 248 * Find the last occurrence of a substring in a string. 249 * The substring is found at code point boundaries. 250 * That means that if the substring begins with 251 * a trail surrogate or ends with a lead surrogate, 252 * then it is found only if these surrogates stand alone in the text. 253 * Otherwise, the substring edge units would be matched against 254 * halves of surrogate pairs. 255 * 256 * @param s The string to search (NUL-terminated). 257 * @param substring The substring to find (NUL-terminated). 258 * @return A pointer to the last occurrence of <code>substring</code> in <code>s</code>, 259 * or <code>s</code> itself if the <code>substring</code> is empty, 260 * or <code>NULL</code> if <code>substring</code> is not in <code>s</code>. 261 * @stable ICU 2.4 262 * 263 * @see u_strstr 264 * @see u_strFindFirst 265 * @see u_strFindLast 266 */ 267 U_CAPI UChar * U_EXPORT2 268 u_strrstr(const UChar *s, const UChar *substring); 269 270 /** 271 * Find the last occurrence of a substring in a string. 272 * The substring is found at code point boundaries. 273 * That means that if the substring begins with 274 * a trail surrogate or ends with a lead surrogate, 275 * then it is found only if these surrogates stand alone in the text. 276 * Otherwise, the substring edge units would be matched against 277 * halves of surrogate pairs. 278 * 279 * @param s The string to search. 280 * @param length The length of s (number of UChars), or -1 if it is NUL-terminated. 281 * @param substring The substring to find (NUL-terminated). 282 * @param subLength The length of substring (number of UChars), or -1 if it is NUL-terminated. 283 * @return A pointer to the last occurrence of <code>substring</code> in <code>s</code>, 284 * or <code>s</code> itself if the <code>substring</code> is empty, 285 * or <code>NULL</code> if <code>substring</code> is not in <code>s</code>. 286 * @stable ICU 2.4 287 * 288 * @see u_strstr 289 * @see u_strFindLast 290 */ 291 U_CAPI UChar * U_EXPORT2 292 u_strFindLast(const UChar *s, int32_t length, const UChar *substring, int32_t subLength); 293 294 /** 295 * Find the last occurrence of a BMP code point in a string. 296 * A surrogate code point is found only if its match in the text is not 297 * part of a surrogate pair. 298 * A NUL character is found at the string terminator. 299 * 300 * @param s The string to search (NUL-terminated). 301 * @param c The BMP code point to find. 302 * @return A pointer to the last occurrence of <code>c</code> in <code>s</code> 303 * or <code>NULL</code> if <code>c</code> is not in <code>s</code>. 304 * @stable ICU 2.4 305 * 306 * @see u_strrchr32 307 * @see u_memrchr 308 * @see u_strrstr 309 * @see u_strFindLast 310 */ 311 U_CAPI UChar * U_EXPORT2 312 u_strrchr(const UChar *s, UChar c); 313 314 /** 315 * Find the last occurrence of a code point in a string. 316 * A surrogate code point is found only if its match in the text is not 317 * part of a surrogate pair. 318 * A NUL character is found at the string terminator. 319 * 320 * @param s The string to search (NUL-terminated). 321 * @param c The code point to find. 322 * @return A pointer to the last occurrence of <code>c</code> in <code>s</code> 323 * or <code>NULL</code> if <code>c</code> is not in <code>s</code>. 324 * @stable ICU 2.4 325 * 326 * @see u_strrchr 327 * @see u_memchr32 328 * @see u_strrstr 329 * @see u_strFindLast 330 */ 331 U_CAPI UChar * U_EXPORT2 332 u_strrchr32(const UChar *s, UChar32 c); 333 334 /** 335 * Locates the first occurrence in the string <code>string</code> of any of the characters 336 * in the string <code>matchSet</code>. 337 * Works just like C's strpbrk but with Unicode. 338 * 339 * @param string The string in which to search, NUL-terminated. 340 * @param matchSet A NUL-terminated string defining a set of code points 341 * for which to search in the text string. 342 * @return A pointer to the character in <code>string</code> that matches one of the 343 * characters in <code>matchSet</code>, or NULL if no such character is found. 344 * @stable ICU 2.0 345 */ 346 U_CAPI UChar * U_EXPORT2 347 u_strpbrk(const UChar *string, const UChar *matchSet); 348 349 /** 350 * Returns the number of consecutive characters in <code>string</code>, 351 * beginning with the first, that do not occur somewhere in <code>matchSet</code>. 352 * Works just like C's strcspn but with Unicode. 353 * 354 * @param string The string in which to search, NUL-terminated. 355 * @param matchSet A NUL-terminated string defining a set of code points 356 * for which to search in the text string. 357 * @return The number of initial characters in <code>string</code> that do not 358 * occur in <code>matchSet</code>. 359 * @see u_strspn 360 * @stable ICU 2.0 361 */ 362 U_CAPI int32_t U_EXPORT2 363 u_strcspn(const UChar *string, const UChar *matchSet); 364 365 /** 366 * Returns the number of consecutive characters in <code>string</code>, 367 * beginning with the first, that occur somewhere in <code>matchSet</code>. 368 * Works just like C's strspn but with Unicode. 369 * 370 * @param string The string in which to search, NUL-terminated. 371 * @param matchSet A NUL-terminated string defining a set of code points 372 * for which to search in the text string. 373 * @return The number of initial characters in <code>string</code> that do 374 * occur in <code>matchSet</code>. 375 * @see u_strcspn 376 * @stable ICU 2.0 377 */ 378 U_CAPI int32_t U_EXPORT2 379 u_strspn(const UChar *string, const UChar *matchSet); 380 381 /** 382 * The string tokenizer API allows an application to break a string into 383 * tokens. Unlike strtok(), the saveState (the current pointer within the 384 * original string) is maintained in saveState. In the first call, the 385 * argument src is a pointer to the string. In subsequent calls to 386 * return successive tokens of that string, src must be specified as 387 * NULL. The value saveState is set by this function to maintain the 388 * function's position within the string, and on each subsequent call 389 * you must give this argument the same variable. This function does 390 * handle surrogate pairs. This function is similar to the strtok_r() 391 * the POSIX Threads Extension (1003.1c-1995) version. 392 * 393 * @param src String containing token(s). This string will be modified. 394 * After the first call to u_strtok_r(), this argument must 395 * be NULL to get to the next token. 396 * @param delim Set of delimiter characters (Unicode code points). 397 * @param saveState The current pointer within the original string, 398 * which is set by this function. The saveState 399 * parameter should the address of a local variable of type 400 * UChar *. (i.e. defined "UChar *myLocalSaveState" and use 401 * &myLocalSaveState for this parameter). 402 * @return A pointer to the next token found in src, or NULL 403 * when there are no more tokens. 404 * @stable ICU 2.0 405 */ 406 U_CAPI UChar * U_EXPORT2 407 u_strtok_r(UChar *src, 408 const UChar *delim, 409 UChar **saveState); 410 411 /** 412 * Compare two Unicode strings for bitwise equality (code unit order). 413 * 414 * @param s1 A string to compare. 415 * @param s2 A string to compare. 416 * @return 0 if <code>s1</code> and <code>s2</code> are bitwise equal; a negative 417 * value if <code>s1</code> is bitwise less than <code>s2,</code>; a positive 418 * value if <code>s1</code> is bitwise greater than <code>s2</code>. 419 * @stable ICU 2.0 420 */ 421 U_CAPI int32_t U_EXPORT2 422 u_strcmp(const UChar *s1, 423 const UChar *s2); 424 425 /** 426 * Compare two Unicode strings in code point order. 427 * See u_strCompare for details. 428 * 429 * @param s1 A string to compare. 430 * @param s2 A string to compare. 431 * @return a negative/zero/positive integer corresponding to whether 432 * the first string is less than/equal to/greater than the second one 433 * in code point order 434 * @stable ICU 2.0 435 */ 436 U_CAPI int32_t U_EXPORT2 437 u_strcmpCodePointOrder(const UChar *s1, const UChar *s2); 438 439 /** 440 * Compare two Unicode strings (binary order). 441 * 442 * The comparison can be done in code unit order or in code point order. 443 * They differ only in UTF-16 when 444 * comparing supplementary code points (U+10000..U+10ffff) 445 * to BMP code points near the end of the BMP (i.e., U+e000..U+ffff). 446 * In code unit order, high BMP code points sort after supplementary code points 447 * because they are stored as pairs of surrogates which are at U+d800..U+dfff. 448 * 449 * This functions works with strings of different explicitly specified lengths 450 * unlike the ANSI C-like u_strcmp() and u_memcmp() etc. 451 * NUL-terminated strings are possible with length arguments of -1. 452 * 453 * @param s1 First source string. 454 * @param length1 Length of first source string, or -1 if NUL-terminated. 455 * 456 * @param s2 Second source string. 457 * @param length2 Length of second source string, or -1 if NUL-terminated. 458 * 459 * @param codePointOrder Choose between code unit order (false) 460 * and code point order (true). 461 * 462 * @return <0 or 0 or >0 as usual for string comparisons 463 * 464 * @stable ICU 2.2 465 */ 466 U_CAPI int32_t U_EXPORT2 467 u_strCompare(const UChar *s1, int32_t length1, 468 const UChar *s2, int32_t length2, 469 UBool codePointOrder); 470 471 /** 472 * Compare two Unicode strings (binary order) 473 * as presented by UCharIterator objects. 474 * Works otherwise just like u_strCompare(). 475 * 476 * Both iterators are reset to their start positions. 477 * When the function returns, it is undefined where the iterators 478 * have stopped. 479 * 480 * @param iter1 First source string iterator. 481 * @param iter2 Second source string iterator. 482 * @param codePointOrder Choose between code unit order (false) 483 * and code point order (true). 484 * 485 * @return <0 or 0 or >0 as usual for string comparisons 486 * 487 * @see u_strCompare 488 * 489 * @stable ICU 2.6 490 */ 491 U_CAPI int32_t U_EXPORT2 492 u_strCompareIter(UCharIterator *iter1, UCharIterator *iter2, UBool codePointOrder); 493 494 /** 495 * Compare two strings case-insensitively using full case folding. 496 * This is equivalent to 497 * u_strCompare(u_strFoldCase(s1, options), 498 * u_strFoldCase(s2, options), 499 * (options&U_COMPARE_CODE_POINT_ORDER)!=0). 500 * 501 * The comparison can be done in UTF-16 code unit order or in code point order. 502 * They differ only when comparing supplementary code points (U+10000..U+10ffff) 503 * to BMP code points near the end of the BMP (i.e., U+e000..U+ffff). 504 * In code unit order, high BMP code points sort after supplementary code points 505 * because they are stored as pairs of surrogates which are at U+d800..U+dfff. 506 * 507 * This functions works with strings of different explicitly specified lengths 508 * unlike the ANSI C-like u_strcmp() and u_memcmp() etc. 509 * NUL-terminated strings are possible with length arguments of -1. 510 * 511 * @param s1 First source string. 512 * @param length1 Length of first source string, or -1 if NUL-terminated. 513 * 514 * @param s2 Second source string. 515 * @param length2 Length of second source string, or -1 if NUL-terminated. 516 * 517 * @param options A bit set of options: 518 * - U_FOLD_CASE_DEFAULT or 0 is used for default options: 519 * Comparison in code unit order with default case folding. 520 * 521 * - U_COMPARE_CODE_POINT_ORDER 522 * Set to choose code point order instead of code unit order 523 * (see u_strCompare for details). 524 * 525 * - U_FOLD_CASE_EXCLUDE_SPECIAL_I 526 * 527 * @param pErrorCode Must be a valid pointer to an error code value, 528 * which must not indicate a failure before the function call. 529 * 530 * @return <0 or 0 or >0 as usual for string comparisons 531 * 532 * @stable ICU 2.2 533 */ 534 U_CAPI int32_t U_EXPORT2 535 u_strCaseCompare(const UChar *s1, int32_t length1, 536 const UChar *s2, int32_t length2, 537 uint32_t options, 538 UErrorCode *pErrorCode); 539 540 /** 541 * Compare two ustrings for bitwise equality. 542 * Compares at most <code>n</code> characters. 543 * 544 * @param ucs1 A string to compare (can be NULL/invalid if n<=0). 545 * @param ucs2 A string to compare (can be NULL/invalid if n<=0). 546 * @param n The maximum number of characters to compare; always returns 0 if n<=0. 547 * @return 0 if <code>s1</code> and <code>s2</code> are bitwise equal; a negative 548 * value if <code>s1</code> is bitwise less than <code>s2</code>; a positive 549 * value if <code>s1</code> is bitwise greater than <code>s2</code>. 550 * @stable ICU 2.0 551 */ 552 U_CAPI int32_t U_EXPORT2 553 u_strncmp(const UChar *ucs1, 554 const UChar *ucs2, 555 int32_t n); 556 557 /** 558 * Compare two Unicode strings in code point order. 559 * This is different in UTF-16 from u_strncmp() if supplementary characters are present. 560 * For details, see u_strCompare(). 561 * 562 * @param s1 A string to compare. 563 * @param s2 A string to compare. 564 * @param n The maximum number of characters to compare. 565 * @return a negative/zero/positive integer corresponding to whether 566 * the first string is less than/equal to/greater than the second one 567 * in code point order 568 * @stable ICU 2.0 569 */ 570 U_CAPI int32_t U_EXPORT2 571 u_strncmpCodePointOrder(const UChar *s1, const UChar *s2, int32_t n); 572 573 /** 574 * Compare two strings case-insensitively using full case folding. 575 * This is equivalent to u_strcmp(u_strFoldCase(s1, options), u_strFoldCase(s2, options)). 576 * 577 * @param s1 A string to compare. 578 * @param s2 A string to compare. 579 * @param options A bit set of options: 580 * - U_FOLD_CASE_DEFAULT or 0 is used for default options: 581 * Comparison in code unit order with default case folding. 582 * 583 * - U_COMPARE_CODE_POINT_ORDER 584 * Set to choose code point order instead of code unit order 585 * (see u_strCompare for details). 586 * 587 * - U_FOLD_CASE_EXCLUDE_SPECIAL_I 588 * 589 * @return A negative, zero, or positive integer indicating the comparison result. 590 * @stable ICU 2.0 591 */ 592 U_CAPI int32_t U_EXPORT2 593 u_strcasecmp(const UChar *s1, const UChar *s2, uint32_t options); 594 595 /** 596 * Compare two strings case-insensitively using full case folding. 597 * This is equivalent to u_strcmp(u_strFoldCase(s1, at most n, options), 598 * u_strFoldCase(s2, at most n, options)). 599 * 600 * @param s1 A string to compare. 601 * @param s2 A string to compare. 602 * @param n The maximum number of characters each string to case-fold and then compare. 603 * @param options A bit set of options: 604 * - U_FOLD_CASE_DEFAULT or 0 is used for default options: 605 * Comparison in code unit order with default case folding. 606 * 607 * - U_COMPARE_CODE_POINT_ORDER 608 * Set to choose code point order instead of code unit order 609 * (see u_strCompare for details). 610 * 611 * - U_FOLD_CASE_EXCLUDE_SPECIAL_I 612 * 613 * @return A negative, zero, or positive integer indicating the comparison result. 614 * @stable ICU 2.0 615 */ 616 U_CAPI int32_t U_EXPORT2 617 u_strncasecmp(const UChar *s1, const UChar *s2, int32_t n, uint32_t options); 618 619 /** 620 * Compare two strings case-insensitively using full case folding. 621 * This is equivalent to u_strcmp(u_strFoldCase(s1, n, options), 622 * u_strFoldCase(s2, n, options)). 623 * 624 * @param s1 A string to compare. 625 * @param s2 A string to compare. 626 * @param length The number of characters in each string to case-fold and then compare. 627 * @param options A bit set of options: 628 * - U_FOLD_CASE_DEFAULT or 0 is used for default options: 629 * Comparison in code unit order with default case folding. 630 * 631 * - U_COMPARE_CODE_POINT_ORDER 632 * Set to choose code point order instead of code unit order 633 * (see u_strCompare for details). 634 * 635 * - U_FOLD_CASE_EXCLUDE_SPECIAL_I 636 * 637 * @return A negative, zero, or positive integer indicating the comparison result. 638 * @stable ICU 2.0 639 */ 640 U_CAPI int32_t U_EXPORT2 641 u_memcasecmp(const UChar *s1, const UChar *s2, int32_t length, uint32_t options); 642 643 /** 644 * Copy a ustring. Adds a null terminator. 645 * 646 * @param dst The destination string. 647 * @param src The source string. 648 * @return A pointer to <code>dst</code>. 649 * @stable ICU 2.0 650 */ 651 U_CAPI UChar* U_EXPORT2 652 u_strcpy(UChar *dst, 653 const UChar *src); 654 655 /** 656 * Copy a ustring. 657 * Copies at most <code>n</code> characters. The result will be null terminated 658 * if the length of <code>src</code> is less than <code>n</code>. 659 * 660 * @param dst The destination string. 661 * @param src The source string (can be NULL/invalid if n<=0). 662 * @param n The maximum number of characters to copy; no-op if <=0. 663 * @return A pointer to <code>dst</code>. 664 * @stable ICU 2.0 665 */ 666 U_CAPI UChar* U_EXPORT2 667 u_strncpy(UChar *dst, 668 const UChar *src, 669 int32_t n); 670 671 #if !UCONFIG_NO_CONVERSION 672 673 /** 674 * Copy a byte string encoded in the default codepage to a ustring. 675 * Adds a null terminator. 676 * Performs a host byte to UChar conversion 677 * 678 * @param dst The destination string. 679 * @param src The source string. 680 * @return A pointer to <code>dst</code>. 681 * @stable ICU 2.0 682 */ 683 U_CAPI UChar* U_EXPORT2 u_uastrcpy(UChar *dst, 684 const char *src ); 685 686 /** 687 * Copy a byte string encoded in the default codepage to a ustring. 688 * Copies at most <code>n</code> characters. The result will be null terminated 689 * if the length of <code>src</code> is less than <code>n</code>. 690 * Performs a host byte to UChar conversion 691 * 692 * @param dst The destination string. 693 * @param src The source string. 694 * @param n The maximum number of characters to copy. 695 * @return A pointer to <code>dst</code>. 696 * @stable ICU 2.0 697 */ 698 U_CAPI UChar* U_EXPORT2 u_uastrncpy(UChar *dst, 699 const char *src, 700 int32_t n); 701 702 /** 703 * Copy ustring to a byte string encoded in the default codepage. 704 * Adds a null terminator. 705 * Performs a UChar to host byte conversion 706 * 707 * @param dst The destination string. 708 * @param src The source string. 709 * @return A pointer to <code>dst</code>. 710 * @stable ICU 2.0 711 */ 712 U_CAPI char* U_EXPORT2 u_austrcpy(char *dst, 713 const UChar *src ); 714 715 /** 716 * Copy ustring to a byte string encoded in the default codepage. 717 * Copies at most <code>n</code> characters. The result will be null terminated 718 * if the length of <code>src</code> is less than <code>n</code>. 719 * Performs a UChar to host byte conversion 720 * 721 * @param dst The destination string. 722 * @param src The source string. 723 * @param n The maximum number of characters to copy. 724 * @return A pointer to <code>dst</code>. 725 * @stable ICU 2.0 726 */ 727 U_CAPI char* U_EXPORT2 u_austrncpy(char *dst, 728 const UChar *src, 729 int32_t n ); 730 731 #endif 732 733 /** 734 * Synonym for memcpy(), but with UChars only. 735 * @param dest The destination string 736 * @param src The source string (can be NULL/invalid if count<=0) 737 * @param count The number of characters to copy; no-op if <=0 738 * @return A pointer to <code>dest</code> 739 * @stable ICU 2.0 740 */ 741 U_CAPI UChar* U_EXPORT2 742 u_memcpy(UChar *dest, const UChar *src, int32_t count); 743 744 /** 745 * Synonym for memmove(), but with UChars only. 746 * @param dest The destination string 747 * @param src The source string (can be NULL/invalid if count<=0) 748 * @param count The number of characters to move; no-op if <=0 749 * @return A pointer to <code>dest</code> 750 * @stable ICU 2.0 751 */ 752 U_CAPI UChar* U_EXPORT2 753 u_memmove(UChar *dest, const UChar *src, int32_t count); 754 755 /** 756 * Initialize <code>count</code> characters of <code>dest</code> to <code>c</code>. 757 * 758 * @param dest The destination string. 759 * @param c The character to initialize the string. 760 * @param count The maximum number of characters to set. 761 * @return A pointer to <code>dest</code>. 762 * @stable ICU 2.0 763 */ 764 U_CAPI UChar* U_EXPORT2 765 u_memset(UChar *dest, UChar c, int32_t count); 766 767 /** 768 * Compare the first <code>count</code> UChars of each buffer. 769 * 770 * @param buf1 The first string to compare. 771 * @param buf2 The second string to compare. 772 * @param count The maximum number of UChars to compare. 773 * @return When buf1 < buf2, a negative number is returned. 774 * When buf1 == buf2, 0 is returned. 775 * When buf1 > buf2, a positive number is returned. 776 * @stable ICU 2.0 777 */ 778 U_CAPI int32_t U_EXPORT2 779 u_memcmp(const UChar *buf1, const UChar *buf2, int32_t count); 780 781 /** 782 * Compare two Unicode strings in code point order. 783 * This is different in UTF-16 from u_memcmp() if supplementary characters are present. 784 * For details, see u_strCompare(). 785 * 786 * @param s1 A string to compare. 787 * @param s2 A string to compare. 788 * @param count The maximum number of characters to compare. 789 * @return a negative/zero/positive integer corresponding to whether 790 * the first string is less than/equal to/greater than the second one 791 * in code point order 792 * @stable ICU 2.0 793 */ 794 U_CAPI int32_t U_EXPORT2 795 u_memcmpCodePointOrder(const UChar *s1, const UChar *s2, int32_t count); 796 797 /** 798 * Find the first occurrence of a BMP code point in a string. 799 * A surrogate code point is found only if its match in the text is not 800 * part of a surrogate pair. 801 * A NUL character is found at the string terminator. 802 * 803 * @param s The string to search (contains <code>count</code> UChars). 804 * @param c The BMP code point to find. 805 * @param count The length of the string. 806 * @return A pointer to the first occurrence of <code>c</code> in <code>s</code> 807 * or <code>NULL</code> if <code>c</code> is not in <code>s</code>. 808 * @stable ICU 2.0 809 * 810 * @see u_strchr 811 * @see u_memchr32 812 * @see u_strFindFirst 813 */ 814 U_CAPI UChar* U_EXPORT2 815 u_memchr(const UChar *s, UChar c, int32_t count); 816 817 /** 818 * Find the first occurrence of a code point in a string. 819 * A surrogate code point is found only if its match in the text is not 820 * part of a surrogate pair. 821 * A NUL character is found at the string terminator. 822 * 823 * @param s The string to search (contains <code>count</code> UChars). 824 * @param c The code point to find. 825 * @param count The length of the string. 826 * @return A pointer to the first occurrence of <code>c</code> in <code>s</code> 827 * or <code>NULL</code> if <code>c</code> is not in <code>s</code>. 828 * @stable ICU 2.0 829 * 830 * @see u_strchr32 831 * @see u_memchr 832 * @see u_strFindFirst 833 */ 834 U_CAPI UChar* U_EXPORT2 835 u_memchr32(const UChar *s, UChar32 c, int32_t count); 836 837 /** 838 * Find the last occurrence of a BMP code point in a string. 839 * A surrogate code point is found only if its match in the text is not 840 * part of a surrogate pair. 841 * A NUL character is found at the string terminator. 842 * 843 * @param s The string to search (contains <code>count</code> UChars). 844 * @param c The BMP code point to find. 845 * @param count The length of the string. 846 * @return A pointer to the last occurrence of <code>c</code> in <code>s</code> 847 * or <code>NULL</code> if <code>c</code> is not in <code>s</code>. 848 * @stable ICU 2.4 849 * 850 * @see u_strrchr 851 * @see u_memrchr32 852 * @see u_strFindLast 853 */ 854 U_CAPI UChar* U_EXPORT2 855 u_memrchr(const UChar *s, UChar c, int32_t count); 856 857 /** 858 * Find the last occurrence of a code point in a string. 859 * A surrogate code point is found only if its match in the text is not 860 * part of a surrogate pair. 861 * A NUL character is found at the string terminator. 862 * 863 * @param s The string to search (contains <code>count</code> UChars). 864 * @param c The code point to find. 865 * @param count The length of the string. 866 * @return A pointer to the last occurrence of <code>c</code> in <code>s</code> 867 * or <code>NULL</code> if <code>c</code> is not in <code>s</code>. 868 * @stable ICU 2.4 869 * 870 * @see u_strrchr32 871 * @see u_memrchr 872 * @see u_strFindLast 873 */ 874 U_CAPI UChar* U_EXPORT2 875 u_memrchr32(const UChar *s, UChar32 c, int32_t count); 876 877 /** 878 * Unicode String literals in C. 879 * We need one macro to declare a variable for the string 880 * and to statically preinitialize it if possible, 881 * and a second macro to dynamically initialize such a string variable if necessary. 882 * 883 * The macros are defined for maximum performance. 884 * They work only for strings that contain "invariant characters", i.e., 885 * only latin letters, digits, and some punctuation. 886 * See utypes.h for details. 887 * 888 * A pair of macros for a single string must be used with the same 889 * parameters. 890 * The string parameter must be a C string literal. 891 * The length of the string, not including the terminating 892 * `NUL`, must be specified as a constant. 893 * The U_STRING_DECL macro should be invoked exactly once for one 894 * such string variable before it is used. 895 * 896 * Usage: 897 * 898 * U_STRING_DECL(ustringVar1, "Quick-Fox 2", 11); 899 * U_STRING_DECL(ustringVar2, "jumps 5%", 8); 900 * static UBool didInit=false; 901 * 902 * int32_t function() { 903 * if(!didInit) { 904 * U_STRING_INIT(ustringVar1, "Quick-Fox 2", 11); 905 * U_STRING_INIT(ustringVar2, "jumps 5%", 8); 906 * didInit=true; 907 * } 908 * return u_strcmp(ustringVar1, ustringVar2); 909 * } 910 * 911 * Note that the macros will NOT consistently work if their argument is another #`define`. 912 * The following will not work on all platforms, don't use it. 913 * 914 * #define GLUCK "Mr. Gluck" 915 * U_STRING_DECL(var, GLUCK, 9) 916 * U_STRING_INIT(var, GLUCK, 9) 917 * 918 * Instead, use the string literal "Mr. Gluck" as the argument to both macro 919 * calls. 920 * 921 * 922 * @stable ICU 2.0 923 */ 924 #if defined(U_DECLARE_UTF16) 925 # define U_STRING_DECL(var, cs, length) static const UChar *var=(const UChar *)U_DECLARE_UTF16(cs) 926 /**@stable ICU 2.0 */ 927 # define U_STRING_INIT(var, cs, length) 928 #elif U_SIZEOF_WCHAR_T==U_SIZEOF_UCHAR && (U_CHARSET_FAMILY==U_ASCII_FAMILY || (U_SIZEOF_UCHAR == 2 && defined(U_WCHAR_IS_UTF16))) 929 # define U_STRING_DECL(var, cs, length) static const UChar var[(length)+1]=L ## cs 930 /**@stable ICU 2.0 */ 931 # define U_STRING_INIT(var, cs, length) 932 #elif U_SIZEOF_UCHAR==1 && U_CHARSET_FAMILY==U_ASCII_FAMILY 933 # define U_STRING_DECL(var, cs, length) static const UChar var[(length)+1]=cs 934 /**@stable ICU 2.0 */ 935 # define U_STRING_INIT(var, cs, length) 936 #else 937 # define U_STRING_DECL(var, cs, length) static UChar var[(length)+1] 938 /**@stable ICU 2.0 */ 939 # define U_STRING_INIT(var, cs, length) u_charsToUChars(cs, var, length+1) 940 #endif 941 942 /** 943 * Unescape a string of characters and write the resulting 944 * Unicode characters to the destination buffer. The following escape 945 * sequences are recognized: 946 * 947 * \\uhhhh 4 hex digits; h in [0-9A-Fa-f] 948 * \\Uhhhhhhhh 8 hex digits 949 * \\xhh 1-2 hex digits 950 * \\x{h...} 1-8 hex digits 951 * \\ooo 1-3 octal digits; o in [0-7] 952 * \\cX control-X; X is masked with 0x1F 953 * 954 * as well as the standard ANSI C escapes: 955 * 956 * \\a => U+0007, \\b => U+0008, \\t => U+0009, \\n => U+000A, 957 * \\v => U+000B, \\f => U+000C, \\r => U+000D, \\e => U+001B, 958 * \\" => U+0022, \\' => U+0027, \\? => U+003F, \\\\ => U+005C 959 * 960 * Anything else following a backslash is generically escaped. For 961 * example, "[a\\-z]" returns "[a-z]". 962 * 963 * If an escape sequence is ill-formed, this method returns an empty 964 * string. An example of an ill-formed sequence is "\\u" followed by 965 * fewer than 4 hex digits. 966 * 967 * The above characters are recognized in the compiler's codepage, 968 * that is, they are coded as 'u', '\\', etc. Characters that are 969 * not parts of escape sequences are converted using u_charsToUChars(). 970 * 971 * This function is similar to UnicodeString::unescape() but not 972 * identical to it. The latter takes a source UnicodeString, so it 973 * does escape recognition but no conversion. 974 * 975 * @param src a zero-terminated string of invariant characters 976 * @param dest pointer to buffer to receive converted and unescaped 977 * text and, if there is room, a zero terminator. May be NULL for 978 * preflighting, in which case no UChars will be written, but the 979 * return value will still be valid. On error, an empty string is 980 * stored here (if possible). 981 * @param destCapacity the number of UChars that may be written at 982 * dest. Ignored if dest == NULL. 983 * @return the length of unescaped string. 984 * @see u_unescapeAt 985 * @see UnicodeString#unescape() 986 * @see UnicodeString#unescapeAt() 987 * @stable ICU 2.0 988 */ 989 U_CAPI int32_t U_EXPORT2 990 u_unescape(const char *src, 991 UChar *dest, int32_t destCapacity); 992 993 U_CDECL_BEGIN 994 /** 995 * Callback function for u_unescapeAt() that returns a character of 996 * the source text given an offset and a context pointer. The context 997 * pointer will be whatever is passed into u_unescapeAt(). 998 * 999 * @param offset pointer to the offset that will be passed to u_unescapeAt(). 1000 * @param context an opaque pointer passed directly into u_unescapeAt() 1001 * @return the character represented by the escape sequence at 1002 * offset 1003 * @see u_unescapeAt 1004 * @stable ICU 2.0 1005 */ 1006 typedef UChar (U_CALLCONV *UNESCAPE_CHAR_AT)(int32_t offset, void *context); 1007 U_CDECL_END 1008 1009 /** 1010 * Unescape a single sequence. The character at offset-1 is assumed 1011 * (without checking) to be a backslash. This method takes a callback 1012 * pointer to a function that returns the UChar at a given offset. By 1013 * varying this callback, ICU functions are able to unescape char* 1014 * strings, UnicodeString objects, and UFILE pointers. 1015 * 1016 * If offset is out of range, or if the escape sequence is ill-formed, 1017 * (UChar32)0xFFFFFFFF is returned. See documentation of u_unescape() 1018 * for a list of recognized sequences. 1019 * 1020 * @param charAt callback function that returns a UChar of the source 1021 * text given an offset and a context pointer. 1022 * @param offset pointer to the offset that will be passed to charAt. 1023 * The offset value will be updated upon return to point after the 1024 * last parsed character of the escape sequence. On error the offset 1025 * is unchanged. 1026 * @param length the number of characters in the source text. The 1027 * last character of the source text is considered to be at offset 1028 * length-1. 1029 * @param context an opaque pointer passed directly into charAt. 1030 * @return the character represented by the escape sequence at 1031 * offset, or (UChar32)0xFFFFFFFF on error. 1032 * @see u_unescape() 1033 * @see UnicodeString#unescape() 1034 * @see UnicodeString#unescapeAt() 1035 * @stable ICU 2.0 1036 */ 1037 U_CAPI UChar32 U_EXPORT2 1038 u_unescapeAt(UNESCAPE_CHAR_AT charAt, 1039 int32_t *offset, 1040 int32_t length, 1041 void *context); 1042 1043 /** 1044 * Uppercase the characters in a string. 1045 * Casing is locale-dependent and context-sensitive. 1046 * The result may be longer or shorter than the original. 1047 * The source string and the destination buffer are allowed to overlap. 1048 * 1049 * @param dest A buffer for the result string. The result will be zero-terminated if 1050 * the buffer is large enough. 1051 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then 1052 * dest may be NULL and the function will only return the length of the result 1053 * without writing any of the result string. 1054 * @param src The original string 1055 * @param srcLength The length of the original string. If -1, then src must be zero-terminated. 1056 * @param locale The locale to consider, or "" for the root locale or NULL for the default locale. 1057 * @param pErrorCode Must be a valid pointer to an error code value, 1058 * which must not indicate a failure before the function call. 1059 * @return The length of the result string. It may be greater than destCapacity. In that case, 1060 * only some of the result was written to the destination buffer. 1061 * @stable ICU 2.0 1062 */ 1063 U_CAPI int32_t U_EXPORT2 1064 u_strToUpper(UChar *dest, int32_t destCapacity, 1065 const UChar *src, int32_t srcLength, 1066 const char *locale, 1067 UErrorCode *pErrorCode); 1068 1069 /** 1070 * Lowercase the characters in a string. 1071 * Casing is locale-dependent and context-sensitive. 1072 * The result may be longer or shorter than the original. 1073 * The source string and the destination buffer are allowed to overlap. 1074 * 1075 * @param dest A buffer for the result string. The result will be zero-terminated if 1076 * the buffer is large enough. 1077 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then 1078 * dest may be NULL and the function will only return the length of the result 1079 * without writing any of the result string. 1080 * @param src The original string 1081 * @param srcLength The length of the original string. If -1, then src must be zero-terminated. 1082 * @param locale The locale to consider, or "" for the root locale or NULL for the default locale. 1083 * @param pErrorCode Must be a valid pointer to an error code value, 1084 * which must not indicate a failure before the function call. 1085 * @return The length of the result string. It may be greater than destCapacity. In that case, 1086 * only some of the result was written to the destination buffer. 1087 * @stable ICU 2.0 1088 */ 1089 U_CAPI int32_t U_EXPORT2 1090 u_strToLower(UChar *dest, int32_t destCapacity, 1091 const UChar *src, int32_t srcLength, 1092 const char *locale, 1093 UErrorCode *pErrorCode); 1094 1095 #if !UCONFIG_NO_BREAK_ITERATION 1096 1097 /** 1098 * Titlecase a string. 1099 * Casing is locale-dependent and context-sensitive. 1100 * Titlecasing uses a break iterator to find the first characters of words 1101 * that are to be titlecased. It titlecases those characters and lowercases 1102 * all others. 1103 * 1104 * The titlecase break iterator can be provided to customize for arbitrary 1105 * styles, using rules and dictionaries beyond the standard iterators. 1106 * It may be more efficient to always provide an iterator to avoid 1107 * opening and closing one for each string. 1108 * The standard titlecase iterator for the root locale implements the 1109 * algorithm of Unicode TR 21. 1110 * 1111 * This function uses only the setText(), first() and next() methods of the 1112 * provided break iterator. 1113 * 1114 * The result may be longer or shorter than the original. 1115 * The source string and the destination buffer are allowed to overlap. 1116 * 1117 * @param dest A buffer for the result string. The result will be zero-terminated if 1118 * the buffer is large enough. 1119 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then 1120 * dest may be NULL and the function will only return the length of the result 1121 * without writing any of the result string. 1122 * @param src The original string 1123 * @param srcLength The length of the original string. If -1, then src must be zero-terminated. 1124 * @param titleIter A break iterator to find the first characters of words 1125 * that are to be titlecased. 1126 * If none is provided (NULL), then a standard titlecase 1127 * break iterator is opened. 1128 * @param locale The locale to consider, or "" for the root locale or NULL for the default locale. 1129 * @param pErrorCode Must be a valid pointer to an error code value, 1130 * which must not indicate a failure before the function call. 1131 * @return The length of the result string. It may be greater than destCapacity. In that case, 1132 * only some of the result was written to the destination buffer. 1133 * @stable ICU 2.1 1134 */ 1135 U_CAPI int32_t U_EXPORT2 1136 u_strToTitle(UChar *dest, int32_t destCapacity, 1137 const UChar *src, int32_t srcLength, 1138 UBreakIterator *titleIter, 1139 const char *locale, 1140 UErrorCode *pErrorCode); 1141 1142 #endif 1143 1144 /** 1145 * Case-folds the characters in a string. 1146 * 1147 * Case-folding is locale-independent and not context-sensitive, 1148 * but there is an option for whether to include or exclude mappings for dotted I 1149 * and dotless i that are marked with 'T' in CaseFolding.txt. 1150 * 1151 * The result may be longer or shorter than the original. 1152 * The source string and the destination buffer are allowed to overlap. 1153 * 1154 * @param dest A buffer for the result string. The result will be zero-terminated if 1155 * the buffer is large enough. 1156 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then 1157 * dest may be NULL and the function will only return the length of the result 1158 * without writing any of the result string. 1159 * @param src The original string 1160 * @param srcLength The length of the original string. If -1, then src must be zero-terminated. 1161 * @param options Either U_FOLD_CASE_DEFAULT or U_FOLD_CASE_EXCLUDE_SPECIAL_I 1162 * @param pErrorCode Must be a valid pointer to an error code value, 1163 * which must not indicate a failure before the function call. 1164 * @return The length of the result string. It may be greater than destCapacity. In that case, 1165 * only some of the result was written to the destination buffer. 1166 * @stable ICU 2.0 1167 */ 1168 U_CAPI int32_t U_EXPORT2 1169 u_strFoldCase(UChar *dest, int32_t destCapacity, 1170 const UChar *src, int32_t srcLength, 1171 uint32_t options, 1172 UErrorCode *pErrorCode); 1173 1174 #if defined(U_WCHAR_IS_UTF16) || defined(U_WCHAR_IS_UTF32) || !UCONFIG_NO_CONVERSION 1175 /** 1176 * Convert a UTF-16 string to a wchar_t string. 1177 * If it is known at compile time that wchar_t strings are in UTF-16 or UTF-32, then 1178 * this function simply calls the fast, dedicated function for that. 1179 * Otherwise, two conversions UTF-16 -> default charset -> wchar_t* are performed. 1180 * 1181 * @param dest A buffer for the result string. The result will be zero-terminated if 1182 * the buffer is large enough. 1183 * @param destCapacity The size of the buffer (number of wchar_t's). If it is 0, then 1184 * dest may be NULL and the function will only return the length of the 1185 * result without writing any of the result string (pre-flighting). 1186 * @param pDestLength A pointer to receive the number of units written to the destination. If 1187 * pDestLength!=NULL then *pDestLength is always set to the 1188 * number of output units corresponding to the transformation of 1189 * all the input units, even in case of a buffer overflow. 1190 * @param src The original source string 1191 * @param srcLength The length of the original string. If -1, then src must be zero-terminated. 1192 * @param pErrorCode Must be a valid pointer to an error code value, 1193 * which must not indicate a failure before the function call. 1194 * @return The pointer to destination buffer. 1195 * @stable ICU 2.0 1196 */ 1197 U_CAPI wchar_t* U_EXPORT2 1198 u_strToWCS(wchar_t *dest, 1199 int32_t destCapacity, 1200 int32_t *pDestLength, 1201 const UChar *src, 1202 int32_t srcLength, 1203 UErrorCode *pErrorCode); 1204 /** 1205 * Convert a wchar_t string to UTF-16. 1206 * If it is known at compile time that wchar_t strings are in UTF-16 or UTF-32, then 1207 * this function simply calls the fast, dedicated function for that. 1208 * Otherwise, two conversions wchar_t* -> default charset -> UTF-16 are performed. 1209 * 1210 * @param dest A buffer for the result string. The result will be zero-terminated if 1211 * the buffer is large enough. 1212 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then 1213 * dest may be NULL and the function will only return the length of the 1214 * result without writing any of the result string (pre-flighting). 1215 * @param pDestLength A pointer to receive the number of units written to the destination. If 1216 * pDestLength!=NULL then *pDestLength is always set to the 1217 * number of output units corresponding to the transformation of 1218 * all the input units, even in case of a buffer overflow. 1219 * @param src The original source string 1220 * @param srcLength The length of the original string. If -1, then src must be zero-terminated. 1221 * @param pErrorCode Must be a valid pointer to an error code value, 1222 * which must not indicate a failure before the function call. 1223 * @return The pointer to destination buffer. 1224 * @stable ICU 2.0 1225 */ 1226 U_CAPI UChar* U_EXPORT2 1227 u_strFromWCS(UChar *dest, 1228 int32_t destCapacity, 1229 int32_t *pDestLength, 1230 const wchar_t *src, 1231 int32_t srcLength, 1232 UErrorCode *pErrorCode); 1233 #endif /* defined(U_WCHAR_IS_UTF16) || defined(U_WCHAR_IS_UTF32) || !UCONFIG_NO_CONVERSION */ 1234 1235 /** 1236 * Convert a UTF-16 string to UTF-8. 1237 * If the input string is not well-formed, then the U_INVALID_CHAR_FOUND error code is set. 1238 * 1239 * @param dest A buffer for the result string. The result will be zero-terminated if 1240 * the buffer is large enough. 1241 * @param destCapacity The size of the buffer (number of chars). If it is 0, then 1242 * dest may be NULL and the function will only return the length of the 1243 * result without writing any of the result string (pre-flighting). 1244 * @param pDestLength A pointer to receive the number of units written to the destination. If 1245 * pDestLength!=NULL then *pDestLength is always set to the 1246 * number of output units corresponding to the transformation of 1247 * all the input units, even in case of a buffer overflow. 1248 * @param src The original source string 1249 * @param srcLength The length of the original string. If -1, then src must be zero-terminated. 1250 * @param pErrorCode Must be a valid pointer to an error code value, 1251 * which must not indicate a failure before the function call. 1252 * @return The pointer to destination buffer. 1253 * @stable ICU 2.0 1254 * @see u_strToUTF8WithSub 1255 * @see u_strFromUTF8 1256 */ 1257 U_CAPI char* U_EXPORT2 1258 u_strToUTF8(char *dest, 1259 int32_t destCapacity, 1260 int32_t *pDestLength, 1261 const UChar *src, 1262 int32_t srcLength, 1263 UErrorCode *pErrorCode); 1264 1265 /** 1266 * Convert a UTF-8 string to UTF-16. 1267 * If the input string is not well-formed, then the U_INVALID_CHAR_FOUND error code is set. 1268 * 1269 * @param dest A buffer for the result string. The result will be zero-terminated if 1270 * the buffer is large enough. 1271 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then 1272 * dest may be NULL and the function will only return the length of the 1273 * result without writing any of the result string (pre-flighting). 1274 * @param pDestLength A pointer to receive the number of units written to the destination. If 1275 * pDestLength!=NULL then *pDestLength is always set to the 1276 * number of output units corresponding to the transformation of 1277 * all the input units, even in case of a buffer overflow. 1278 * @param src The original source string 1279 * @param srcLength The length of the original string. If -1, then src must be zero-terminated. 1280 * @param pErrorCode Must be a valid pointer to an error code value, 1281 * which must not indicate a failure before the function call. 1282 * @return The pointer to destination buffer. 1283 * @stable ICU 2.0 1284 * @see u_strFromUTF8WithSub 1285 * @see u_strFromUTF8Lenient 1286 */ 1287 U_CAPI UChar* U_EXPORT2 1288 u_strFromUTF8(UChar *dest, 1289 int32_t destCapacity, 1290 int32_t *pDestLength, 1291 const char *src, 1292 int32_t srcLength, 1293 UErrorCode *pErrorCode); 1294 1295 /** 1296 * Convert a UTF-16 string to UTF-8. 1297 * 1298 * Same as u_strToUTF8() except for the additional subchar which is output for 1299 * illegal input sequences, instead of stopping with the U_INVALID_CHAR_FOUND error code. 1300 * With subchar==U_SENTINEL, this function behaves exactly like u_strToUTF8(). 1301 * 1302 * @param dest A buffer for the result string. The result will be zero-terminated if 1303 * the buffer is large enough. 1304 * @param destCapacity The size of the buffer (number of chars). If it is 0, then 1305 * dest may be NULL and the function will only return the length of the 1306 * result without writing any of the result string (pre-flighting). 1307 * @param pDestLength A pointer to receive the number of units written to the destination. If 1308 * pDestLength!=NULL then *pDestLength is always set to the 1309 * number of output units corresponding to the transformation of 1310 * all the input units, even in case of a buffer overflow. 1311 * @param src The original source string 1312 * @param srcLength The length of the original string. If -1, then src must be zero-terminated. 1313 * @param subchar The substitution character to use in place of an illegal input sequence, 1314 * or U_SENTINEL if the function is to return with U_INVALID_CHAR_FOUND instead. 1315 * A substitution character can be any valid Unicode code point (up to U+10FFFF) 1316 * except for surrogate code points (U+D800..U+DFFF). 1317 * The recommended value is U+FFFD "REPLACEMENT CHARACTER". 1318 * @param pNumSubstitutions Output parameter receiving the number of substitutions if subchar>=0. 1319 * Set to 0 if no substitutions occur or subchar<0. 1320 * pNumSubstitutions can be NULL. 1321 * @param pErrorCode Pointer to a standard ICU error code. Its input value must 1322 * pass the U_SUCCESS() test, or else the function returns 1323 * immediately. Check for U_FAILURE() on output or use with 1324 * function chaining. (See User Guide for details.) 1325 * @return The pointer to destination buffer. 1326 * @see u_strToUTF8 1327 * @see u_strFromUTF8WithSub 1328 * @stable ICU 3.6 1329 */ 1330 U_CAPI char* U_EXPORT2 1331 u_strToUTF8WithSub(char *dest, 1332 int32_t destCapacity, 1333 int32_t *pDestLength, 1334 const UChar *src, 1335 int32_t srcLength, 1336 UChar32 subchar, int32_t *pNumSubstitutions, 1337 UErrorCode *pErrorCode); 1338 1339 /** 1340 * Convert a UTF-8 string to UTF-16. 1341 * 1342 * Same as u_strFromUTF8() except for the additional subchar which is output for 1343 * illegal input sequences, instead of stopping with the U_INVALID_CHAR_FOUND error code. 1344 * With subchar==U_SENTINEL, this function behaves exactly like u_strFromUTF8(). 1345 * 1346 * @param dest A buffer for the result string. The result will be zero-terminated if 1347 * the buffer is large enough. 1348 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then 1349 * dest may be NULL and the function will only return the length of the 1350 * result without writing any of the result string (pre-flighting). 1351 * @param pDestLength A pointer to receive the number of units written to the destination. If 1352 * pDestLength!=NULL then *pDestLength is always set to the 1353 * number of output units corresponding to the transformation of 1354 * all the input units, even in case of a buffer overflow. 1355 * @param src The original source string 1356 * @param srcLength The length of the original string. If -1, then src must be zero-terminated. 1357 * @param subchar The substitution character to use in place of an illegal input sequence, 1358 * or U_SENTINEL if the function is to return with U_INVALID_CHAR_FOUND instead. 1359 * A substitution character can be any valid Unicode code point (up to U+10FFFF) 1360 * except for surrogate code points (U+D800..U+DFFF). 1361 * The recommended value is U+FFFD "REPLACEMENT CHARACTER". 1362 * @param pNumSubstitutions Output parameter receiving the number of substitutions if subchar>=0. 1363 * Set to 0 if no substitutions occur or subchar<0. 1364 * pNumSubstitutions can be NULL. 1365 * @param pErrorCode Pointer to a standard ICU error code. Its input value must 1366 * pass the U_SUCCESS() test, or else the function returns 1367 * immediately. Check for U_FAILURE() on output or use with 1368 * function chaining. (See User Guide for details.) 1369 * @return The pointer to destination buffer. 1370 * @see u_strFromUTF8 1371 * @see u_strFromUTF8Lenient 1372 * @see u_strToUTF8WithSub 1373 * @stable ICU 3.6 1374 */ 1375 U_CAPI UChar* U_EXPORT2 1376 u_strFromUTF8WithSub(UChar *dest, 1377 int32_t destCapacity, 1378 int32_t *pDestLength, 1379 const char *src, 1380 int32_t srcLength, 1381 UChar32 subchar, int32_t *pNumSubstitutions, 1382 UErrorCode *pErrorCode); 1383 1384 /** 1385 * Convert a UTF-8 string to UTF-16. 1386 * 1387 * Same as u_strFromUTF8() except that this function is designed to be very fast, 1388 * which it achieves by being lenient about malformed UTF-8 sequences. 1389 * This function is intended for use in environments where UTF-8 text is 1390 * expected to be well-formed. 1391 * 1392 * Its semantics are: 1393 * - Well-formed UTF-8 text is correctly converted to well-formed UTF-16 text. 1394 * - The function will not read beyond the input string, nor write beyond 1395 * the destCapacity. 1396 * - Malformed UTF-8 results in "garbage" 16-bit Unicode strings which may not 1397 * be well-formed UTF-16. 1398 * The function will resynchronize to valid code point boundaries 1399 * within a small number of code points after an illegal sequence. 1400 * - Non-shortest forms are not detected and will result in "spoofing" output. 1401 * 1402 * For further performance improvement, if srcLength is given (>=0), 1403 * then it must be destCapacity>=srcLength. 1404 * 1405 * There is no inverse u_strToUTF8Lenient() function because there is practically 1406 * no performance gain from not checking that a UTF-16 string is well-formed. 1407 * 1408 * @param dest A buffer for the result string. The result will be zero-terminated if 1409 * the buffer is large enough. 1410 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then 1411 * dest may be NULL and the function will only return the length of the 1412 * result without writing any of the result string (pre-flighting). 1413 * Unlike for other ICU functions, if srcLength>=0 then it 1414 * must be destCapacity>=srcLength. 1415 * @param pDestLength A pointer to receive the number of units written to the destination. If 1416 * pDestLength!=NULL then *pDestLength is always set to the 1417 * number of output units corresponding to the transformation of 1418 * all the input units, even in case of a buffer overflow. 1419 * Unlike for other ICU functions, if srcLength>=0 but 1420 * destCapacity<srcLength, then *pDestLength will be set to srcLength 1421 * (and U_BUFFER_OVERFLOW_ERROR will be set) 1422 * regardless of the actual result length. 1423 * @param src The original source string 1424 * @param srcLength The length of the original string. If -1, then src must be zero-terminated. 1425 * @param pErrorCode Pointer to a standard ICU error code. Its input value must 1426 * pass the U_SUCCESS() test, or else the function returns 1427 * immediately. Check for U_FAILURE() on output or use with 1428 * function chaining. (See User Guide for details.) 1429 * @return The pointer to destination buffer. 1430 * @see u_strFromUTF8 1431 * @see u_strFromUTF8WithSub 1432 * @see u_strToUTF8WithSub 1433 * @stable ICU 3.6 1434 */ 1435 U_CAPI UChar * U_EXPORT2 1436 u_strFromUTF8Lenient(UChar *dest, 1437 int32_t destCapacity, 1438 int32_t *pDestLength, 1439 const char *src, 1440 int32_t srcLength, 1441 UErrorCode *pErrorCode); 1442 1443 /** 1444 * Convert a UTF-16 string to UTF-32. 1445 * If the input string is not well-formed, then the U_INVALID_CHAR_FOUND error code is set. 1446 * 1447 * @param dest A buffer for the result string. The result will be zero-terminated if 1448 * the buffer is large enough. 1449 * @param destCapacity The size of the buffer (number of UChar32s). If it is 0, then 1450 * dest may be NULL and the function will only return the length of the 1451 * result without writing any of the result string (pre-flighting). 1452 * @param pDestLength A pointer to receive the number of units written to the destination. If 1453 * pDestLength!=NULL then *pDestLength is always set to the 1454 * number of output units corresponding to the transformation of 1455 * all the input units, even in case of a buffer overflow. 1456 * @param src The original source string 1457 * @param srcLength The length of the original string. If -1, then src must be zero-terminated. 1458 * @param pErrorCode Must be a valid pointer to an error code value, 1459 * which must not indicate a failure before the function call. 1460 * @return The pointer to destination buffer. 1461 * @see u_strToUTF32WithSub 1462 * @see u_strFromUTF32 1463 * @stable ICU 2.0 1464 */ 1465 U_CAPI UChar32* U_EXPORT2 1466 u_strToUTF32(UChar32 *dest, 1467 int32_t destCapacity, 1468 int32_t *pDestLength, 1469 const UChar *src, 1470 int32_t srcLength, 1471 UErrorCode *pErrorCode); 1472 1473 /** 1474 * Convert a UTF-32 string to UTF-16. 1475 * If the input string is not well-formed, then the U_INVALID_CHAR_FOUND error code is set. 1476 * 1477 * @param dest A buffer for the result string. The result will be zero-terminated if 1478 * the buffer is large enough. 1479 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then 1480 * dest may be NULL and the function will only return the length of the 1481 * result without writing any of the result string (pre-flighting). 1482 * @param pDestLength A pointer to receive the number of units written to the destination. If 1483 * pDestLength!=NULL then *pDestLength is always set to the 1484 * number of output units corresponding to the transformation of 1485 * all the input units, even in case of a buffer overflow. 1486 * @param src The original source string 1487 * @param srcLength The length of the original string. If -1, then src must be zero-terminated. 1488 * @param pErrorCode Must be a valid pointer to an error code value, 1489 * which must not indicate a failure before the function call. 1490 * @return The pointer to destination buffer. 1491 * @see u_strFromUTF32WithSub 1492 * @see u_strToUTF32 1493 * @stable ICU 2.0 1494 */ 1495 U_CAPI UChar* U_EXPORT2 1496 u_strFromUTF32(UChar *dest, 1497 int32_t destCapacity, 1498 int32_t *pDestLength, 1499 const UChar32 *src, 1500 int32_t srcLength, 1501 UErrorCode *pErrorCode); 1502 1503 /** 1504 * Convert a UTF-16 string to UTF-32. 1505 * 1506 * Same as u_strToUTF32() except for the additional subchar which is output for 1507 * illegal input sequences, instead of stopping with the U_INVALID_CHAR_FOUND error code. 1508 * With subchar==U_SENTINEL, this function behaves exactly like u_strToUTF32(). 1509 * 1510 * @param dest A buffer for the result string. The result will be zero-terminated if 1511 * the buffer is large enough. 1512 * @param destCapacity The size of the buffer (number of UChar32s). If it is 0, then 1513 * dest may be NULL and the function will only return the length of the 1514 * result without writing any of the result string (pre-flighting). 1515 * @param pDestLength A pointer to receive the number of units written to the destination. If 1516 * pDestLength!=NULL then *pDestLength is always set to the 1517 * number of output units corresponding to the transformation of 1518 * all the input units, even in case of a buffer overflow. 1519 * @param src The original source string 1520 * @param srcLength The length of the original string. If -1, then src must be zero-terminated. 1521 * @param subchar The substitution character to use in place of an illegal input sequence, 1522 * or U_SENTINEL if the function is to return with U_INVALID_CHAR_FOUND instead. 1523 * A substitution character can be any valid Unicode code point (up to U+10FFFF) 1524 * except for surrogate code points (U+D800..U+DFFF). 1525 * The recommended value is U+FFFD "REPLACEMENT CHARACTER". 1526 * @param pNumSubstitutions Output parameter receiving the number of substitutions if subchar>=0. 1527 * Set to 0 if no substitutions occur or subchar<0. 1528 * pNumSubstitutions can be NULL. 1529 * @param pErrorCode Pointer to a standard ICU error code. Its input value must 1530 * pass the U_SUCCESS() test, or else the function returns 1531 * immediately. Check for U_FAILURE() on output or use with 1532 * function chaining. (See User Guide for details.) 1533 * @return The pointer to destination buffer. 1534 * @see u_strToUTF32 1535 * @see u_strFromUTF32WithSub 1536 * @stable ICU 4.2 1537 */ 1538 U_CAPI UChar32* U_EXPORT2 1539 u_strToUTF32WithSub(UChar32 *dest, 1540 int32_t destCapacity, 1541 int32_t *pDestLength, 1542 const UChar *src, 1543 int32_t srcLength, 1544 UChar32 subchar, int32_t *pNumSubstitutions, 1545 UErrorCode *pErrorCode); 1546 1547 /** 1548 * Convert a UTF-32 string to UTF-16. 1549 * 1550 * Same as u_strFromUTF32() except for the additional subchar which is output for 1551 * illegal input sequences, instead of stopping with the U_INVALID_CHAR_FOUND error code. 1552 * With subchar==U_SENTINEL, this function behaves exactly like u_strFromUTF32(). 1553 * 1554 * @param dest A buffer for the result string. The result will be zero-terminated if 1555 * the buffer is large enough. 1556 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then 1557 * dest may be NULL and the function will only return the length of the 1558 * result without writing any of the result string (pre-flighting). 1559 * @param pDestLength A pointer to receive the number of units written to the destination. If 1560 * pDestLength!=NULL then *pDestLength is always set to the 1561 * number of output units corresponding to the transformation of 1562 * all the input units, even in case of a buffer overflow. 1563 * @param src The original source string 1564 * @param srcLength The length of the original string. If -1, then src must be zero-terminated. 1565 * @param subchar The substitution character to use in place of an illegal input sequence, 1566 * or U_SENTINEL if the function is to return with U_INVALID_CHAR_FOUND instead. 1567 * A substitution character can be any valid Unicode code point (up to U+10FFFF) 1568 * except for surrogate code points (U+D800..U+DFFF). 1569 * The recommended value is U+FFFD "REPLACEMENT CHARACTER". 1570 * @param pNumSubstitutions Output parameter receiving the number of substitutions if subchar>=0. 1571 * Set to 0 if no substitutions occur or subchar<0. 1572 * pNumSubstitutions can be NULL. 1573 * @param pErrorCode Pointer to a standard ICU error code. Its input value must 1574 * pass the U_SUCCESS() test, or else the function returns 1575 * immediately. Check for U_FAILURE() on output or use with 1576 * function chaining. (See User Guide for details.) 1577 * @return The pointer to destination buffer. 1578 * @see u_strFromUTF32 1579 * @see u_strToUTF32WithSub 1580 * @stable ICU 4.2 1581 */ 1582 U_CAPI UChar* U_EXPORT2 1583 u_strFromUTF32WithSub(UChar *dest, 1584 int32_t destCapacity, 1585 int32_t *pDestLength, 1586 const UChar32 *src, 1587 int32_t srcLength, 1588 UChar32 subchar, int32_t *pNumSubstitutions, 1589 UErrorCode *pErrorCode); 1590 1591 /** 1592 * Convert a 16-bit Unicode string to Java Modified UTF-8. 1593 * See http://java.sun.com/javase/6/docs/api/java/io/DataInput.html#modified-utf-8 1594 * 1595 * This function behaves according to the documentation for Java DataOutput.writeUTF() 1596 * except that it does not encode the output length in the destination buffer 1597 * and does not have an output length restriction. 1598 * See http://java.sun.com/javase/6/docs/api/java/io/DataOutput.html#writeUTF(java.lang.String) 1599 * 1600 * The input string need not be well-formed UTF-16. 1601 * (Therefore there is no subchar parameter.) 1602 * 1603 * @param dest A buffer for the result string. The result will be zero-terminated if 1604 * the buffer is large enough. 1605 * @param destCapacity The size of the buffer (number of chars). If it is 0, then 1606 * dest may be NULL and the function will only return the length of the 1607 * result without writing any of the result string (pre-flighting). 1608 * @param pDestLength A pointer to receive the number of units written to the destination. If 1609 * pDestLength!=NULL then *pDestLength is always set to the 1610 * number of output units corresponding to the transformation of 1611 * all the input units, even in case of a buffer overflow. 1612 * @param src The original source string 1613 * @param srcLength The length of the original string. If -1, then src must be zero-terminated. 1614 * @param pErrorCode Pointer to a standard ICU error code. Its input value must 1615 * pass the U_SUCCESS() test, or else the function returns 1616 * immediately. Check for U_FAILURE() on output or use with 1617 * function chaining. (See User Guide for details.) 1618 * @return The pointer to destination buffer. 1619 * @stable ICU 4.4 1620 * @see u_strToUTF8WithSub 1621 * @see u_strFromJavaModifiedUTF8WithSub 1622 */ 1623 U_CAPI char* U_EXPORT2 1624 u_strToJavaModifiedUTF8( 1625 char *dest, 1626 int32_t destCapacity, 1627 int32_t *pDestLength, 1628 const UChar *src, 1629 int32_t srcLength, 1630 UErrorCode *pErrorCode); 1631 1632 /** 1633 * Convert a Java Modified UTF-8 string to a 16-bit Unicode string. 1634 * If the input string is not well-formed and no substitution char is specified, 1635 * then the U_INVALID_CHAR_FOUND error code is set. 1636 * 1637 * This function behaves according to the documentation for Java DataInput.readUTF() 1638 * except that it takes a length parameter rather than 1639 * interpreting the first two input bytes as the length. 1640 * See http://java.sun.com/javase/6/docs/api/java/io/DataInput.html#readUTF() 1641 * 1642 * The output string may not be well-formed UTF-16. 1643 * 1644 * @param dest A buffer for the result string. The result will be zero-terminated if 1645 * the buffer is large enough. 1646 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then 1647 * dest may be NULL and the function will only return the length of the 1648 * result without writing any of the result string (pre-flighting). 1649 * @param pDestLength A pointer to receive the number of units written to the destination. If 1650 * pDestLength!=NULL then *pDestLength is always set to the 1651 * number of output units corresponding to the transformation of 1652 * all the input units, even in case of a buffer overflow. 1653 * @param src The original source string 1654 * @param srcLength The length of the original string. If -1, then src must be zero-terminated. 1655 * @param subchar The substitution character to use in place of an illegal input sequence, 1656 * or U_SENTINEL if the function is to return with U_INVALID_CHAR_FOUND instead. 1657 * A substitution character can be any valid Unicode code point (up to U+10FFFF) 1658 * except for surrogate code points (U+D800..U+DFFF). 1659 * The recommended value is U+FFFD "REPLACEMENT CHARACTER". 1660 * @param pNumSubstitutions Output parameter receiving the number of substitutions if subchar>=0. 1661 * Set to 0 if no substitutions occur or subchar<0. 1662 * pNumSubstitutions can be NULL. 1663 * @param pErrorCode Pointer to a standard ICU error code. Its input value must 1664 * pass the U_SUCCESS() test, or else the function returns 1665 * immediately. Check for U_FAILURE() on output or use with 1666 * function chaining. (See User Guide for details.) 1667 * @return The pointer to destination buffer. 1668 * @see u_strFromUTF8WithSub 1669 * @see u_strFromUTF8Lenient 1670 * @see u_strToJavaModifiedUTF8 1671 * @stable ICU 4.4 1672 */ 1673 U_CAPI UChar* U_EXPORT2 1674 u_strFromJavaModifiedUTF8WithSub( 1675 UChar *dest, 1676 int32_t destCapacity, 1677 int32_t *pDestLength, 1678 const char *src, 1679 int32_t srcLength, 1680 UChar32 subchar, int32_t *pNumSubstitutions, 1681 UErrorCode *pErrorCode); 1682 1683 #endif 1684