1// © 2016 and later: Unicode, Inc. and others.
2// License & terms of use: http://www.unicode.org/copyright.html
3/*
4**********************************************************************
5* Copyright (C) 1998-2014, International Business Machines
6* Corporation and others. All Rights Reserved.
7**********************************************************************
8*
9* File ustring.h
10*
11* Modification History:
12*
13* Date Name Description
14* 12/07/98 bertrand Creation.
15******************************************************************************
16*/
17
18#ifndef USTRING_H
19#define USTRING_H
20
21#include "unicode/utypes.h"
22#include "unicode/putil.h"
23#include "unicode/uiter.h"
24
25/**
26 * \def UBRK_TYPEDEF_UBREAK_ITERATOR
27 * @internal
28 */
29
30#ifndef UBRK_TYPEDEF_UBREAK_ITERATOR
31# define UBRK_TYPEDEF_UBREAK_ITERATOR
32/** Simple declaration for u_strToTitle() to avoid including unicode/ubrk.h. @stable ICU 2.1*/
33 typedef struct UBreakIterator UBreakIterator;
34#endif
35
36/**
37 * \file
38 * \brief C API: Unicode string handling functions
39 *
40 * These C API functions provide general Unicode string handling.
41 *
42 * Some functions are equivalent in name, signature, and behavior to the ANSI C <string.h>
43 * functions. (For example, they do not check for bad arguments like NULL string pointers.)
44 * In some cases, only the thread-safe variant of such a function is implemented here
45 * (see u_strtok_r()).
46 *
47 * Other functions provide more Unicode-specific functionality like locale-specific
48 * upper/lower-casing and string comparison in code point order.
49 *
50 * ICU uses 16-bit Unicode (UTF-16) in the form of arrays of UChar code units.
51 * UTF-16 encodes each Unicode code point with either one or two UChar code units.
52 * (This is the default form of Unicode, and a forward-compatible extension of the original,
53 * fixed-width form that was known as UCS-2. UTF-16 superseded UCS-2 with Unicode 2.0
54 * in 1996.)
55 *
56 * Some APIs accept a 32-bit UChar32 value for a single code point.
57 *
58 * ICU also handles 16-bit Unicode text with unpaired surrogates.
59 * Such text is not well-formed UTF-16.
60 * Code-point-related functions treat unpaired surrogates as surrogate code points,
61 * i.e., as separate units.
62 *
63 * Although UTF-16 is a variable-width encoding form (like some legacy multi-byte encodings),
64 * it is much more efficient even for random access because the code unit values
65 * for single-unit characters vs. lead units vs. trail units are completely disjoint.
66 * This means that it is easy to determine character (code point) boundaries from
67 * random offsets in the string.
68 *
69 * Unicode (UTF-16) string processing is optimized for the single-unit case.
70 * Although it is important to support supplementary characters
71 * (which use pairs of lead/trail code units called "surrogates"),
72 * their occurrence is rare. Almost all characters in modern use require only
73 * a single UChar code unit (i.e., their code point values are <=0xffff).
74 *
75 * For more details see the User Guide Strings chapter (https://unicode-org.github.io/icu/userguide/strings/).
76 * For a discussion of the handling of unpaired surrogates see also
77 * Jitterbug 2145 and its icu mailing list proposal on 2002-sep-18.
78 */
79
80/**
81 * \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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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 * `NUL`, 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 *
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 *
917 * Note that the macros will NOT consistently work if their argument is another #`define`.
918 * The following will not work on all platforms, don't use it.
919 *
920 * #define GLUCK "Mr. Gluck"
921 * U_STRING_DECL(var, GLUCK, 9)
922 * U_STRING_INIT(var, GLUCK, 9)
923 *
924 * Instead, use the string literal "Mr. Gluck" as the argument to both macro
925 * calls.
926 *
927 *
928 * @stable ICU 2.0
929 */
930#if defined(U_DECLARE_UTF16)
931# define U_STRING_DECL(var, cs, length) static const UChar *var=(const UChar *)U_DECLARE_UTF16(cs)
932 /**@stable ICU 2.0 */
933# define U_STRING_INIT(var, cs, length)
934#elif U_SIZEOF_WCHAR_T==U_SIZEOF_UCHAR && (U_CHARSET_FAMILY==U_ASCII_FAMILY || defined(U_WCHAR_IS_UTF16))
935# define U_STRING_DECL(var, cs, length) static const UChar var[(length)+1]=L ## cs
936 /**@stable ICU 2.0 */
937# define U_STRING_INIT(var, cs, length)
938#else
939# define U_STRING_DECL(var, cs, length) static UChar var[(length)+1]
940 /**@stable ICU 2.0 */
941# define U_STRING_INIT(var, cs, length) u_charsToUChars(cs, var, length+1)
942#endif
943
944/**
945 * Unescape a string of characters and write the resulting
946 * Unicode characters to the destination buffer. The following escape
947 * sequences are recognized:
948 *
949 * \\uhhhh 4 hex digits; h in [0-9A-Fa-f]
950 * \\Uhhhhhhhh 8 hex digits
951 * \\xhh 1-2 hex digits
952 * \\x{h...} 1-8 hex digits
953 * \\ooo 1-3 octal digits; o in [0-7]
954 * \\cX control-X; X is masked with 0x1F
955 *
956 * as well as the standard ANSI C escapes:
957 *
958 * \\a => U+0007, \\b => U+0008, \\t => U+0009, \\n => U+000A,
959 * \\v => U+000B, \\f => U+000C, \\r => U+000D, \\e => U+001B,
960 * \\&quot; => U+0022, \\' => U+0027, \\? => U+003F, \\\\ => U+005C
961 *
962 * Anything else following a backslash is generically escaped. For
963 * example, "[a\\-z]" returns "[a-z]".
964 *
965 * If an escape sequence is ill-formed, this method returns an empty
966 * string. An example of an ill-formed sequence is "\\u" followed by
967 * fewer than 4 hex digits.
968 *
969 * The above characters are recognized in the compiler's codepage,
970 * that is, they are coded as 'u', '\\', etc. Characters that are
971 * not parts of escape sequences are converted using u_charsToUChars().
972 *
973 * This function is similar to UnicodeString::unescape() but not
974 * identical to it. The latter takes a source UnicodeString, so it
975 * does escape recognition but no conversion.
976 *
977 * @param src a zero-terminated string of invariant characters
978 * @param dest pointer to buffer to receive converted and unescaped
979 * text and, if there is room, a zero terminator. May be NULL for
980 * preflighting, in which case no UChars will be written, but the
981 * return value will still be valid. On error, an empty string is
982 * stored here (if possible).
983 * @param destCapacity the number of UChars that may be written at
984 * dest. Ignored if dest == NULL.
985 * @return the length of unescaped string.
986 * @see u_unescapeAt
987 * @see UnicodeString#unescape()
988 * @see UnicodeString#unescapeAt()
989 * @stable ICU 2.0
990 */
991U_CAPI int32_t U_EXPORT2
992u_unescape(const char *src,
993 UChar *dest, int32_t destCapacity);
994
995U_CDECL_BEGIN
996/**
997 * Callback function for u_unescapeAt() that returns a character of
998 * the source text given an offset and a context pointer. The context
999 * pointer will be whatever is passed into u_unescapeAt().
1000 *
1001 * @param offset pointer to the offset that will be passed to u_unescapeAt().
1002 * @param context an opaque pointer passed directly into u_unescapeAt()
1003 * @return the character represented by the escape sequence at
1004 * offset
1005 * @see u_unescapeAt
1006 * @stable ICU 2.0
1007 */
1008typedef UChar (U_CALLCONV *UNESCAPE_CHAR_AT)(int32_t offset, void *context);
1009U_CDECL_END
1010
1011/**
1012 * Unescape a single sequence. The character at offset-1 is assumed
1013 * (without checking) to be a backslash. This method takes a callback
1014 * pointer to a function that returns the UChar at a given offset. By
1015 * varying this callback, ICU functions are able to unescape char*
1016 * strings, UnicodeString objects, and UFILE pointers.
1017 *
1018 * If offset is out of range, or if the escape sequence is ill-formed,
1019 * (UChar32)0xFFFFFFFF is returned. See documentation of u_unescape()
1020 * for a list of recognized sequences.
1021 *
1022 * @param charAt callback function that returns a UChar of the source
1023 * text given an offset and a context pointer.
1024 * @param offset pointer to the offset that will be passed to charAt.
1025 * The offset value will be updated upon return to point after the
1026 * last parsed character of the escape sequence. On error the offset
1027 * is unchanged.
1028 * @param length the number of characters in the source text. The
1029 * last character of the source text is considered to be at offset
1030 * length-1.
1031 * @param context an opaque pointer passed directly into charAt.
1032 * @return the character represented by the escape sequence at
1033 * offset, or (UChar32)0xFFFFFFFF on error.
1034 * @see u_unescape()
1035 * @see UnicodeString#unescape()
1036 * @see UnicodeString#unescapeAt()
1037 * @stable ICU 2.0
1038 */
1039U_CAPI UChar32 U_EXPORT2
1040u_unescapeAt(UNESCAPE_CHAR_AT charAt,
1041 int32_t *offset,
1042 int32_t length,
1043 void *context);
1044
1045/**
1046 * Uppercase the characters in a string.
1047 * Casing is locale-dependent and context-sensitive.
1048 * The result may be longer or shorter than the original.
1049 * The source string and the destination buffer are allowed to overlap.
1050 *
1051 * @param dest A buffer for the result string. The result will be zero-terminated if
1052 * the buffer is large enough.
1053 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1054 * dest may be NULL and the function will only return the length of the result
1055 * without writing any of the result string.
1056 * @param src The original string
1057 * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1058 * @param locale The locale to consider, or "" for the root locale or NULL for the default locale.
1059 * @param pErrorCode Must be a valid pointer to an error code value,
1060 * which must not indicate a failure before the function call.
1061 * @return The length of the result string. It may be greater than destCapacity. In that case,
1062 * only some of the result was written to the destination buffer.
1063 * @stable ICU 2.0
1064 */
1065U_CAPI int32_t U_EXPORT2
1066u_strToUpper(UChar *dest, int32_t destCapacity,
1067 const UChar *src, int32_t srcLength,
1068 const char *locale,
1069 UErrorCode *pErrorCode);
1070
1071/**
1072 * Lowercase the characters in a string.
1073 * Casing is locale-dependent and context-sensitive.
1074 * The result may be longer or shorter than the original.
1075 * The source string and the destination buffer are allowed to overlap.
1076 *
1077 * @param dest A buffer for the result string. The result will be zero-terminated if
1078 * the buffer is large enough.
1079 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1080 * dest may be NULL and the function will only return the length of the result
1081 * without writing any of the result string.
1082 * @param src The original string
1083 * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1084 * @param locale The locale to consider, or "" for the root locale or NULL for the default locale.
1085 * @param pErrorCode Must be a valid pointer to an error code value,
1086 * which must not indicate a failure before the function call.
1087 * @return The length of the result string. It may be greater than destCapacity. In that case,
1088 * only some of the result was written to the destination buffer.
1089 * @stable ICU 2.0
1090 */
1091U_CAPI int32_t U_EXPORT2
1092u_strToLower(UChar *dest, int32_t destCapacity,
1093 const UChar *src, int32_t srcLength,
1094 const char *locale,
1095 UErrorCode *pErrorCode);
1096
1097#if !UCONFIG_NO_BREAK_ITERATION
1098
1099/**
1100 * Titlecase a string.
1101 * Casing is locale-dependent and context-sensitive.
1102 * Titlecasing uses a break iterator to find the first characters of words
1103 * that are to be titlecased. It titlecases those characters and lowercases
1104 * all others.
1105 *
1106 * The titlecase break iterator can be provided to customize for arbitrary
1107 * styles, using rules and dictionaries beyond the standard iterators.
1108 * It may be more efficient to always provide an iterator to avoid
1109 * opening and closing one for each string.
1110 * The standard titlecase iterator for the root locale implements the
1111 * algorithm of Unicode TR 21.
1112 *
1113 * This function uses only the setText(), first() and next() methods of the
1114 * provided break iterator.
1115 *
1116 * The result may be longer or shorter than the original.
1117 * The source string and the destination buffer are allowed to overlap.
1118 *
1119 * @param dest A buffer for the result string. The result will be zero-terminated if
1120 * the buffer is large enough.
1121 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1122 * dest may be NULL and the function will only return the length of the result
1123 * without writing any of the result string.
1124 * @param src The original string
1125 * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1126 * @param titleIter A break iterator to find the first characters of words
1127 * that are to be titlecased.
1128 * If none is provided (NULL), then a standard titlecase
1129 * break iterator is opened.
1130 * @param locale The locale to consider, or "" for the root locale or NULL for the default locale.
1131 * @param pErrorCode Must be a valid pointer to an error code value,
1132 * which must not indicate a failure before the function call.
1133 * @return The length of the result string. It may be greater than destCapacity. In that case,
1134 * only some of the result was written to the destination buffer.
1135 * @stable ICU 2.1
1136 */
1137U_CAPI int32_t U_EXPORT2
1138u_strToTitle(UChar *dest, int32_t destCapacity,
1139 const UChar *src, int32_t srcLength,
1140 UBreakIterator *titleIter,
1141 const char *locale,
1142 UErrorCode *pErrorCode);
1143
1144#endif
1145
1146/**
1147 * Case-folds the characters in a string.
1148 *
1149 * Case-folding is locale-independent and not context-sensitive,
1150 * but there is an option for whether to include or exclude mappings for dotted I
1151 * and dotless i that are marked with 'T' in CaseFolding.txt.
1152 *
1153 * The result may be longer or shorter than the original.
1154 * The source string and the destination buffer are allowed to overlap.
1155 *
1156 * @param dest A buffer for the result string. The result will be zero-terminated if
1157 * the buffer is large enough.
1158 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1159 * dest may be NULL and the function will only return the length of the result
1160 * without writing any of the result string.
1161 * @param src The original string
1162 * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1163 * @param options Either U_FOLD_CASE_DEFAULT or U_FOLD_CASE_EXCLUDE_SPECIAL_I
1164 * @param pErrorCode Must be a valid pointer to an error code value,
1165 * which must not indicate a failure before the function call.
1166 * @return The length of the result string. It may be greater than destCapacity. In that case,
1167 * only some of the result was written to the destination buffer.
1168 * @stable ICU 2.0
1169 */
1170U_CAPI int32_t U_EXPORT2
1171u_strFoldCase(UChar *dest, int32_t destCapacity,
1172 const UChar *src, int32_t srcLength,
1173 uint32_t options,
1174 UErrorCode *pErrorCode);
1175
1176#if defined(U_WCHAR_IS_UTF16) || defined(U_WCHAR_IS_UTF32) || !UCONFIG_NO_CONVERSION
1177/**
1178 * Convert a UTF-16 string to a wchar_t string.
1179 * If it is known at compile time that wchar_t strings are in UTF-16 or UTF-32, then
1180 * this function simply calls the fast, dedicated function for that.
1181 * Otherwise, two conversions UTF-16 -> default charset -> wchar_t* are performed.
1182 *
1183 * @param dest A buffer for the result string. The result will be zero-terminated if
1184 * the buffer is large enough.
1185 * @param destCapacity The size of the buffer (number of wchar_t's). If it is 0, then
1186 * dest may be NULL and the function will only return the length of the
1187 * result without writing any of the result string (pre-flighting).
1188 * @param pDestLength A pointer to receive the number of units written to the destination. If
1189 * pDestLength!=NULL then *pDestLength is always set to the
1190 * number of output units corresponding to the transformation of
1191 * all the input units, even in case of a buffer overflow.
1192 * @param src The original source string
1193 * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1194 * @param pErrorCode Must be a valid pointer to an error code value,
1195 * which must not indicate a failure before the function call.
1196 * @return The pointer to destination buffer.
1197 * @stable ICU 2.0
1198 */
1199U_CAPI wchar_t* U_EXPORT2
1200u_strToWCS(wchar_t *dest,
1201 int32_t destCapacity,
1202 int32_t *pDestLength,
1203 const UChar *src,
1204 int32_t srcLength,
1205 UErrorCode *pErrorCode);
1206/**
1207 * Convert a wchar_t string to UTF-16.
1208 * If it is known at compile time that wchar_t strings are in UTF-16 or UTF-32, then
1209 * this function simply calls the fast, dedicated function for that.
1210 * Otherwise, two conversions wchar_t* -> default charset -> UTF-16 are performed.
1211 *
1212 * @param dest A buffer for the result string. The result will be zero-terminated if
1213 * the buffer is large enough.
1214 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1215 * dest may be NULL and the function will only return the length of the
1216 * result without writing any of the result string (pre-flighting).
1217 * @param pDestLength A pointer to receive the number of units written to the destination. If
1218 * pDestLength!=NULL then *pDestLength is always set to the
1219 * number of output units corresponding to the transformation of
1220 * all the input units, even in case of a buffer overflow.
1221 * @param src The original source string
1222 * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1223 * @param pErrorCode Must be a valid pointer to an error code value,
1224 * which must not indicate a failure before the function call.
1225 * @return The pointer to destination buffer.
1226 * @stable ICU 2.0
1227 */
1228U_CAPI UChar* U_EXPORT2
1229u_strFromWCS(UChar *dest,
1230 int32_t destCapacity,
1231 int32_t *pDestLength,
1232 const wchar_t *src,
1233 int32_t srcLength,
1234 UErrorCode *pErrorCode);
1235#endif /* defined(U_WCHAR_IS_UTF16) || defined(U_WCHAR_IS_UTF32) || !UCONFIG_NO_CONVERSION */
1236
1237/**
1238 * Convert a UTF-16 string to UTF-8.
1239 * If the input string is not well-formed, then the U_INVALID_CHAR_FOUND error code is set.
1240 *
1241 * @param dest A buffer for the result string. The result will be zero-terminated if
1242 * the buffer is large enough.
1243 * @param destCapacity The size of the buffer (number of chars). If it is 0, then
1244 * dest may be NULL and the function will only return the length of the
1245 * result without writing any of the result string (pre-flighting).
1246 * @param pDestLength A pointer to receive the number of units written to the destination. If
1247 * pDestLength!=NULL then *pDestLength is always set to the
1248 * number of output units corresponding to the transformation of
1249 * all the input units, even in case of a buffer overflow.
1250 * @param src The original source string
1251 * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1252 * @param pErrorCode Must be a valid pointer to an error code value,
1253 * which must not indicate a failure before the function call.
1254 * @return The pointer to destination buffer.
1255 * @stable ICU 2.0
1256 * @see u_strToUTF8WithSub
1257 * @see u_strFromUTF8
1258 */
1259U_CAPI char* U_EXPORT2
1260u_strToUTF8(char *dest,
1261 int32_t destCapacity,
1262 int32_t *pDestLength,
1263 const UChar *src,
1264 int32_t srcLength,
1265 UErrorCode *pErrorCode);
1266
1267/**
1268 * Convert a UTF-8 string to UTF-16.
1269 * If the input string is not well-formed, then the U_INVALID_CHAR_FOUND error code is set.
1270 *
1271 * @param dest A buffer for the result string. The result will be zero-terminated if
1272 * the buffer is large enough.
1273 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1274 * dest may be NULL and the function will only return the length of the
1275 * result without writing any of the result string (pre-flighting).
1276 * @param pDestLength A pointer to receive the number of units written to the destination. If
1277 * pDestLength!=NULL then *pDestLength is always set to the
1278 * number of output units corresponding to the transformation of
1279 * all the input units, even in case of a buffer overflow.
1280 * @param src The original source string
1281 * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1282 * @param pErrorCode Must be a valid pointer to an error code value,
1283 * which must not indicate a failure before the function call.
1284 * @return The pointer to destination buffer.
1285 * @stable ICU 2.0
1286 * @see u_strFromUTF8WithSub
1287 * @see u_strFromUTF8Lenient
1288 */
1289U_CAPI UChar* U_EXPORT2
1290u_strFromUTF8(UChar *dest,
1291 int32_t destCapacity,
1292 int32_t *pDestLength,
1293 const char *src,
1294 int32_t srcLength,
1295 UErrorCode *pErrorCode);
1296
1297/**
1298 * Convert a UTF-16 string to UTF-8.
1299 *
1300 * Same as u_strToUTF8() except for the additional subchar which is output for
1301 * illegal input sequences, instead of stopping with the U_INVALID_CHAR_FOUND error code.
1302 * With subchar==U_SENTINEL, this function behaves exactly like u_strToUTF8().
1303 *
1304 * @param dest A buffer for the result string. The result will be zero-terminated if
1305 * the buffer is large enough.
1306 * @param destCapacity The size of the buffer (number of chars). If it is 0, then
1307 * dest may be NULL and the function will only return the length of the
1308 * result without writing any of the result string (pre-flighting).
1309 * @param pDestLength A pointer to receive the number of units written to the destination. If
1310 * pDestLength!=NULL then *pDestLength is always set to the
1311 * number of output units corresponding to the transformation of
1312 * all the input units, even in case of a buffer overflow.
1313 * @param src The original source string
1314 * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1315 * @param subchar The substitution character to use in place of an illegal input sequence,
1316 * or U_SENTINEL if the function is to return with U_INVALID_CHAR_FOUND instead.
1317 * A substitution character can be any valid Unicode code point (up to U+10FFFF)
1318 * except for surrogate code points (U+D800..U+DFFF).
1319 * The recommended value is U+FFFD "REPLACEMENT CHARACTER".
1320 * @param pNumSubstitutions Output parameter receiving the number of substitutions if subchar>=0.
1321 * Set to 0 if no substitutions occur or subchar<0.
1322 * pNumSubstitutions can be NULL.
1323 * @param pErrorCode Pointer to a standard ICU error code. Its input value must
1324 * pass the U_SUCCESS() test, or else the function returns
1325 * immediately. Check for U_FAILURE() on output or use with
1326 * function chaining. (See User Guide for details.)
1327 * @return The pointer to destination buffer.
1328 * @see u_strToUTF8
1329 * @see u_strFromUTF8WithSub
1330 * @stable ICU 3.6
1331 */
1332U_CAPI char* U_EXPORT2
1333u_strToUTF8WithSub(char *dest,
1334 int32_t destCapacity,
1335 int32_t *pDestLength,
1336 const UChar *src,
1337 int32_t srcLength,
1338 UChar32 subchar, int32_t *pNumSubstitutions,
1339 UErrorCode *pErrorCode);
1340
1341/**
1342 * Convert a UTF-8 string to UTF-16.
1343 *
1344 * Same as u_strFromUTF8() except for the additional subchar which is output for
1345 * illegal input sequences, instead of stopping with the U_INVALID_CHAR_FOUND error code.
1346 * With subchar==U_SENTINEL, this function behaves exactly like u_strFromUTF8().
1347 *
1348 * @param dest A buffer for the result string. The result will be zero-terminated if
1349 * the buffer is large enough.
1350 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1351 * dest may be NULL and the function will only return the length of the
1352 * result without writing any of the result string (pre-flighting).
1353 * @param pDestLength A pointer to receive the number of units written to the destination. If
1354 * pDestLength!=NULL then *pDestLength is always set to the
1355 * number of output units corresponding to the transformation of
1356 * all the input units, even in case of a buffer overflow.
1357 * @param src The original source string
1358 * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1359 * @param subchar The substitution character to use in place of an illegal input sequence,
1360 * or U_SENTINEL if the function is to return with U_INVALID_CHAR_FOUND instead.
1361 * A substitution character can be any valid Unicode code point (up to U+10FFFF)
1362 * except for surrogate code points (U+D800..U+DFFF).
1363 * The recommended value is U+FFFD "REPLACEMENT CHARACTER".
1364 * @param pNumSubstitutions Output parameter receiving the number of substitutions if subchar>=0.
1365 * Set to 0 if no substitutions occur or subchar<0.
1366 * pNumSubstitutions can be NULL.
1367 * @param pErrorCode Pointer to a standard ICU error code. Its input value must
1368 * pass the U_SUCCESS() test, or else the function returns
1369 * immediately. Check for U_FAILURE() on output or use with
1370 * function chaining. (See User Guide for details.)
1371 * @return The pointer to destination buffer.
1372 * @see u_strFromUTF8
1373 * @see u_strFromUTF8Lenient
1374 * @see u_strToUTF8WithSub
1375 * @stable ICU 3.6
1376 */
1377U_CAPI UChar* U_EXPORT2
1378u_strFromUTF8WithSub(UChar *dest,
1379 int32_t destCapacity,
1380 int32_t *pDestLength,
1381 const char *src,
1382 int32_t srcLength,
1383 UChar32 subchar, int32_t *pNumSubstitutions,
1384 UErrorCode *pErrorCode);
1385
1386/**
1387 * Convert a UTF-8 string to UTF-16.
1388 *
1389 * Same as u_strFromUTF8() except that this function is designed to be very fast,
1390 * which it achieves by being lenient about malformed UTF-8 sequences.
1391 * This function is intended for use in environments where UTF-8 text is
1392 * expected to be well-formed.
1393 *
1394 * Its semantics are:
1395 * - Well-formed UTF-8 text is correctly converted to well-formed UTF-16 text.
1396 * - The function will not read beyond the input string, nor write beyond
1397 * the destCapacity.
1398 * - Malformed UTF-8 results in "garbage" 16-bit Unicode strings which may not
1399 * be well-formed UTF-16.
1400 * The function will resynchronize to valid code point boundaries
1401 * within a small number of code points after an illegal sequence.
1402 * - Non-shortest forms are not detected and will result in "spoofing" output.
1403 *
1404 * For further performance improvement, if srcLength is given (>=0),
1405 * then it must be destCapacity>=srcLength.
1406 *
1407 * There is no inverse u_strToUTF8Lenient() function because there is practically
1408 * no performance gain from not checking that a UTF-16 string is well-formed.
1409 *
1410 * @param dest A buffer for the result string. The result will be zero-terminated if
1411 * the buffer is large enough.
1412 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1413 * dest may be NULL and the function will only return the length of the
1414 * result without writing any of the result string (pre-flighting).
1415 * Unlike for other ICU functions, if srcLength>=0 then it
1416 * must be destCapacity>=srcLength.
1417 * @param pDestLength A pointer to receive the number of units written to the destination. If
1418 * pDestLength!=NULL then *pDestLength is always set to the
1419 * number of output units corresponding to the transformation of
1420 * all the input units, even in case of a buffer overflow.
1421 * Unlike for other ICU functions, if srcLength>=0 but
1422 * destCapacity<srcLength, then *pDestLength will be set to srcLength
1423 * (and U_BUFFER_OVERFLOW_ERROR will be set)
1424 * regardless of the actual result length.
1425 * @param src The original source string
1426 * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1427 * @param pErrorCode Pointer to a standard ICU error code. Its input value must
1428 * pass the U_SUCCESS() test, or else the function returns
1429 * immediately. Check for U_FAILURE() on output or use with
1430 * function chaining. (See User Guide for details.)
1431 * @return The pointer to destination buffer.
1432 * @see u_strFromUTF8
1433 * @see u_strFromUTF8WithSub
1434 * @see u_strToUTF8WithSub
1435 * @stable ICU 3.6
1436 */
1437U_CAPI UChar * U_EXPORT2
1438u_strFromUTF8Lenient(UChar *dest,
1439 int32_t destCapacity,
1440 int32_t *pDestLength,
1441 const char *src,
1442 int32_t srcLength,
1443 UErrorCode *pErrorCode);
1444
1445/**
1446 * Convert a UTF-16 string to UTF-32.
1447 * If the input string is not well-formed, then the U_INVALID_CHAR_FOUND error code is set.
1448 *
1449 * @param dest A buffer for the result string. The result will be zero-terminated if
1450 * the buffer is large enough.
1451 * @param destCapacity The size of the buffer (number of UChar32s). If it is 0, then
1452 * dest may be NULL and the function will only return the length of the
1453 * result without writing any of the result string (pre-flighting).
1454 * @param pDestLength A pointer to receive the number of units written to the destination. If
1455 * pDestLength!=NULL then *pDestLength is always set to the
1456 * number of output units corresponding to the transformation of
1457 * all the input units, even in case of a buffer overflow.
1458 * @param src The original source string
1459 * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1460 * @param pErrorCode Must be a valid pointer to an error code value,
1461 * which must not indicate a failure before the function call.
1462 * @return The pointer to destination buffer.
1463 * @see u_strToUTF32WithSub
1464 * @see u_strFromUTF32
1465 * @stable ICU 2.0
1466 */
1467U_CAPI UChar32* U_EXPORT2
1468u_strToUTF32(UChar32 *dest,
1469 int32_t destCapacity,
1470 int32_t *pDestLength,
1471 const UChar *src,
1472 int32_t srcLength,
1473 UErrorCode *pErrorCode);
1474
1475/**
1476 * Convert a UTF-32 string to UTF-16.
1477 * If the input string is not well-formed, then the U_INVALID_CHAR_FOUND error code is set.
1478 *
1479 * @param dest A buffer for the result string. The result will be zero-terminated if
1480 * the buffer is large enough.
1481 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1482 * dest may be NULL and the function will only return the length of the
1483 * result without writing any of the result string (pre-flighting).
1484 * @param pDestLength A pointer to receive the number of units written to the destination. If
1485 * pDestLength!=NULL then *pDestLength is always set to the
1486 * number of output units corresponding to the transformation of
1487 * all the input units, even in case of a buffer overflow.
1488 * @param src The original source string
1489 * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1490 * @param pErrorCode Must be a valid pointer to an error code value,
1491 * which must not indicate a failure before the function call.
1492 * @return The pointer to destination buffer.
1493 * @see u_strFromUTF32WithSub
1494 * @see u_strToUTF32
1495 * @stable ICU 2.0
1496 */
1497U_CAPI UChar* U_EXPORT2
1498u_strFromUTF32(UChar *dest,
1499 int32_t destCapacity,
1500 int32_t *pDestLength,
1501 const UChar32 *src,
1502 int32_t srcLength,
1503 UErrorCode *pErrorCode);
1504
1505/**
1506 * Convert a UTF-16 string to UTF-32.
1507 *
1508 * Same as u_strToUTF32() except for the additional subchar which is output for
1509 * illegal input sequences, instead of stopping with the U_INVALID_CHAR_FOUND error code.
1510 * With subchar==U_SENTINEL, this function behaves exactly like u_strToUTF32().
1511 *
1512 * @param dest A buffer for the result string. The result will be zero-terminated if
1513 * the buffer is large enough.
1514 * @param destCapacity The size of the buffer (number of UChar32s). If it is 0, then
1515 * dest may be NULL and the function will only return the length of the
1516 * result without writing any of the result string (pre-flighting).
1517 * @param pDestLength A pointer to receive the number of units written to the destination. If
1518 * pDestLength!=NULL then *pDestLength is always set to the
1519 * number of output units corresponding to the transformation of
1520 * all the input units, even in case of a buffer overflow.
1521 * @param src The original source string
1522 * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1523 * @param subchar The substitution character to use in place of an illegal input sequence,
1524 * or U_SENTINEL if the function is to return with U_INVALID_CHAR_FOUND instead.
1525 * A substitution character can be any valid Unicode code point (up to U+10FFFF)
1526 * except for surrogate code points (U+D800..U+DFFF).
1527 * The recommended value is U+FFFD "REPLACEMENT CHARACTER".
1528 * @param pNumSubstitutions Output parameter receiving the number of substitutions if subchar>=0.
1529 * Set to 0 if no substitutions occur or subchar<0.
1530 * pNumSubstitutions can be NULL.
1531 * @param pErrorCode Pointer to a standard ICU error code. Its input value must
1532 * pass the U_SUCCESS() test, or else the function returns
1533 * immediately. Check for U_FAILURE() on output or use with
1534 * function chaining. (See User Guide for details.)
1535 * @return The pointer to destination buffer.
1536 * @see u_strToUTF32
1537 * @see u_strFromUTF32WithSub
1538 * @stable ICU 4.2
1539 */
1540U_CAPI UChar32* U_EXPORT2
1541u_strToUTF32WithSub(UChar32 *dest,
1542 int32_t destCapacity,
1543 int32_t *pDestLength,
1544 const UChar *src,
1545 int32_t srcLength,
1546 UChar32 subchar, int32_t *pNumSubstitutions,
1547 UErrorCode *pErrorCode);
1548
1549/**
1550 * Convert a UTF-32 string to UTF-16.
1551 *
1552 * Same as u_strFromUTF32() except for the additional subchar which is output for
1553 * illegal input sequences, instead of stopping with the U_INVALID_CHAR_FOUND error code.
1554 * With subchar==U_SENTINEL, this function behaves exactly like u_strFromUTF32().
1555 *
1556 * @param dest A buffer for the result string. The result will be zero-terminated if
1557 * the buffer is large enough.
1558 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1559 * dest may be NULL and the function will only return the length of the
1560 * result without writing any of the result string (pre-flighting).
1561 * @param pDestLength A pointer to receive the number of units written to the destination. If
1562 * pDestLength!=NULL then *pDestLength is always set to the
1563 * number of output units corresponding to the transformation of
1564 * all the input units, even in case of a buffer overflow.
1565 * @param src The original source string
1566 * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1567 * @param subchar The substitution character to use in place of an illegal input sequence,
1568 * or U_SENTINEL if the function is to return with U_INVALID_CHAR_FOUND instead.
1569 * A substitution character can be any valid Unicode code point (up to U+10FFFF)
1570 * except for surrogate code points (U+D800..U+DFFF).
1571 * The recommended value is U+FFFD "REPLACEMENT CHARACTER".
1572 * @param pNumSubstitutions Output parameter receiving the number of substitutions if subchar>=0.
1573 * Set to 0 if no substitutions occur or subchar<0.
1574 * pNumSubstitutions can be NULL.
1575 * @param pErrorCode Pointer to a standard ICU error code. Its input value must
1576 * pass the U_SUCCESS() test, or else the function returns
1577 * immediately. Check for U_FAILURE() on output or use with
1578 * function chaining. (See User Guide for details.)
1579 * @return The pointer to destination buffer.
1580 * @see u_strFromUTF32
1581 * @see u_strToUTF32WithSub
1582 * @stable ICU 4.2
1583 */
1584U_CAPI UChar* U_EXPORT2
1585u_strFromUTF32WithSub(UChar *dest,
1586 int32_t destCapacity,
1587 int32_t *pDestLength,
1588 const UChar32 *src,
1589 int32_t srcLength,
1590 UChar32 subchar, int32_t *pNumSubstitutions,
1591 UErrorCode *pErrorCode);
1592
1593/**
1594 * Convert a 16-bit Unicode string to Java Modified UTF-8.
1595 * See http://java.sun.com/javase/6/docs/api/java/io/DataInput.html#modified-utf-8
1596 *
1597 * This function behaves according to the documentation for Java DataOutput.writeUTF()
1598 * except that it does not encode the output length in the destination buffer
1599 * and does not have an output length restriction.
1600 * See http://java.sun.com/javase/6/docs/api/java/io/DataOutput.html#writeUTF(java.lang.String)
1601 *
1602 * The input string need not be well-formed UTF-16.
1603 * (Therefore there is no subchar parameter.)
1604 *
1605 * @param dest A buffer for the result string. The result will be zero-terminated if
1606 * the buffer is large enough.
1607 * @param destCapacity The size of the buffer (number of chars). If it is 0, then
1608 * dest may be NULL and the function will only return the length of the
1609 * result without writing any of the result string (pre-flighting).
1610 * @param pDestLength A pointer to receive the number of units written to the destination. If
1611 * pDestLength!=NULL then *pDestLength is always set to the
1612 * number of output units corresponding to the transformation of
1613 * all the input units, even in case of a buffer overflow.
1614 * @param src The original source string
1615 * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1616 * @param pErrorCode Pointer to a standard ICU error code. Its input value must
1617 * pass the U_SUCCESS() test, or else the function returns
1618 * immediately. Check for U_FAILURE() on output or use with
1619 * function chaining. (See User Guide for details.)
1620 * @return The pointer to destination buffer.
1621 * @stable ICU 4.4
1622 * @see u_strToUTF8WithSub
1623 * @see u_strFromJavaModifiedUTF8WithSub
1624 */
1625U_CAPI char* U_EXPORT2
1626u_strToJavaModifiedUTF8(
1627 char *dest,
1628 int32_t destCapacity,
1629 int32_t *pDestLength,
1630 const UChar *src,
1631 int32_t srcLength,
1632 UErrorCode *pErrorCode);
1633
1634/**
1635 * Convert a Java Modified UTF-8 string to a 16-bit Unicode string.
1636 * If the input string is not well-formed and no substitution char is specified,
1637 * then the U_INVALID_CHAR_FOUND error code is set.
1638 *
1639 * This function behaves according to the documentation for Java DataInput.readUTF()
1640 * except that it takes a length parameter rather than
1641 * interpreting the first two input bytes as the length.
1642 * See http://java.sun.com/javase/6/docs/api/java/io/DataInput.html#readUTF()
1643 *
1644 * The output string may not be well-formed UTF-16.
1645 *
1646 * @param dest A buffer for the result string. The result will be zero-terminated if
1647 * the buffer is large enough.
1648 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
1649 * dest may be NULL and the function will only return the length of the
1650 * result without writing any of the result string (pre-flighting).
1651 * @param pDestLength A pointer to receive the number of units written to the destination. If
1652 * pDestLength!=NULL then *pDestLength is always set to the
1653 * number of output units corresponding to the transformation of
1654 * all the input units, even in case of a buffer overflow.
1655 * @param src The original source string
1656 * @param srcLength The length of the original string. If -1, then src must be zero-terminated.
1657 * @param subchar The substitution character to use in place of an illegal input sequence,
1658 * or U_SENTINEL if the function is to return with U_INVALID_CHAR_FOUND instead.
1659 * A substitution character can be any valid Unicode code point (up to U+10FFFF)
1660 * except for surrogate code points (U+D800..U+DFFF).
1661 * The recommended value is U+FFFD "REPLACEMENT CHARACTER".
1662 * @param pNumSubstitutions Output parameter receiving the number of substitutions if subchar>=0.
1663 * Set to 0 if no substitutions occur or subchar<0.
1664 * pNumSubstitutions can be NULL.
1665 * @param pErrorCode Pointer to a standard ICU error code. Its input value must
1666 * pass the U_SUCCESS() test, or else the function returns
1667 * immediately. Check for U_FAILURE() on output or use with
1668 * function chaining. (See User Guide for details.)
1669 * @return The pointer to destination buffer.
1670 * @see u_strFromUTF8WithSub
1671 * @see u_strFromUTF8Lenient
1672 * @see u_strToJavaModifiedUTF8
1673 * @stable ICU 4.4
1674 */
1675U_CAPI UChar* U_EXPORT2
1676u_strFromJavaModifiedUTF8WithSub(
1677 UChar *dest,
1678 int32_t destCapacity,
1679 int32_t *pDestLength,
1680 const char *src,
1681 int32_t srcLength,
1682 UChar32 subchar, int32_t *pNumSubstitutions,
1683 UErrorCode *pErrorCode);
1684
1685#endif
1686