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