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