Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/ustring.h @ 69:33d812a61356

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