icu/unicode/ustring.h

   1 /*
   2 **********************************************************************
   3 *   Copyright (C) 1998-2004, International Business Machines
   4 *   Corporation and others.  All Rights Reserved.
   5 **********************************************************************
   6 *
   7 * File ustring.h
   8 *
   9 * Modification History:
  10 *
  11 *   Date        Name        Description
  12 *   12/07/98    bertrand    Creation.
  13 ******************************************************************************
  14 */
  15
  16 #ifndef USTRING_H
  17 #define USTRING_H
  18
  19 #include "unicode/utypes.h"
  20 #include "unicode/putil.h"
  21 #include "unicode/uiter.h"
  22
  23 /** Simple declaration for u_strToTitle() to avoid including unicode/ubrk.h. @stable ICU 2.1*/
  24 #ifndef UBRK_TYPEDEF_UBREAK_ITERATOR
  25 #   define UBRK_TYPEDEF_UBREAK_ITERATOR
  26     typedef void UBreakIterator;
  27 #endif
  28
  29 /**
  30  * \file
  31  * \brief C API: Unicode string handling functions
  32  *
  33  * These C API functions provide general Unicode string handling.
  34  *
  35  * Some functions are equivalent in name, signature, and behavior to the ANSI C <string.h>
  36  * functions. (For example, they do not check for bad arguments like NULL string pointers.)
  37  * In some cases, only the thread-safe variant of such a function is implemented here
  38  * (see u_strtok_r()).
  39  *
  40  * Other functions provide more Unicode-specific functionality like locale-specific
  41  * upper/lower-casing and string comparison in code point order.
  42  *
  43  * ICU uses 16-bit Unicode (UTF-16) in the form of arrays of UChar code units.
  44  * UTF-16 encodes each Unicode code point with either one or two UChar code units.
  45  * (This is the default form of Unicode, and a forward-compatible extension of the original,
  46  * fixed-width form that was known as UCS-2. UTF-16 superseded UCS-2 with Unicode 2.0
  47  * in 1996.)
  48  *
  49  * Some APIs accept a 32-bit UChar32 value for a single code point.
  50  *
  51  * ICU also handles 16-bit Unicode text with unpaired surrogates.
  52  * Such text is not well-formed UTF-16.
  53  * Code-point-related functions treat unpaired surrogates as surrogate code points,
  54  * i.e., as separate units.
  55  *
  56  * Although UTF-16 is a variable-width encoding form (like some legacy multi-byte encodings),
  57  * it is much more efficient even for random access because the code unit values
  58  * for single-unit characters vs. lead units vs. trail units are completely disjoint.
  59  * This means that it is easy to determine character (code point) boundaries from
  60  * random offsets in the string.
  61  *
  62  * Unicode (UTF-16) string processing is optimized for the single-unit case.
  63  * Although it is important to support supplementary characters
  64  * (which use pairs of lead/trail code units called "surrogates"),
  65  * their occurrence is rare. Almost all characters in modern use require only
  66  * a single UChar code unit (i.e., their code point values are <=0xffff).
  67  *
  68  * For more details see the User Guide Strings chapter (http://oss.software.ibm.com/icu/userguide/strings.html).
  69  * For a discussion of the handling of unpaired surrogates see also
  70  * Jitterbug 2145 and its icu mailing list proposal on 2002-sep-18.
  71  */
  72
  73 /**
  74  * Determine the length of an array of UChar.
  75  *
  76  * @param s The array of UChars, NULL (U+0000) terminated.
  77  * @return The number of UChars in <code>chars</code>, minus the terminator.
  78  * @stable ICU 2.0
  79  */
  80 U_STABLE int32_t U_EXPORT2
  81 u_strlen(const UChar *s);
  82
  83 /**
  84  * Count Unicode code points in the length UChar code units of the string.
  85  * A code point may occupy either one or two UChar code units.
  86  * Counting code points involves reading all code units.
  87  *
  88  * This functions is basically the inverse of the U16_FWD_N() macro (see utf.h).
  89  *
  90  * @param s The input string.
  91  * @param length The number of UChar code units to be checked, or -1 to count all
  92  *               code points before the first NUL (U+0000).
  93  * @return The number of code points in the specified code units.
  94  * @stable ICU 2.0
  95  */
  96 U_STABLE int32_t U_EXPORT2
  97 u_countChar32(const UChar *s, int32_t length);
  98
  99 /**
 100  * Check if the string contains more Unicode code points than a certain number.
 101  * This is more efficient than counting all code points in the entire string
 102  * and comparing that number with a threshold.
 103  * This function may not need to scan the string at all if the length is known
 104  * (not -1 for NUL-termination) and falls within a certain range, and
 105  * never needs to count more than 'number+1' code points.
 106  * Logically equivalent to (u_countChar32(s, length)>number).
 107  * A Unicode code point may occupy either one or two UChar code units.
 108  *
 109  * @param s The input string.
 110  * @param length The length of the string, or -1 if it is NUL-terminated.
 111  * @param number The number of code points in the string is compared against
 112  *               the 'number' parameter.
 113  * @return Boolean value for whether the string contains more Unicode code points
 114  *         than 'number'. Same as (u_countChar32(s, length)>number).
 115  * @stable ICU 2.4
 116  */
 117 U_STABLE UBool U_EXPORT2
 118 u_strHasMoreChar32Than(const UChar *s, int32_t length, int32_t number);
 119
 120 /**
 121  * Concatenate two ustrings.  Appends a copy of <code>src</code>,
 122  * including the null terminator, to <code>dst</code>. The initial copied
 123  * character from <code>src</code> overwrites the null terminator in <code>dst</code>.
 124  *
 125  * @param dst The destination string.
 126  * @param src The source string.
 127  * @return A pointer to <code>dst</code>.
 128  * @stable ICU 2.0
 129  */
 130 U_STABLE UChar* U_EXPORT2
 131 u_strcat(UChar     *dst,
 132     const UChar     *src);
 133
 134 /**
 135  * Concatenate two ustrings.
 136  * Appends at most <code>n</code> characters from <code>src</code> to <code>dst</code>.
 137  * Adds a terminating NUL.
 138  * If src is too long, then only <code>n-1</code> characters will be copied
 139  * before the terminating NUL.
 140  * If <code>n&lt;=0</code> then dst is not modified.
 141  *
 142  * @param dst The destination string.
 143  * @param src The source string.
 144  * @param n The maximum number of characters to compare.
 145  * @return A pointer to <code>dst</code>.
 146  * @stable ICU 2.0
 147  */
 148 U_STABLE UChar* U_EXPORT2
 149 u_strncat(UChar     *dst,
 150      const UChar     *src,
 151      int32_t     n);
 152
 153 /**
 154  * Find the first occurrence of a substring in a string.
 155  * The substring is found at code point boundaries.
 156  * That means that if the substring begins with
 157  * a trail surrogate or ends with a lead surrogate,
 158  * then it is found only if these surrogates stand alone in the text.
 159  * Otherwise, the substring edge units would be matched against
 160  * halves of surrogate pairs.
 161  *
 162  * @param s The string to search (NUL-terminated).
 163  * @param substring The substring to find (NUL-terminated).
 164  * @return A pointer to the first occurrence of <code>substring</code> in <code>s</code>,
 165  *         or <code>s</code> itself if the <code>substring</code> is empty,
 166  *         or <code>NULL</code> if <code>substring</code> is not in <code>s</code>.
 167  * @stable ICU 2.0
 168  *
 169  * @see u_strrstr
 170  * @see u_strFindFirst
 171  * @see u_strFindLast
 172  */
 173 U_STABLE UChar * U_EXPORT2
 174 u_strstr(const UChar *s, const UChar *substring);
 175
 176 /**
 177  * Find the first occurrence of a substring in a string.
 178  * The substring is found at code point boundaries.
 179  * That means that if the substring begins with
 180  * a trail surrogate or ends with a lead surrogate,
 181  * then it is found only if these surrogates stand alone in the text.
 182  * Otherwise, the substring edge units would be matched against
 183  * halves of surrogate pairs.
 184  *
 185  * @param s The string to search.
 186  * @param length The length of s (number of UChars), or -1 if it is NUL-terminated.
 187  * @param substring The substring to find (NUL-terminated).
 188  * @param subLength The length of substring (number of UChars), or -1 if it is NUL-terminated.
 189  * @return A pointer to the first occurrence of <code>substring</code> in <code>s</code>,
 190  *         or <code>s</code> itself if the <code>substring</code> is empty,
 191  *         or <code>NULL</code> if <code>substring</code> is not in <code>s</code>.
 192  * @stable ICU 2.4
 193  *
 194  * @see u_strstr
 195  * @see u_strFindLast
 196  */
 197 U_STABLE UChar * U_EXPORT2
 198 u_strFindFirst(const UChar *s, int32_t length, const UChar *substring, int32_t subLength);
 199
 200 /**
 201  * Find the first occurrence of a BMP code point in a string.
 202  * A surrogate code point is found only if its match in the text is not
 203  * part of a surrogate pair.
 204  * A NUL character is found at the string terminator.
 205  *
 206  * @param s The string to search (NUL-terminated).
 207  * @param c The BMP code point to find.
 208  * @return A pointer to the first occurrence of <code>c</code> in <code>s</code>
 209  *         or <code>NULL</code> if <code>c</code> is not in <code>s</code>.
 210  * @stable ICU 2.0
 211  *
 212  * @see u_strchr32
 213  * @see u_memchr
 214  * @see u_strstr
 215  * @see u_strFindFirst
 216  */
 217 U_STABLE UChar * U_EXPORT2
 218 u_strchr(const UChar *s, UChar c);
 219
 220 /**
 221  * Find the first occurrence of a code point in a string.
 222  * A surrogate code point is found only if its match in the text is not
 223  * part of a surrogate pair.
 224  * A NUL character is found at the string terminator.
 225  *
 226  * @param s The string to search (NUL-terminated).
 227  * @param c The code point to find.
 228  * @return A pointer to the first occurrence of <code>c</code> in <code>s</code>
 229  *         or <code>NULL</code> if <code>c</code> is not in <code>s</code>.
 230  * @stable ICU 2.0
 231  *
 232  * @see u_strchr
 233  * @see u_memchr32
 234  * @see u_strstr
 235  * @see u_strFindFirst
 236  */
 237 U_STABLE UChar * U_EXPORT2
 238 u_strchr32(const UChar *s, UChar32 c);
 239
 240 /**
 241  * Find the last occurrence of a substring in a string.
 242  * The substring is found at code point boundaries.
 243  * That means that if the substring begins with
 244  * a trail surrogate or ends with a lead surrogate,
 245  * then it is found only if these surrogates stand alone in the text.
 246  * Otherwise, the substring edge units would be matched against
 247  * halves of surrogate pairs.
 248  *
 249  * @param s The string to search (NUL-terminated).
 250  * @param substring The substring to find (NUL-terminated).
 251  * @return A pointer to the last occurrence of <code>substring</code> in <code>s</code>,
 252  *         or <code>s</code> itself if the <code>substring</code> is empty,
 253  *         or <code>NULL</code> if <code>substring</code> is not in <code>s</code>.
 254  * @stable ICU 2.4
 255  *
 256  * @see u_strstr
 257  * @see u_strFindFirst
 258  * @see u_strFindLast
 259  */
 260 U_STABLE UChar * U_EXPORT2
 261 u_strrstr(const UChar *s, const UChar *substring);
 262
 263 /**
 264  * Find the last occurrence of a substring in a string.
 265  * The substring is found at code point boundaries.
 266  * That means that if the substring begins with
 267  * a trail surrogate or ends with a lead surrogate,
 268  * then it is found only if these surrogates stand alone in the text.
 269  * Otherwise, the substring edge units would be matched against
 270  * halves of surrogate pairs.
 271  *
 272  * @param s The string to search.
 273  * @param length The length of s (number of UChars), or -1 if it is NUL-terminated.
 274  * @param substring The substring to find (NUL-terminated).
 275  * @param subLength The length of substring (number of UChars), or -1 if it is NUL-terminated.
 276  * @return A pointer to the last occurrence of <code>substring</code> in <code>s</code>,
 277  *         or <code>s</code> itself if the <code>substring</code> is empty,
 278  *         or <code>NULL</code> if <code>substring</code> is not in <code>s</code>.
 279  * @stable ICU 2.4
 280  *
 281  * @see u_strstr
 282  * @see u_strFindLast
 283  */
 284 U_STABLE UChar * U_EXPORT2
 285 u_strFindLast(const UChar *s, int32_t length, const UChar *substring, int32_t subLength);
 286
 287 /**
 288  * Find the last occurrence of a BMP code point in a string.
 289  * A surrogate code point is found only if its match in the text is not
 290  * part of a surrogate pair.
 291  * A NUL character is found at the string terminator.
 292  *
 293  * @param s The string to search (NUL-terminated).
 294  * @param c The BMP code point to find.
 295  * @return A pointer to the last occurrence of <code>c</code> in <code>s</code>
 296  *         or <code>NULL</code> if <code>c</code> is not in <code>s</code>.
 297  * @stable ICU 2.4
 298  *
 299  * @see u_strrchr32
 300  * @see u_memrchr
 301  * @see u_strrstr
 302  * @see u_strFindLast
 303  */
 304 U_STABLE UChar * U_EXPORT2
 305 u_strrchr(const UChar *s, UChar c);
 306
 307 /**
 308  * Find the last occurrence of a code point in a string.
 309  * A surrogate code point is found only if its match in the text is not
 310  * part of a surrogate pair.
 311  * A NUL character is found at the string terminator.
 312  *
 313  * @param s The string to search (NUL-terminated).
 314  * @param c The code point to find.
 315  * @return A pointer to the last occurrence of <code>c</code> in <code>s</code>
 316  *         or <code>NULL</code> if <code>c</code> is not in <code>s</code>.
 317  * @stable ICU 2.4
 318  *
 319  * @see u_strrchr
 320  * @see u_memchr32
 321  * @see u_strrstr
 322  * @see u_strFindLast
 323  */
 324 U_STABLE UChar * U_EXPORT2
 325 u_strrchr32(const UChar *s, UChar32 c);
 326
 327 /**
 328  * Locates the first occurrence in the string <code>string</code> of any of the characters
 329  * in the string <code>matchSet</code>.
 330  * Works just like C's strpbrk but with Unicode.
 331  *
 332  * @param string The string in which to search, NUL-terminated.
 333  * @param matchSet A NUL-terminated string defining a set of code points
 334  *                 for which to search in the text string.
 335  * @return A pointer to the  character in <code>string</code> that matches one of the
 336  *         characters in <code>matchSet</code>, or NULL if no such character is found.
 337  * @stable ICU 2.0
 338  */
 339 U_STABLE UChar * U_EXPORT2
 340 u_strpbrk(const UChar *string, const UChar *matchSet);
 341
 342 /**
 343  * Returns the number of consecutive characters in <code>string</code>,
 344  * beginning with the first, that do not occur somewhere in <code>matchSet</code>.
 345  * Works just like C's strcspn but with Unicode.
 346  *
 347  * @param string The string in which to search, NUL-terminated.
 348  * @param matchSet A NUL-terminated string defining a set of code points
 349  *                 for which to search in the text string.
 350  * @return The number of initial characters in <code>string</code> that do not
 351  *         occur in <code>matchSet</code>.
 352  * @see u_strspn
 353  * @stable ICU 2.0
 354  */
 355 U_STABLE int32_t U_EXPORT2
 356 u_strcspn(const UChar *string, const UChar *matchSet);
 357
 358 /**
 359  * Returns the number of consecutive characters in <code>string</code>,
 360  * beginning with the first, that occur somewhere in <code>matchSet</code>.
 361  * Works just like C's strspn but with Unicode.
 362  *
 363  * @param string The string in which to search, NUL-terminated.
 364  * @param matchSet A NUL-terminated string defining a set of code points
 365  *                 for which to search in the text string.
 366  * @return The number of initial characters in <code>string</code> that do
 367  *         occur in <code>matchSet</code>.
 368  * @see u_strcspn
 369  * @stable ICU 2.0
 370  */
 371 U_STABLE int32_t U_EXPORT2
 372 u_strspn(const UChar *string, const UChar *matchSet);
 373
 374 /**
 375  * The string tokenizer API allows an application to break a string into
 376  * tokens. Unlike strtok(), the saveState (the current pointer within the
 377  * original string) is maintained in saveState. In the first call, the
 378  * argument src is a pointer to the string. In subsequent calls to
 379  * return successive tokens of that string, src must be specified as
 380  * NULL. The value saveState is set by this function to maintain the
 381  * function's position within the string, and on each subsequent call
 382  * you must give this argument the same variable. This function does
 383  * handle surrogate pairs. This function is similar to the strtok_r()
 384  * the POSIX Threads Extension (1003.1c-1995) version.
 385  *
 386  * @param src String containing token(s). This string will be modified.
 387  *            After the first call to u_strtok_r(), this argument must
 388  *            be NULL to get to the next token.
 389  * @param delim Set of delimiter characters (Unicode code points).
 390  * @param saveState The current pointer within the original string,
 391  *              which is set by this function. The saveState
 392  *              parameter should the address of a local variable of type
 393  *              UChar *. (i.e. defined "Uhar *myLocalSaveState" and use
 394  *              &myLocalSaveState for this parameter).
 395  * @return A pointer to the next token found in src, or NULL
 396  *         when there are no more tokens.
 397  * @stable ICU 2.0
 398  */
 399 U_STABLE UChar * U_EXPORT2
 400 u_strtok_r(UChar    *src,
 401      const UChar    *delim,
 402            UChar   **saveState);
 403
 404 /**
 405  * Compare two Unicode strings for bitwise equality (code unit order).
 406  *
 407  * @param s1 A string to compare.
 408  * @param s2 A string to compare.
 409  * @return 0 if <code>s1</code> and <code>s2</code> are bitwise equal; a negative
 410  * value if <code>s1</code> is bitwise less than <code>s2,</code>; a positive
 411  * value if <code>s1</code> is bitwise greater than <code>s2</code>.
 412  * @stable ICU 2.0
 413  */
 414 U_STABLE int32_t  U_EXPORT2
 415 u_strcmp(const UChar     *s1,
 416          const UChar     *s2);
 417
 418 /**
 419  * Compare two Unicode strings in code point order.
 420  * See u_strCompare for details.
 421  *
 422  * @param s1 A string to compare.
 423  * @param s2 A string to compare.
 424  * @return a negative/zero/positive integer corresponding to whether
 425  * the first string is less than/equal to/greater than the second one
 426  * in code point order
 427  * @stable ICU 2.0
 428  */
 429 U_STABLE int32_t U_EXPORT2
 430 u_strcmpCodePointOrder(const UChar *s1, const UChar *s2);
 431
 432 /**
 433  * Compare two Unicode strings (binary order).
 434  *
 435  * The comparison can be done in code unit order or in code point order.
 436  * They differ only in UTF-16 when
 437  * comparing supplementary code points (U+10000..U+10ffff)
 438  * to BMP code points near the end of the BMP (i.e., U+e000..U+ffff).
 439  * In code unit order, high BMP code points sort after supplementary code points
 440  * because they are stored as pairs of surrogates which are at U+d800..U+dfff.
 441  *
 442  * This functions works with strings of different explicitly specified lengths
 443  * unlike the ANSI C-like u_strcmp() and u_memcmp() etc.
 444  * NUL-terminated strings are possible with length arguments of -1.
 445  *
 446  * @param s1 First source string.
 447  * @param length1 Length of first source string, or -1 if NUL-terminated.
 448  *
 449  * @param s2 Second source string.
 450  * @param length2 Length of second source string, or -1 if NUL-terminated.
 451  *
 452  * @param codePointOrder Choose between code unit order (FALSE)
 453  *                       and code point order (TRUE).
 454  *
 455  * @return <0 or 0 or >0 as usual for string comparisons
 456  *
 457  * @stable ICU 2.2
 458  */
 459 U_STABLE int32_t U_EXPORT2
 460 u_strCompare(const UChar *s1, int32_t length1,
 461              const UChar *s2, int32_t length2,
 462              UBool codePointOrder);
 463
 464 /**
 465  * Compare two Unicode strings (binary order)
 466  * as presented by UCharIterator objects.
 467  * Works otherwise just like u_strCompare().
 468  *
 469  * Both iterators are reset to their start positions.
 470  * When the function returns, it is undefined where the iterators
 471  * have stopped.
 472  *
 473  * @param iter1 First source string iterator.
 474  * @param iter2 Second source string iterator.
 475  * @param codePointOrder Choose between code unit order (FALSE)
 476  *                       and code point order (TRUE).
 477  *
 478  * @return <0 or 0 or >0 as usual for string comparisons
 479  *
 480  * @see u_strCompare
 481  *
 482  * @stable ICU 2.6
 483  */
 484 U_STABLE int32_t U_EXPORT2
 485 u_strCompareIter(UCharIterator *iter1, UCharIterator *iter2, UBool codePointOrder);
 486
 487 #ifndef U_COMPARE_CODE_POINT_ORDER
 488 /* see also unistr.h and unorm.h */
 489 /**
 490  * Option bit for u_strCaseCompare, u_strcasecmp, unorm_compare, etc:
 491  * Compare strings in code point order instead of code unit order.
 492  * @stable ICU 2.2
 493  */
 494 #define U_COMPARE_CODE_POINT_ORDER  0x8000
 495 #endif
 496
 497 /**
 498  * Compare two strings case-insensitively using full case folding.
 499  * This is equivalent to
 500  *   u_strCompare(u_strFoldCase(s1, options),
 501  *                u_strFoldCase(s2, options),
 502  *                (options&U_COMPARE_CODE_POINT_ORDER)!=0).
 503  *
 504  * The comparison can be done in UTF-16 code unit order or in code point order.
 505  * They differ only when comparing supplementary code points (U+10000..U+10ffff)
 506  * to BMP code points near the end of the BMP (i.e., U+e000..U+ffff).
 507  * In code unit order, high BMP code points sort after supplementary code points
 508  * because they are stored as pairs of surrogates which are at U+d800..U+dfff.
 509  *
 510  * This functions works with strings of different explicitly specified lengths
 511  * unlike the ANSI C-like u_strcmp() and u_memcmp() etc.
 512  * NUL-terminated strings are possible with length arguments of -1.
 513  *
 514  * @param s1 First source string.
 515  * @param length1 Length of first source string, or -1 if NUL-terminated.
 516  *
 517  * @param s2 Second source string.
 518  * @param length2 Length of second source string, or -1 if NUL-terminated.
 519  *
 520  * @param options A bit set of options:
 521  *   - U_FOLD_CASE_DEFAULT or 0 is used for default options:
 522  *     Comparison in code unit order with default case folding.
 523  *
 524  *   - U_COMPARE_CODE_POINT_ORDER
 525  *     Set to choose code point order instead of code unit order
 526  *     (see u_strCompare for details).
 527  *
 528  *   - U_FOLD_CASE_EXCLUDE_SPECIAL_I
 529  *
 530  * @param pErrorCode Must be a valid pointer to an error code value,
 531  *                  which must not indicate a failure before the function call.
 532  *
 533  * @return <0 or 0 or >0 as usual for string comparisons
 534  *
 535  * @stable ICU 2.2
 536  */
 537 U_STABLE int32_t U_EXPORT2
 538 u_strCaseCompare(const UChar *s1, int32_t length1,
 539                  const UChar *s2, int32_t length2,
 540                  uint32_t options,
 541                  UErrorCode *pErrorCode);
 542
 543 /**
 544  * Compare two ustrings for bitwise equality.
 545  * Compares at most <code>n</code> characters.
 546  *
 547  * @param ucs1 A string to compare.
 548  * @param ucs2 A string to compare.
 549  * @param n The maximum number of characters to compare.
 550  * @return 0 if <code>s1</code> and <code>s2</code> are bitwise equal; a negative
 551  * value if <code>s1</code> is bitwise less than <code>s2</code>; a positive
 552  * value if <code>s1</code> is bitwise greater than <code>s2</code>.
 553  * @stable ICU 2.0
 554  */
 555 U_STABLE int32_t U_EXPORT2
 556 u_strncmp(const UChar     *ucs1,
 557      const UChar     *ucs2,
 558      int32_t     n);
 559
 560 /**
 561  * Compare two Unicode strings in code point order.
 562  * This is different in UTF-16 from u_strncmp() if supplementary characters are present.
 563  * For details, see u_strCompare().
 564  *
 565  * @param s1 A string to compare.
 566  * @param s2 A string to compare.
 567  * @param n The maximum number of characters to compare.
 568  * @return a negative/zero/positive integer corresponding to whether
 569  * the first string is less than/equal to/greater than the second one
 570  * in code point order
 571  * @stable ICU 2.0
 572  */
 573 U_STABLE int32_t U_EXPORT2
 574 u_strncmpCodePointOrder(const UChar *s1, const UChar *s2, int32_t n);
 575
 576 /**
 577  * Compare two strings case-insensitively using full case folding.
 578  * This is equivalent to u_strcmp(u_strFoldCase(s1, options), u_strFoldCase(s2, options)).
 579  *
 580  * @param s1 A string to compare.
 581  * @param s2 A string to compare.
 582  * @param options A bit set of options:
 583  *   - U_FOLD_CASE_DEFAULT or 0 is used for default options:
 584  *     Comparison in code unit order with default case folding.
 585  *
 586  *   - U_COMPARE_CODE_POINT_ORDER
 587  *     Set to choose code point order instead of code unit order
 588  *     (see u_strCompare for details).
 589  *
 590  *   - U_FOLD_CASE_EXCLUDE_SPECIAL_I
 591  *
 592  * @return A negative, zero, or positive integer indicating the comparison result.
 593  * @stable ICU 2.0
 594  */
 595 U_STABLE int32_t U_EXPORT2
 596 u_strcasecmp(const UChar *s1, const UChar *s2, uint32_t options);
 597
 598 /**
 599  * Compare two strings case-insensitively using full case folding.
 600  * This is equivalent to u_strcmp(u_strFoldCase(s1, at most n, options),
 601  * u_strFoldCase(s2, at most n, options)).
 602  *
 603  * @param s1 A string to compare.
 604  * @param s2 A string to compare.
 605  * @param n The maximum number of characters each string to case-fold and then compare.
 606  * @param options A bit set of options:
 607  *   - U_FOLD_CASE_DEFAULT or 0 is used for default options:
 608  *     Comparison in code unit order with default case folding.
 609  *
 610  *   - U_COMPARE_CODE_POINT_ORDER
 611  *     Set to choose code point order instead of code unit order
 612  *     (see u_strCompare for details).
 613  *
 614  *   - U_FOLD_CASE_EXCLUDE_SPECIAL_I
 615  *
 616  * @return A negative, zero, or positive integer indicating the comparison result.
 617  * @stable ICU 2.0
 618  */
 619 U_STABLE int32_t U_EXPORT2
 620 u_strncasecmp(const UChar *s1, const UChar *s2, int32_t n, uint32_t options);
 621
 622 /**
 623  * Compare two strings case-insensitively using full case folding.
 624  * This is equivalent to u_strcmp(u_strFoldCase(s1, n, options),
 625  * u_strFoldCase(s2, n, options)).
 626  *
 627  * @param s1 A string to compare.
 628  * @param s2 A string to compare.
 629  * @param length The number of characters in each string to case-fold and then compare.
 630  * @param options A bit set of options:
 631  *   - U_FOLD_CASE_DEFAULT or 0 is used for default options:
 632  *     Comparison in code unit order with default case folding.
 633  *
 634  *   - U_COMPARE_CODE_POINT_ORDER
 635  *     Set to choose code point order instead of code unit order
 636  *     (see u_strCompare for details).
 637  *
 638  *   - U_FOLD_CASE_EXCLUDE_SPECIAL_I
 639  *
 640  * @return A negative, zero, or positive integer indicating the comparison result.
 641  * @stable ICU 2.0
 642  */
 643 U_STABLE int32_t U_EXPORT2
 644 u_memcasecmp(const UChar *s1, const UChar *s2, int32_t length, uint32_t options);
 645
 646 /**
 647  * Copy a ustring. Adds a null terminator.
 648  *
 649  * @param dst The destination string.
 650  * @param src The source string.
 651  * @return A pointer to <code>dst</code>.
 652  * @stable ICU 2.0
 653  */
 654 U_STABLE UChar* U_EXPORT2
 655 u_strcpy(UChar     *dst,
 656     const UChar     *src);
 657
 658 /**
 659  * Copy a ustring.
 660  * Copies at most <code>n</code> characters.  The result will be null terminated
 661  * if the length of <code>src</code> is less than <code>n</code>.
 662  *
 663  * @param dst The destination string.
 664  * @param src The source string.
 665  * @param n The maximum number of characters to copy.
 666  * @return A pointer to <code>dst</code>.
 667  * @stable ICU 2.0
 668  */
 669 U_STABLE UChar* U_EXPORT2
 670 u_strncpy(UChar     *dst,
 671      const UChar     *src,
 672      int32_t     n);
 673
 674 #if !UCONFIG_NO_CONVERSION
 675
 676 /**
 677  * Copy a byte string encoded in the default codepage to a ustring.
 678  * Adds a null terminator.
 679  * Performs a host byte to UChar conversion
 680  *
 681  * @param dst The destination string.
 682  * @param src The source string.
 683  * @return A pointer to <code>dst</code>.
 684  * @stable ICU 2.0
 685  */
 686 U_STABLE UChar* U_EXPORT2 u_uastrcpy(UChar *dst,
 687                const char *src );
 688
 689 /**
 690  * Copy a byte string encoded in the default codepage to a ustring.
 691  * Copies at most <code>n</code> characters.  The result will be null terminated
 692  * if the length of <code>src</code> is less than <code>n</code>.
 693  * Performs a host byte to UChar conversion
 694  *
 695  * @param dst The destination string.
 696  * @param src The source string.
 697  * @param n The maximum number of characters to copy.
 698  * @return A pointer to <code>dst</code>.
 699  * @stable ICU 2.0
 700  */
 701 U_STABLE UChar* U_EXPORT2 u_uastrncpy(UChar *dst,
 702             const char *src,
 703             int32_t n);
 704
 705 /**
 706  * Copy ustring to a byte string encoded in the default codepage.
 707  * Adds a null terminator.
 708  * Performs a UChar to host byte conversion
 709  *
 710  * @param dst The destination string.
 711  * @param src The source string.
 712  * @return A pointer to <code>dst</code>.
 713  * @stable ICU 2.0
 714  */
 715 U_STABLE char* U_EXPORT2 u_austrcpy(char *dst,
 716             const UChar *src );
 717
 718 /**
 719  * Copy ustring to a byte string encoded in the default codepage.
 720  * Copies at most <code>n</code> characters.  The result will be null terminated
 721  * if the length of <code>src</code> is less than <code>n</code>.
 722  * Performs a UChar to host byte conversion
 723  *
 724  * @param dst The destination string.
 725  * @param src The source string.
 726  * @param n The maximum number of characters to copy.
 727  * @return A pointer to <code>dst</code>.
 728  * @stable ICU 2.0
 729  */
 730 U_STABLE char* U_EXPORT2 u_austrncpy(char *dst,
 731             const UChar *src,
 732             int32_t n );
 733
 734 #endif
 735
 736 /**
 737  * Synonym for memcpy(), but with UChars only.
 738  * @param dest The destination string
 739  * @param src The source string
 740  * @param count The number of characters to copy
 741  * @return A pointer to <code>dest</code>
 742  * @stable ICU 2.0
 743  */
 744 U_STABLE UChar* U_EXPORT2
 745 u_memcpy(UChar *dest, const UChar *src, int32_t count);
 746
 747 /**
 748  * Synonym for memmove(), but with UChars only.
 749  * @param dest The destination string
 750  * @param src The source string
 751  * @param count The number of characters to move
 752  * @return A pointer to <code>dest</code>
 753  * @stable ICU 2.0
 754  */
 755 U_STABLE UChar* U_EXPORT2
 756 u_memmove(UChar *dest, const UChar *src, int32_t count);
 757
 758 /**
 759  * Initialize <code>count</code> characters of <code>dest</code> to <code>c</code>.
 760  *
 761  * @param dest The destination string.
 762  * @param c The character to initialize the string.
 763  * @param count The maximum number of characters to set.
 764  * @return A pointer to <code>dest</code>.
 765  * @stable ICU 2.0
 766  */
 767 U_STABLE UChar* U_EXPORT2
 768 u_memset(UChar *dest, UChar c, int32_t count);
 769
 770 /**
 771  * Compare the first <code>count</code> UChars of each buffer.
 772  *
 773  * @param buf1 The first string to compare.
 774  * @param buf2 The second string to compare.
 775  * @param count The maximum number of UChars to compare.
 776  * @return When buf1 < buf2, a negative number is returned.
 777  *      When buf1 == buf2, 0 is returned.
 778  *      When buf1 > buf2, a positive number is returned.
 779  * @stable ICU 2.0
 780  */
 781 U_STABLE int32_t U_EXPORT2
 782 u_memcmp(const UChar *buf1, const UChar *buf2, int32_t count);
 783
 784 /**
 785  * Compare two Unicode strings in code point order.
 786  * This is different in UTF-16 from u_memcmp() if supplementary characters are present.
 787  * For details, see u_strCompare().
 788  *
 789  * @param s1 A string to compare.
 790  * @param s2 A string to compare.
 791  * @param count The maximum number of characters to compare.
 792  * @return a negative/zero/positive integer corresponding to whether
 793  * the first string is less than/equal to/greater than the second one
 794  * in code point order
 795  * @stable ICU 2.0
 796  */
 797 U_STABLE int32_t U_EXPORT2
 798 u_memcmpCodePointOrder(const UChar *s1, const UChar *s2, int32_t count);
 799
 800 /**
 801  * Find the first occurrence of a BMP code point in a string.
 802  * A surrogate code point is found only if its match in the text is not
 803  * part of a surrogate pair.
 804  * A NUL character is found at the string terminator.
 805  *
 806  * @param s The string to search (contains <code>count</code> UChars).
 807  * @param c The BMP code point to find.
 808  * @param count The length of the string.
 809  * @return A pointer to the first occurrence of <code>c</code> in <code>s</code>
 810  *         or <code>NULL</code> if <code>c</code> is not in <code>s</code>.
 811  * @stable ICU 2.0
 812  *
 813  * @see u_strchr
 814  * @see u_memchr32
 815  * @see u_strFindFirst
 816  */
 817 U_STABLE UChar* U_EXPORT2
 818 u_memchr(const UChar *s, UChar c, int32_t count);
 819
 820 /**
 821  * Find the first occurrence of a code point in a string.
 822  * A surrogate code point is found only if its match in the text is not
 823  * part of a surrogate pair.
 824  * A NUL character is found at the string terminator.
 825  *
 826  * @param s The string to search (contains <code>count</code> UChars).
 827  * @param c The code point to find.
 828  * @param count The length of the string.
 829  * @return A pointer to the first occurrence of <code>c</code> in <code>s</code>
 830  *         or <code>NULL</code> if <code>c</code> is not in <code>s</code>.
 831  * @stable ICU 2.0
 832  *
 833  * @see u_strchr32
 834  * @see u_memchr
 835  * @see u_strFindFirst
 836  */
 837 U_STABLE UChar* U_EXPORT2
 838 u_memchr32(const UChar *s, UChar32 c, int32_t count);
 839
 840 /**
 841  * Find the last occurrence of a BMP code point in a string.
 842  * A surrogate code point is found only if its match in the text is not
 843  * part of a surrogate pair.
 844  * A NUL character is found at the string terminator.
 845  *
 846  * @param s The string to search (contains <code>count</code> UChars).
 847  * @param c The BMP code point to find.
 848  * @param count The length of the string.
 849  * @return A pointer to the last occurrence of <code>c</code> in <code>s</code>
 850  *         or <code>NULL</code> if <code>c</code> is not in <code>s</code>.
 851  * @stable ICU 2.4
 852  *
 853  * @see u_strrchr
 854  * @see u_memrchr32
 855  * @see u_strFindLast
 856  */
 857 U_STABLE UChar* U_EXPORT2
 858 u_memrchr(const UChar *s, UChar c, int32_t count);
 859
 860 /**
 861  * Find the last occurrence of a code point in a string.
 862  * A surrogate code point is found only if its match in the text is not
 863  * part of a surrogate pair.
 864  * A NUL character is found at the string terminator.
 865  *
 866  * @param s The string to search (contains <code>count</code> UChars).
 867  * @param c The code point to find.
 868  * @param count The length of the string.
 869  * @return A pointer to the last occurrence of <code>c</code> in <code>s</code>
 870  *         or <code>NULL</code> if <code>c</code> is not in <code>s</code>.
 871  * @stable ICU 2.4
 872  *
 873  * @see u_strrchr32
 874  * @see u_memrchr
 875  * @see u_strFindLast
 876  */
 877 U_STABLE UChar* U_EXPORT2
 878 u_memrchr32(const UChar *s, UChar32 c, int32_t count);
 879
 880 /**
 881  * Unicode String literals in C.
 882  * We need one macro to declare a variable for the string
 883  * and to statically preinitialize it if possible,
 884  * and a second macro to dynamically intialize such a string variable if necessary.
 885  *
 886  * The macros are defined for maximum performance.
 887  * They work only for strings that contain "invariant characters", i.e.,
 888  * only latin letters, digits, and some punctuation.
 889  * See utypes.h for details.
 890  *
 891  * A pair of macros for a single string must be used with the same
 892  * parameters.
 893  * The string parameter must be a C string literal.
 894  * The length of the string, not including the terminating
 895  * <code>NUL</code>, must be specified as a constant.
 896  * The U_STRING_DECL macro should be invoked exactly once for one
 897  * such string variable before it is used.
 898  *
 899  * Usage:
 900  * <pre>
 901  * &#32;   U_STRING_DECL(ustringVar1, "Quick-Fox 2", 11);
 902  * &#32;   U_STRING_DECL(ustringVar2, "jumps 5%", 8);
 903  * &#32;   static UBool didInit=FALSE;
 904  * &#32;
 905  * &#32;   int32_t function() {
 906  * &#32;       if(!didInit) {
 907  * &#32;           U_STRING_INIT(ustringVar1, "Quick-Fox 2", 11);
 908  * &#32;           U_STRING_INIT(ustringVar2, "jumps 5%", 8);
 909  * &#32;           didInit=TRUE;
 910  * &#32;       }
 911  * &#32;       return u_strcmp(ustringVar1, ustringVar2);
 912  * &#32;   }
 913  * </pre>
 914  * @stable ICU 2.0
 915  */
 916 #if U_SIZEOF_WCHAR_T==U_SIZEOF_UCHAR && U_CHARSET_FAMILY==U_ASCII_FAMILY
 917 #   define U_STRING_DECL(var, cs, length) static const wchar_t var[(length)+1]={ L ## cs }
 918     /**@stable ICU 2.0 */
 919 #   define U_STRING_INIT(var, cs, length)
 920 #elif U_SIZEOF_UCHAR==1 && U_CHARSET_FAMILY==U_ASCII_FAMILY
 921 #   define U_STRING_DECL(var, cs, length) static const UChar var[(length)+1]={ (const UChar *)cs }
 922     /**@stable ICU 2.0 */
 923 #   define U_STRING_INIT(var, cs, length)
 924 #else
 925 #   define U_STRING_DECL(var, cs, length) static UChar var[(length)+1]
 926     /**@stable ICU 2.0 */
 927 #   define U_STRING_INIT(var, cs, length) u_charsToUChars(cs, var, length+1)
 928 #endif
 929
 930 /**
 931  * Unescape a string of characters and write the resulting
 932  * Unicode characters to the destination buffer.  The following escape
 933  * sequences are recognized:
 934  *
 935  * \\uhhhh       4 hex digits; h in [0-9A-Fa-f]
 936  * \\Uhhhhhhhh   8 hex digits
 937  * \\xhh         1-2 hex digits
 938  * \\x{h...}     1-8 hex digits
 939  * \\ooo         1-3 octal digits; o in [0-7]
 940  * \\cX          control-X; X is masked with 0x1F
 941  *
 942  * as well as the standard ANSI C escapes:
 943  *
 944  * \\a => U+0007, \\b => U+0008, \\t => U+0009, \\n => U+000A,
 945  * \\v => U+000B, \\f => U+000C, \\r => U+000D, \\e => U+001B,
 946  * \\" => U+0022, \\' => U+0027, \\? => U+003F, \\\\ => U+005C
 947  *
 948  * Anything else following a backslash is generically escaped.  For
 949  * example, "[a\\-z]" returns "[a-z]".
 950  *
 951  * If an escape sequence is ill-formed, this method returns an empty
 952  * string.  An example of an ill-formed sequence is "\\u" followed by
 953  * fewer than 4 hex digits.
 954  *
 955  * The above characters are recognized in the compiler's codepage,
 956  * that is, they are coded as 'u', '\\', etc.  Characters that are
 957  * not parts of escape sequences are converted using u_charsToUChars().
 958  *
 959  * This function is similar to UnicodeString::unescape() but not
 960  * identical to it.  The latter takes a source UnicodeString, so it
 961  * does escape recognition but no conversion.
 962  *
 963  * @param src a zero-terminated string of invariant characters
 964  * @param dest pointer to buffer to receive converted and unescaped
 965  * text and, if there is room, a zero terminator.  May be NULL for
 966  * preflighting, in which case no UChars will be written, but the
 967  * return value will still be valid.  On error, an empty string is
 968  * stored here (if possible).
 969  * @param destCapacity the number of UChars that may be written at
 970  * dest.  Ignored if dest == NULL.
 971  * @return the length of unescaped string.
 972  * @see u_unescapeAt
 973  * @see UnicodeString#unescape()
 974  * @see UnicodeString#unescapeAt()
 975  * @stable ICU 2.0
 976  */
 977 U_STABLE int32_t U_EXPORT2
 978 u_unescape(const char *src,
 979            UChar *dest, int32_t destCapacity);
 980
 981 U_CDECL_BEGIN
 982 /**
 983  * Callback function for u_unescapeAt() that returns a character of
 984  * the source text given an offset and a context pointer.  The context
 985  * pointer will be whatever is passed into u_unescapeAt().
 986  *
 987  * @param offset pointer to the offset that will be passed to u_unescapeAt().
 988  * @param context an opaque pointer passed directly into u_unescapeAt()
 989  * @return the character represented by the escape sequence at
 990  * offset
 991  * @see u_unescapeAt
 992  * @stable ICU 2.0
 993  */
 994 typedef UChar (U_CALLCONV *UNESCAPE_CHAR_AT)(int32_t offset, void *context);
 995 U_CDECL_END
 996
 997 /**
 998  * Unescape a single sequence. The character at offset-1 is assumed
 999  * (without checking) to be a backslash.  This method takes a callback
1000  * pointer to a function that returns the UChar at a given offset.  By
1001  * varying this callback, ICU functions are able to unescape char*
1002  * strings, UnicodeString objects, and UFILE pointers.
1003  *
1004  * If offset is out of range, or if the escape sequence is ill-formed,
1005  * (UChar32)0xFFFFFFFF is returned.  See documentation of u_unescape()
1006  * for a list of recognized sequences.
1007  *
1008  * @param charAt callback function that returns a UChar of the source
1009  * text given an offset and a context pointer.
1010  * @param offset pointer to the offset that will be passed to charAt.
1011  * The offset value will be updated upon return to point after the
1012  * last parsed character of the escape sequence.  On error the offset
1013  * is unchanged.
1014  * @param length the number of characters in the source text.  The
1015  * last character of the source text is considered to be at offset
1016  * length-1.
1017  * @param context an opaque pointer passed directly into charAt.
1018  * @return the character represented by the escape sequence at
1019  * offset, or (UChar32)0xFFFFFFFF on error.
1020  * @see u_unescape()
1021  * @see UnicodeString#unescape()
1022  * @see UnicodeString#unescapeAt()
1023  * @stable ICU 2.0
1024  */
1025 U_STABLE UChar32 U_EXPORT2
1026 u_unescapeAt(UNESCAPE_CHAR_AT charAt,
1027              int32_t *offset,
1028              int32_t length,
1029              void *context);
1030
1031 /**
1032  * Uppercase the characters in a string.
1033  * Casing is locale-dependent and context-sensitive.
1034  * The result may be longer or shorter than the original.
1035  * The source string and the destination buffer are allowed to overlap.
1036  *
1037  * @param dest      A buffer for the result string. The result will be zero-terminated if
1038  *                  the buffer is large enough.
1039  * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1040  *                  dest may be NULL and the function will only return the length of the result
1041  *                  without writing any of the result string.
1042  * @param src       The original string
1043  * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1044  * @param locale    The locale to consider, or "" for the root locale or NULL for the default locale.
1045  * @param pErrorCode Must be a valid pointer to an error code value,
1046  *                  which must not indicate a failure before the function call.
1047  * @return The length of the result string. It may be greater than destCapacity. In that case,
1048  *         only some of the result was written to the destination buffer.
1049  * @stable ICU 2.0
1050  */
1051 U_STABLE int32_t U_EXPORT2
1052 u_strToUpper(UChar *dest, int32_t destCapacity,
1053              const UChar *src, int32_t srcLength,
1054              const char *locale,
1055              UErrorCode *pErrorCode);
1056
1057 /**
1058  * Lowercase the characters in a string.
1059  * Casing is locale-dependent and context-sensitive.
1060  * The result may be longer or shorter than the original.
1061  * The source string and the destination buffer are allowed to overlap.
1062  *
1063  * @param dest      A buffer for the result string. The result will be zero-terminated if
1064  *                  the buffer is large enough.
1065  * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1066  *                  dest may be NULL and the function will only return the length of the result
1067  *                  without writing any of the result string.
1068  * @param src       The original string
1069  * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1070  * @param locale    The locale to consider, or "" for the root locale or NULL for the default locale.
1071  * @param pErrorCode Must be a valid pointer to an error code value,
1072  *                  which must not indicate a failure before the function call.
1073  * @return The length of the result string. It may be greater than destCapacity. In that case,
1074  *         only some of the result was written to the destination buffer.
1075  * @stable ICU 2.0
1076  */
1077 U_STABLE int32_t U_EXPORT2
1078 u_strToLower(UChar *dest, int32_t destCapacity,
1079              const UChar *src, int32_t srcLength,
1080              const char *locale,
1081              UErrorCode *pErrorCode);
1082
1083 #if !UCONFIG_NO_BREAK_ITERATION
1084
1085 /**
1086  * Titlecase a string.
1087  * Casing is locale-dependent and context-sensitive.
1088  * Titlecasing uses a break iterator to find the first characters of words
1089  * that are to be titlecased. It titlecases those characters and lowercases
1090  * all others.
1091  *
1092  * The titlecase break iterator can be provided to customize for arbitrary
1093  * styles, using rules and dictionaries beyond the standard iterators.
1094  * It may be more efficient to always provide an iterator to avoid
1095  * opening and closing one for each string.
1096  * The standard titlecase iterator for the root locale implements the
1097  * algorithm of Unicode TR 21.
1098  *
1099  * This function uses only the first() and next() methods of the
1100  * provided break iterator.
1101  *
1102  * The result may be longer or shorter than the original.
1103  * The source string and the destination buffer are allowed to overlap.
1104  *
1105  * @param dest      A buffer for the result string. The result will be zero-terminated if
1106  *                  the buffer is large enough.
1107  * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1108  *                  dest may be NULL and the function will only return the length of the result
1109  *                  without writing any of the result string.
1110  * @param src       The original string
1111  * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1112  * @param titleIter A break iterator to find the first characters of words
1113  *                  that are to be titlecased.
1114  *                  If none is provided (NULL), then a standard titlecase
1115  *                  break iterator is opened.
1116  * @param locale    The locale to consider, or "" for the root locale or NULL for the default locale.
1117  * @param pErrorCode Must be a valid pointer to an error code value,
1118  *                  which must not indicate a failure before the function call.
1119  * @return The length of the result string. It may be greater than destCapacity. In that case,
1120  *         only some of the result was written to the destination buffer.
1121  * @stable ICU 2.1
1122  */
1123 U_STABLE int32_t U_EXPORT2
1124 u_strToTitle(UChar *dest, int32_t destCapacity,
1125              const UChar *src, int32_t srcLength,
1126              UBreakIterator *titleIter,
1127              const char *locale,
1128              UErrorCode *pErrorCode);
1129
1130 #endif
1131
1132 /**
1133  * Case-fold the characters in a string.
1134  * Case-folding is locale-independent and not context-sensitive,
1135  * but there is an option for whether to include or exclude mappings for dotted I
1136  * and dotless i that are marked with 'I' in CaseFolding.txt.
1137  * The result may be longer or shorter than the original.
1138  * The source string and the destination buffer are allowed to overlap.
1139  *
1140  * @param dest      A buffer for the result string. The result will be zero-terminated if
1141  *                  the buffer is large enough.
1142  * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1143  *                  dest may be NULL and the function will only return the length of the result
1144  *                  without writing any of the result string.
1145  * @param src       The original string
1146  * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1147  * @param options   Either U_FOLD_CASE_DEFAULT or U_FOLD_CASE_EXCLUDE_SPECIAL_I
1148  * @param pErrorCode Must be a valid pointer to an error code value,
1149  *                  which must not indicate a failure before the function call.
1150  * @return The length of the result string. It may be greater than destCapacity. In that case,
1151  *         only some of the result was written to the destination buffer.
1152  * @stable ICU 2.0
1153  */
1154 U_STABLE int32_t U_EXPORT2
1155 u_strFoldCase(UChar *dest, int32_t destCapacity,
1156               const UChar *src, int32_t srcLength,
1157               uint32_t options,
1158               UErrorCode *pErrorCode);
1159
1160 /**
1161  * Converts a sequence of UChars to wchar_t units.
1162  *
1163  * @param dest          A buffer for the result string. The result will be zero-terminated if
1164  *                      the buffer is large enough.
1165  * @param destCapacity  The size of the buffer (number of wchar_t's). If it is 0, then
1166  *                      dest may be NULL and the function will only return the length of the
1167  *                      result without writing any of the result string (pre-flighting).
1168  * @param pDestLength   A pointer to receive the number of units written to the destination. If
1169  *                      pDestLength!=NULL then *pDestLength is always set to the
1170  *                      number of output units corresponding to the transformation of
1171  *                      all the input units, even in case of a buffer overflow.
1172  * @param src           The original source string
1173  * @param srcLength     The length of the original string. If -1, then src must be zero-terminated.
1174  * @param pErrorCode    Must be a valid pointer to an error code value,
1175  *                      which must not indicate a failure before the function call.
1176  * @return The pointer to destination buffer.
1177  * @stable ICU 2.0
1178  */
1179 U_STABLE wchar_t* U_EXPORT2
1180 u_strToWCS(wchar_t *dest,
1181            int32_t destCapacity,
1182            int32_t *pDestLength,
1183            const UChar *src,
1184            int32_t srcLength,
1185            UErrorCode *pErrorCode);
1186 /**
1187  * Converts a sequence of wchar_t units to UChars
1188  *
1189  * @param dest          A buffer for the result string. The result will be zero-terminated if
1190  *                      the buffer is large enough.
1191  * @param destCapacity  The size of the buffer (number of UChars). If it is 0, then
1192  *                      dest may be NULL and the function will only return the length of the
1193  *                      result without writing any of the result string (pre-flighting).
1194  * @param pDestLength   A pointer to receive the number of units written to the destination. If
1195  *                      pDestLength!=NULL then *pDestLength is always set to the
1196  *                      number of output units corresponding to the transformation of
1197  *                      all the input units, even in case of a buffer overflow.
1198  * @param src           The original source string
1199  * @param srcLength     The length of the original string. If -1, then src must be zero-terminated.
1200  * @param pErrorCode    Must be a valid pointer to an error code value,
1201  *                      which must not indicate a failure before the function call.
1202  * @return The pointer to destination buffer.
1203  * @stable ICU 2.0
1204  */
1205 U_STABLE UChar* U_EXPORT2
1206 u_strFromWCS(UChar   *dest,
1207              int32_t destCapacity,
1208              int32_t *pDestLength,
1209              const wchar_t *src,
1210              int32_t srcLength,
1211              UErrorCode *pErrorCode);
1212 /**
1213  * Converts a sequence of UChars (UTF-16) to UTF-8 bytes
1214  *
1215  * @param dest          A buffer for the result string. The result will be zero-terminated if
1216  *                      the buffer is large enough.
1217  * @param destCapacity  The size of the buffer (number of chars). If it is 0, then
1218  *                      dest may be NULL and the function will only return the length of the
1219  *                      result without writing any of the result string (pre-flighting).
1220  * @param pDestLength   A pointer to receive the number of units written to the destination. If
1221  *                      pDestLength!=NULL then *pDestLength is always set to the
1222  *                      number of output units corresponding to the transformation of
1223  *                      all the input units, even in case of a buffer overflow.
1224  * @param src           The original source string
1225  * @param srcLength     The length of the original string. If -1, then src must be zero-terminated.
1226  * @param pErrorCode    Must be a valid pointer to an error code value,
1227  *                      which must not indicate a failure before the function call.
1228  * @return The pointer to destination buffer.
1229  * @stable ICU 2.0
1230  */
1231 U_STABLE char* U_EXPORT2
1232 u_strToUTF8(char *dest,
1233             int32_t destCapacity,
1234             int32_t *pDestLength,
1235             const UChar *src,
1236             int32_t srcLength,
1237             UErrorCode *pErrorCode);
1238
1239 /**
1240  * Converts a sequence of UTF-8 bytes to UChars (UTF-16).
1241  *
1242  * @param dest          A buffer for the result string. The result will be zero-terminated if
1243  *                      the buffer is large enough.
1244  * @param destCapacity  The size of the buffer (number of UChars). If it is 0, then
1245  *                      dest may be NULL and the function will only return the length of the
1246  *                      result without writing any of the result string (pre-flighting).
1247  * @param pDestLength   A pointer to receive the number of units written to the destination. If
1248  *                      pDestLength!=NULL then *pDestLength is always set to the
1249  *                      number of output units corresponding to the transformation of
1250  *                      all the input units, even in case of a buffer overflow.
1251  * @param src           The original source string
1252  * @param srcLength     The length of the original string. If -1, then src must be zero-terminated.
1253  * @param pErrorCode    Must be a valid pointer to an error code value,
1254  *                      which must not indicate a failure before the function call.
1255  * @return The pointer to destination buffer.
1256  * @stable ICU 2.0
1257  */
1258 U_STABLE UChar* U_EXPORT2
1259 u_strFromUTF8(UChar *dest,
1260               int32_t destCapacity,
1261               int32_t *pDestLength,
1262               const char *src,
1263               int32_t srcLength,
1264               UErrorCode *pErrorCode);
1265
1266 /**
1267  * Converts a sequence of UChars (UTF-16) to UTF32 units.
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 UChar32s). 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  */
1285 U_STABLE UChar32* U_EXPORT2
1286 u_strToUTF32(UChar32 *dest,
1287              int32_t  destCapacity,
1288              int32_t  *pDestLength,
1289              const UChar *src,
1290              int32_t  srcLength,
1291              UErrorCode *pErrorCode);
1292
1293 /**
1294  * Converts a sequence of UTF32 units to UChars (UTF-16)
1295  *
1296  * @param dest          A buffer for the result string. The result will be zero-terminated if
1297  *                      the buffer is large enough.
1298  * @param destCapacity  The size of the buffer (number of UChars). If it is 0, then
1299  *                      dest may be NULL and the function will only return the length of the
1300  *                      result without writing any of the result string (pre-flighting).
1301  * @param pDestLength   A pointer to receive the number of units written to the destination. If
1302  *                      pDestLength!=NULL then *pDestLength is always set to the
1303  *                      number of output units corresponding to the transformation of
1304  *                      all the input units, even in case of a buffer overflow.
1305  * @param src           The original source string
1306  * @param srcLength     The length of the original string. If -1, then src must be zero-terminated.
1307  * @param pErrorCode    Must be a valid pointer to an error code value,
1308  *                      which must not indicate a failure before the function call.
1309  * @return The pointer to destination buffer.
1310  * @stable ICU 2.0
1311  */
1312 U_STABLE UChar* U_EXPORT2
1313 u_strFromUTF32(UChar   *dest,
1314                int32_t destCapacity,
1315                int32_t *pDestLength,
1316                const UChar32 *src,
1317                int32_t srcLength,
1318                UErrorCode *pErrorCode);
1319
1320 #endif