2
**********************************************************************
3
* Copyright (C) 1998-2001, International Business Machines
4
* Corporation and others. All Rights Reserved.
5
**********************************************************************
9
* Modification History:
11
* Date Name Description
12
* 12/07/98 bertrand Creation.
13
******************************************************************************
18
#include "unicode/utypes.h"
20
/** Simple declaration for u_strToTitle() to avoid including unicode/ubrk.h. */
21
#ifndef UBRK_TYPEDEF_UBREAK_ITERATOR
22
# define UBRK_TYPEDEF_UBREAK_ITERATOR
23
typedef void *UBreakIterator;
28
* \brief C API: Unicode string handling functions
30
* These C API functions provide Unicode string handling.
32
* Some functions are equivalent in name, signature, and behavior to the ANSI C <string.h>
33
* functions. (For example, they do not check for bad arguments like NULL string pointers.)
34
* In some cases, only the thread-safe variant of such a function is implemented here
37
* Other functions provide more Unicode-specific functionality like locale-specific
38
* upper/lower-casing and string comparison in code point order.
40
* ICU uses 16-bit Unicode (UTF-16) in the form of arrays of UChar code units.
41
* UTF-16 encodes each Unicode code point with either one or two UChar code units.
42
* Some APIs accept a 32-bit UChar32 value for a single code point.
43
* (This is the default form of Unicode, and a forward-compatible extension of the original,
44
* fixed-width form that was known as UCS-2. UTF-16 superseded UCS-2 with Unicode 2.0
47
* Although UTF-16 is a variable-width encoding form (like some legacy multi-byte encodings),
48
* it is much more efficient even for random access because the code unit values
49
* for single-unit characters vs. lead units vs. trail units are completely disjoint.
50
* This means that it is easy to determine character (code point) boundaries from
51
* random offsets in the string.
52
* (It also means, e.g., that u_strstr() does not need to verify that a match was
53
* found on actual character boundaries; with some legacy encodings, strstr() may need to
54
* scan back to the start of the text to verify this.)
56
* Unicode (UTF-16) string processing is optimized for the single-unit case.
57
* Although it is important to support supplementary characters
58
* (which use pairs of lead/trail code units called "surrogates"),
59
* their occurrence is rare. Almost all characters in modern use require only
60
* a single UChar code unit (i.e., their code point values are <=0xffff).
64
* Determine the length of an array of UChar.
66
* @param s The array of UChars, NULL (U+0000) terminated.
67
* @return The number of UChars in <TT>chars</TT>, minus the terminator.
70
U_CAPI int32_t U_EXPORT2
71
u_strlen(const UChar *s);
74
* Count Unicode code points in the length UChar code units of the string.
75
* A code point may occupy either one or two UChar code units.
76
* Counting code points involves reading all code units.
78
* This functions is basically the inverse of the UTF_FWD_N() macro (see utf.h).
80
* @param s The input string.
81
* @param length The number of UChar code units to be checked, or -1 to count all
82
* code points before the first NUL (U+0000).
83
* @return The number of code points in the specified code units.
86
U_CAPI int32_t U_EXPORT2
87
u_countChar32(const UChar *s, int32_t length);
90
* Concatenate two ustrings. Appends a copy of <TT>src</TT>,
91
* including the null terminator, to <TT>dst</TT>. The initial copied
92
* character from <TT>src</TT> overwrites the null terminator in <TT>dst</TT>.
94
* @param dst The destination string.
95
* @param src The source string.
96
* @return A pointer to <TT>dst</TT>.
99
U_CAPI UChar* U_EXPORT2
104
* Concatenate two ustrings.
105
* Appends at most <TT>n</TT> characters from <TT>src</TT> to <TT>dst</TT>.
106
* Adds a null terminator.
108
* @param dst The destination string.
109
* @param src The source string.
110
* @param n The maximum number of characters to compare.
111
* @return A pointer to <TT>dst</TT>.
114
U_CAPI UChar* U_EXPORT2
115
u_strncat(UChar *dst,
120
* Find the first occurrence of a specified character in a ustring.
122
* @param s The string to search.
123
* @param c The character to find.
124
* @return A pointer to the first occurrence of <TT>c</TT> in <TT>s</TT>,
125
* or a null pointer if <TT>s</TT> does not contain <TT>c</TT>.
128
U_CAPI UChar* U_EXPORT2
129
u_strchr(const UChar *s,
133
* Find the first occurrence of a substring in a string.
135
* @param s The string to search.
136
* @return A pointer to the first occurrence of <TT>substring</TT> in
137
* <TT>s</TT>, or a null pointer if <TT>substring</TT>
138
* is not in <TT>s</TT>.
141
U_CAPI UChar * U_EXPORT2
142
u_strstr(const UChar *s, const UChar *substring);
145
* Find the first occurence of a specified code point in a string.
147
* This function finds code points, which differs for BMP code points
148
* from u_strchr() only for surrogates:
149
* While u_strchr() finds any surrogate code units in a string,
150
* u_strchr32() finds only unmatched surrogate code points,
151
* i.e., only those that do not combine with an adjacent surrogate
152
* to form a supplementary code point.
153
* For example, in a string "\ud800\udc00" u_strchr()
154
* will find code units U+d800 at 0 and U+dc00 at 1,
155
* but u_strchr32() will find neither because they
156
* combine to the code point U+10000.
157
* Either function will find U+d800 in "a\ud800b".
158
* This behavior ensures that UTF_GET_CHAR(u_strchr32(c))==c.
160
* @param s The string to search.
161
* @param c The code point (0..0x10ffff) to find.
162
* @return A pointer to the first occurrence of <TT>c</TT> in <TT>s</TT>,
163
* or a null pointer if there is no such character.
164
* If <TT>c</TT> is represented with several UChars, then the returned
165
* pointer will point to the first of them.
168
U_CAPI UChar * U_EXPORT2
169
u_strchr32(const UChar *s, UChar32 c);
172
* Locates the first occurrence in the string str of any of the characters
173
* in the string accept.
174
* Works just like C's strpbrk but with Unicode.
176
* @return A pointer to the character in str that matches one of the
177
* characters in accept, or NULL if no such character is found.
180
U_CAPI UChar * U_EXPORT2
181
u_strpbrk(const UChar *string, const UChar *matchSet);
184
* Returns the number of consecutive characters in string1,
185
* beginning with the first, that do not occur somewhere in string2.
186
* Works just like C's strcspn but with Unicode.
191
U_CAPI int32_t U_EXPORT2
192
u_strcspn(const UChar *string, const UChar *matchSet);
195
* Returns the number of consecutive characters in string1,
196
* beginning with the first, that occur somewhere in string2.
197
* Works just like C's strspn but with Unicode.
202
U_CAPI int32_t U_EXPORT2
203
u_strspn(const UChar *string, const UChar *matchSet);
206
* The string tokenizer API allows an application to break a string into
207
* tokens. Unlike strtok(), the saveState (the current pointer within the
208
* original string) is maintained in saveState. In the first call, the
209
* argument src is a pointer to the string. In subsequent calls to
210
* return successive tokens of that string, src must be specified as
211
* NULL. The value saveState is set by this function to maintain the
212
* function's position within the string, and on each subsequent call
213
* you must give this argument the same variable. This function does
214
* handle surrogate pairs. This function is similar to the strtok_r()
215
* the POSIX Threads Extension (1003.1c-1995) version.
217
* @param src String containing token(s). This string will be modified.
218
* After the first call to u_strtok_r(), this argument must
219
* be NULL to get to the next token.
220
* @param delim Set of delimiter characters (Unicode code points).
221
* @param saveState The current pointer within the original string,
222
* which is set by this function. The saveState
223
* parameter should the address of a local variable of type
224
* UChar *. (i.e. defined "Uhar *myLocalSaveState" and use
225
* &myLocalSaveState for this parameter).
226
* @return A pointer to the next token found in src, or NULL
227
* when there are no more tokens.
230
U_CAPI UChar * U_EXPORT2
231
u_strtok_r(UChar *src,
236
* Compare two Unicode strings for bitwise equality (code unit order).
238
* @param s1 A string to compare.
239
* @param s2 A string to compare.
240
* @return 0 if <TT>s1</TT> and <TT>s2</TT> are bitwise equal; a negative
241
* value if <TT>s1</TT> is bitwise less than <TT>s2,/TT>; a positive
242
* value if <TT>s1</TT> is bitwise greater than <TT>s2,/TT>.
245
U_CAPI int32_t U_EXPORT2
246
u_strcmp(const UChar *s1,
250
* Compare two Unicode strings in code point order.
251
* This is different in UTF-16 from u_strcmp() if supplementary characters are present:
252
* In UTF-16, supplementary characters (with code points U+10000 and above) are
253
* stored with pairs of surrogate code units. These have values from 0xd800 to
254
* 0xdfff, which means that they compare as less than some other BMP characters
255
* like U+feff. This function compares Unicode strings in code point order.
256
* If eihter of the UTF-16 strings is malformed (i.e., it contains unpaired
257
* surrogates), then the result is not defined.
259
* @param s1 A string to compare.
260
* @param s2 A string to compare.
261
* @return a negative/zero/positive integer corresponding to whether
262
* the first string is less than/equal to/greater than the second one
263
* in code point order
266
U_CAPI int32_t U_EXPORT2
267
u_strcmpCodePointOrder(const UChar *s1, const UChar *s2);
270
* Compare two ustrings for bitwise equality.
271
* Compares at most <TT>n</TT> characters.
273
* @param s1 A string to compare.
274
* @param s2 A string to compare.
275
* @param n The maximum number of characters to compare.
276
* @return 0 if <TT>s1</TT> and <TT>s2</TT> are bitwise equal; a negative
277
* value if <TT>s1</TT> is bitwise less than <TT>s2,/TT>; a positive
278
* value if <TT>s1</TT> is bitwise greater than <TT>s2,/TT>.
281
U_CAPI int32_t U_EXPORT2
282
u_strncmp(const UChar *ucs1,
287
* Compare two Unicode strings in code point order.
288
* This is different in UTF-16 from u_strncmp() if supplementary characters are present.
289
* For details, see u_strcmpCodePointOrder().
291
* @param s1 A string to compare.
292
* @param s2 A string to compare.
293
* @param n The maximum number of characters to compare.
294
* @return a negative/zero/positive integer corresponding to whether
295
* the first string is less than/equal to/greater than the second one
296
* in code point order
299
U_CAPI int32_t U_EXPORT2
300
u_strncmpCodePointOrder(const UChar *s1, const UChar *s2, int32_t n);
303
* Compare two strings case-insensitively using full case folding.
304
* This is equivalent to u_strcmp(u_strFoldCase(s1, options), u_strFoldCase(s2, options)).
306
* @param s1 A string to compare.
307
* @param s2 A string to compare.
308
* @param options Either U_FOLD_CASE_DEFAULT or U_FOLD_CASE_EXCLUDE_SPECIAL_I
309
* @return A negative, zero, or positive integer indicating the comparison result.
312
U_CAPI int32_t U_EXPORT2
313
u_strcasecmp(const UChar *s1, const UChar *s2, uint32_t options);
316
* Compare two strings case-insensitively using full case folding.
317
* This is equivalent to u_strcmp(u_strFoldCase(s1, at most n, options),
318
* u_strFoldCase(s2, at most n, options)).
320
* @param s1 A string to compare.
321
* @param s2 A string to compare.
322
* @param n The maximum number of characters each string to case-fold and then compare.
323
* @param options Either U_FOLD_CASE_DEFAULT or U_FOLD_CASE_EXCLUDE_SPECIAL_I
324
* @return A negative, zero, or positive integer indicating the comparison result.
327
U_CAPI int32_t U_EXPORT2
328
u_strncasecmp(const UChar *s1, const UChar *s2, int32_t n, uint32_t options);
331
* Compare two strings case-insensitively using full case folding.
332
* This is equivalent to u_strcmp(u_strFoldCase(s1, n, options),
333
* u_strFoldCase(s2, n, options)).
335
* @param s1 A string to compare.
336
* @param s2 A string to compare.
337
* @param n The number of characters in each string to case-fold and then compare.
338
* @param options Either U_FOLD_CASE_DEFAULT or U_FOLD_CASE_EXCLUDE_SPECIAL_I
339
* @return A negative, zero, or positive integer indicating the comparison result.
342
U_CAPI int32_t U_EXPORT2
343
u_memcasecmp(const UChar *s1, const UChar *s2, int32_t length, uint32_t options);
346
* Copy a ustring. Adds a null terminator.
348
* @param dst The destination string.
349
* @param src The source string.
350
* @return A pointer to <TT>dst</TT>.
353
U_CAPI UChar* U_EXPORT2
359
* Copies at most <TT>n</TT> characters. The result will be null terminated
360
* if the length of <TT>src</TT> is less than <TT>n</TT>.
362
* @param dst The destination string.
363
* @param src The source string.
364
* @param n The maximum number of characters to copy.
365
* @return A pointer to <TT>dst</TT>.
368
U_CAPI UChar* U_EXPORT2
369
u_strncpy(UChar *dst,
374
* Copy a byte string encoded in the default codepage to a ustring.
375
* Adds a null terminator.
376
* Performs a host byte to UChar conversion
378
* @param dst The destination string.
379
* @param src The source string.
380
* @return A pointer to <TT>dst</TT>.
383
U_CAPI UChar* U_EXPORT2 u_uastrcpy(UChar *dst,
387
* Copy a byte string encoded in the default codepage to a ustring.
388
* Copies at most <TT>n</TT> characters. The result will be null terminated
389
* if the length of <TT>src</TT> is less than <TT>n</TT>.
390
* Performs a host byte to UChar conversion
392
* @param dst The destination string.
393
* @param src The source string.
394
* @param n The maximum number of characters to copy.
395
* @return A pointer to <TT>dst</TT>.
398
U_CAPI UChar* U_EXPORT2 u_uastrncpy(UChar *dst,
403
* Copy ustring to a byte string encoded in the default codepage.
404
* Adds a null terminator.
405
* Performs a UChar to host byte conversion
407
* @param dst The destination string.
408
* @param src The source string.
409
* @return A pointer to <TT>dst</TT>.
412
U_CAPI char* U_EXPORT2 u_austrcpy(char *dst,
416
* Copy ustring to a byte string encoded in the default codepage.
417
* Copies at most <TT>n</TT> characters. The result will be null terminated
418
* if the length of <TT>src</TT> is less than <TT>n</TT>.
419
* Performs a UChar to host byte conversion
421
* @param dst The destination string.
422
* @param src The source string.
423
* @param n The maximum number of characters to copy.
424
* @return A pointer to <TT>dst</TT>.
427
U_CAPI char* U_EXPORT2 u_austrncpy(char *dst,
432
* Synonym for memcpy(), but with UChars only.
435
U_CAPI UChar* U_EXPORT2
436
u_memcpy(UChar *dest, const UChar *src, int32_t count);
439
* Synonym for memmove(), but with UChars only.
442
U_CAPI UChar* U_EXPORT2
443
u_memmove(UChar *dest, const UChar *src, int32_t count);
446
* Initialize <TT>count</TT> characters of <TT>dest</TT> to <TT>c</TT>.
448
* @param dest The destination string.
449
* @param c The character to initialize the string.
450
* @param count The maximum number of characters to set.
451
* @return A pointer to <TT>dest</TT>.
454
U_CAPI UChar* U_EXPORT2
455
u_memset(UChar *dest, UChar c, int32_t count);
458
* Compare the first <TT>count</TT> UChars of each buffer.
460
* @param buf1 The first string to compare.
461
* @param buf2 The second string to compare.
462
* @param count The maximum number of UChars to compare.
463
* @return When buf1 < buf2, a negative number is returned.
464
* When buf1 == buf2, 0 is returned.
465
* When buf1 > buf2, a positive number is returned.
468
U_CAPI int32_t U_EXPORT2
469
u_memcmp(const UChar *buf1, const UChar *buf2, int32_t count);
472
* Compare two Unicode strings in code point order.
473
* This is different in UTF-16 from u_memcmp() if supplementary characters are present.
474
* For details, see u_strcmpCodePointOrder().
476
* @param s1 A string to compare.
477
* @param s2 A string to compare.
478
* @param n The maximum number of characters to compare.
479
* @return a negative/zero/positive integer corresponding to whether
480
* the first string is less than/equal to/greater than the second one
481
* in code point order
484
U_CAPI int32_t U_EXPORT2
485
u_memcmpCodePointOrder(const UChar *s1, const UChar *s2, int32_t count);
488
* Search for a UChar within a Unicode string until <TT>count</TT>
491
* @param src string to search in
492
* @param ch character to find
493
* @param count maximum number of UChars in <TT>src</TT>to search for
495
* @return A pointer within src, pointing to <TT>ch</TT>, or NULL if it
499
U_CAPI UChar* U_EXPORT2
500
u_memchr(const UChar *src, UChar ch, int32_t count);
503
* Find the first occurence of a specified code point in a string.
505
* This function finds code points, which differs for BMP code points
506
* from u_memchr() only for surrogates:
507
* While u_memchr() finds any surrogate code units in a string,
508
* u_memchr32() finds only unmatched surrogate code points,
509
* i.e., only those that do not combine with an adjacent surrogate
510
* to form a supplementary code point.
511
* For example, in a string "\ud800\udc00" u_memchr()
512
* will find code units U+d800 at 0 and U+dc00 at 1,
513
* but u_memchr32() will find neither because they
514
* combine to the code point U+10000.
515
* Either function will find U+d800 in "a\ud800b".
516
* This behavior ensures that UTF_GET_CHAR(u_memchr32(c))==c.
518
* @param src string to search in
519
* @param ch character to find
520
* @param count maximum number of UChars in <TT>src</TT>to search for
522
* @return A pointer within src, pointing to <TT>ch</TT>, or NULL if it
526
U_CAPI UChar* U_EXPORT2
527
u_memchr32(const UChar *src, UChar32 ch, int32_t count);
530
* Unicode String literals in C.
531
* We need one macro to declare a variable for the string
532
* and to statically preinitialize it if possible,
533
* and a second macro to dynamically intialize such a string variable if necessary.
535
* The macros are defined for maximum performance.
536
* They work only for strings that contain "invariant characters", i.e.,
537
* only latin letters, digits, and some punctuation.
538
* See utypes.h for details.
540
* A pair of macros for a single string must be used with the same
542
* The string parameter must be a C string literal.
543
* The length of the string, not including the terminating
544
* <code>NUL</code>, must be specified as a constant.
545
* The U_STRING_DECL macro should be invoked exactly once for one
546
* such string variable before it is used.
550
*   U_STRING_DECL(ustringVar1, "Quick-Fox 2", 11);
551
*   U_STRING_DECL(ustringVar2, "jumps 5%", 8);
552
*   static UBool didInit=FALSE;
554
*   int32_t function() {
555
*   if(!didInit) {
556
*   U_STRING_INIT(ustringVar1, "Quick-Fox 2", 11);
557
*   U_STRING_INIT(ustringVar2, "jumps 5%", 8);
558
*   didInit=TRUE;
560
*   return u_strcmp(ustringVar1, ustringVar2);
565
#if U_SIZEOF_WCHAR_T==U_SIZEOF_UCHAR && U_CHARSET_FAMILY==U_ASCII_FAMILY
566
# define U_STRING_DECL(var, cs, length) static const wchar_t var[(length)+1]={ L ## cs }
567
# define U_STRING_INIT(var, cs, length)
568
#elif U_SIZEOF_UCHAR==1 && U_CHARSET_FAMILY==U_ASCII_FAMILY
569
# define U_STRING_DECL(var, cs, length) static const UChar var[(length)+1]={ (const UChar *)cs }
570
# define U_STRING_INIT(var, cs, length)
572
# define U_STRING_DECL(var, cs, length) static UChar var[(length)+1]
573
# define U_STRING_INIT(var, cs, length) u_charsToUChars(cs, var, length+1)
577
* Unescape a string of characters and write the resulting
578
* Unicode characters to the destination buffer. The following escape
579
* sequences are recognized:
581
* \uhhhh 4 hex digits; h in [0-9A-Fa-f]
582
* \Uhhhhhhhh 8 hex digits
583
* \xhh 1-2 hex digits
584
* \ooo 1-3 octal digits; o in [0-7]
586
* as well as the standard ANSI C escapes:
588
* \a => U+0007, \b => U+0008, \t => U+0009, \n => U+000A,
589
* \v => U+000B, \f => U+000C, \r => U+000D,
590
* \" => U+0022, \' => U+0027, \? => U+003F, \\ => U+005C
592
* Anything else following a backslash is generically escaped. For
593
* example, "[a\-z]" returns "[a-z]".
595
* If an escape sequence is ill-formed, this method returns an empty
596
* string. An example of an ill-formed sequence is "\u" followed by
597
* fewer than 4 hex digits.
599
* The above characters are recognized in the compiler's codepage,
600
* that is, they are coded as 'u', '\\', etc. Characters that are
601
* not parts of escape sequences are converted using u_charsToUChars().
603
* This function is similar to UnicodeString::unescape() but not
604
* identical to it. The latter takes a source UnicodeString, so it
605
* does escape recognition but no conversion.
607
* @param src a zero-terminated string of invariant characters
608
* @param dest pointer to buffer to receive converted and unescaped
609
* text and, if there is room, a zero terminator. May be NULL for
610
* preflighting, in which case no UChars will be written, but the
611
* return value will still be valid. On error, an empty string is
612
* stored here (if possible).
613
* @param destCapacity the number of UChars that may be written at
614
* dest. Ignored if dest == NULL.
615
* @return the capacity required to fully convert all of the source
616
* text, including the zero terminator, or 0 on error.
618
* @see UnicodeString#unescape()
619
* @see UnicodeString#unescapeAt()
622
U_CAPI int32_t U_EXPORT2
623
u_unescape(const char *src,
624
UChar *dest, int32_t destCapacity);
627
* Callback function for u_unescapeAt() that returns a character of
628
* the source text given an offset and a context pointer. The context
629
* pointer will be whatever is passed into u_unescapeAt().
635
typedef UChar (*UNESCAPE_CHAR_AT)(int32_t offset, void *context);
639
* Unescape a single sequence. The character at offset-1 is assumed
640
* (without checking) to be a backslash. This method takes a callback
641
* pointer to a function that returns the UChar at a given offset. By
642
* varying this callback, ICU functions are able to unescape char*
643
* strings, UnicodeString objects, and UFILE pointers.
645
* If offset is out of range, or if the escape sequence is ill-formed,
646
* (UChar32)0xFFFFFFFF is returned. See documentation of u_unescape()
647
* for a list of recognized sequences.
649
* @param charAt callback function that returns a UChar of the source
650
* text given an offset and a context pointer.
651
* @param offset pointer to the offset that will be passed to charAt.
652
* The offset value will be updated upon return to point after the
653
* last parsed character of the escape sequence. On error the offset
655
* @param length the number of characters in the source text. The
656
* last character of the source text is considered to be at offset
658
* @param context an opaque pointer passed directly into charAt.
659
* @return the character represented by the escape sequence at
660
* offset, or (UChar32)0xFFFFFFFF on error.
662
* @see UnicodeString#unescape()
663
* @see UnicodeString#unescapeAt()
666
U_CAPI UChar32 U_EXPORT2
667
u_unescapeAt(UNESCAPE_CHAR_AT charAt,
673
* Uppercase the characters in a string.
674
* Casing is locale-dependent and context-sensitive.
675
* The result may be longer or shorter than the original.
676
* The source string and the destination buffer are allowed to overlap.
678
* @param dest A buffer for the result string. The result will be zero-terminated if
679
* the buffer is large enough.
680
* @param destCapacity The size of the buffer (number of UChars). If it is 0, then
681
* dest may be NULL and the function will only return the length of the result
682
* without writing any of the result string.
683
* @param src The original string
684
* @param srcLength The length of the original string. If -1, then src must be zero-terminated.
685
* @param locale The locale to consider, or "" for the root locale or NULL for the default locale.
686
* @param pErrorCode Must be a valid pointer to an error code value,
687
* which must not indicate a failure before the function call.
688
* @return The length of the result string. It may be greater than destCapacity. In that case,
689
* only some of the result was written to the destination buffer.
692
U_CAPI int32_t U_EXPORT2
693
u_strToUpper(UChar *dest, int32_t destCapacity,
694
const UChar *src, int32_t srcLength,
696
UErrorCode *pErrorCode);
699
* Lowercase the characters in a string.
700
* Casing is locale-dependent and context-sensitive.
701
* The result may be longer or shorter than the original.
702
* The source string and the destination buffer are allowed to overlap.
704
* @param dest A buffer for the result string. The result will be zero-terminated if
705
* the buffer is large enough.
706
* @param destCapacity The size of the buffer (number of UChars). If it is 0, then
707
* dest may be NULL and the function will only return the length of the result
708
* without writing any of the result string.
709
* @param src The original string
710
* @param srcLength The length of the original string. If -1, then src must be zero-terminated.
711
* @param locale The locale to consider, or "" for the root locale or NULL for the default locale.
712
* @param pErrorCode Must be a valid pointer to an error code value,
713
* which must not indicate a failure before the function call.
714
* @return The length of the result string. It may be greater than destCapacity. In that case,
715
* only some of the result was written to the destination buffer.
718
U_CAPI int32_t U_EXPORT2
719
u_strToLower(UChar *dest, int32_t destCapacity,
720
const UChar *src, int32_t srcLength,
722
UErrorCode *pErrorCode);
725
* Titlecase a string.
726
* Casing is locale-dependent and context-sensitive.
727
* Titlecasing uses a break iterator to find the first characters of words
728
* that are to be titlecased. It titlecases those characters and lowercases
731
* The titlecase break iterator can be provided to customize for arbitrary
732
* styles, using rules and dictionaries beyond the standard iterators.
733
* It may be more efficient to always provide an iterator to avoid
734
* opening and closing one for each string.
735
* The standard titlecase iterator for the root locale implements the
736
* algorithm of Unicode TR 21.
738
* This function uses only the first() and next() methods of the
739
* provided break iterator.
741
* The result may be longer or shorter than the original.
742
* The source string and the destination buffer are allowed to overlap.
744
* @param dest A buffer for the result string. The result will be zero-terminated if
745
* the buffer is large enough.
746
* @param destCapacity The size of the buffer (number of UChars). If it is 0, then
747
* dest may be NULL and the function will only return the length of the result
748
* without writing any of the result string.
749
* @param src The original string
750
* @param srcLength The length of the original string. If -1, then src must be zero-terminated.
751
* @param titleIter A break iterator to find the first characters of words
752
* that are to be titlecased.
753
* If none is provided (NULL), then a standard titlecase
754
* break iterator is opened.
755
* @param locale The locale to consider, or "" for the root locale or NULL for the default locale.
756
* @param pErrorCode Must be a valid pointer to an error code value,
757
* which must not indicate a failure before the function call.
758
* @return The length of the result string. It may be greater than destCapacity. In that case,
759
* only some of the result was written to the destination buffer.
762
U_CAPI int32_t U_EXPORT2
763
u_strToTitle(UChar *dest, int32_t destCapacity,
764
const UChar *src, int32_t srcLength,
765
UBreakIterator *titleIter,
767
UErrorCode *pErrorCode);
770
* Case-fold the characters in a string.
771
* Case-folding is locale-independent and not context-sensitive,
772
* but there is an option for whether to include or exclude mappings for dotted I
773
* and dotless i that are marked with 'I' in CaseFolding.txt.
774
* The result may be longer or shorter than the original.
775
* The source string and the destination buffer are allowed to overlap.
777
* @param dest A buffer for the result string. The result will be zero-terminated if
778
* the buffer is large enough.
779
* @param destCapacity The size of the buffer (number of UChars). If it is 0, then
780
* dest may be NULL and the function will only return the length of the result
781
* without writing any of the result string.
782
* @param src The original string
783
* @param srcLength The length of the original string. If -1, then src must be zero-terminated.
784
* @param options Either U_FOLD_CASE_DEFAULT or U_FOLD_CASE_EXCLUDE_SPECIAL_I
785
* @param pErrorCode Must be a valid pointer to an error code value,
786
* which must not indicate a failure before the function call.
787
* @return The length of the result string. It may be greater than destCapacity. In that case,
788
* only some of the result was written to the destination buffer.
791
U_CAPI int32_t U_EXPORT2
792
u_strFoldCase(UChar *dest, int32_t destCapacity,
793
const UChar *src, int32_t srcLength,
795
UErrorCode *pErrorCode);
798
* Converts a sequence of UChars to wchar_t units.
800
* @param dest A buffer for the result string. The result will be zero-terminated if
801
* the buffer is large enough.
802
* @param destCapacity The size of the buffer (number of UChars). If it is 0, then
803
* dest may be NULL and the function will only return the length of the
804
* result without writing any of the result string (pre-flighting).
805
* @param pDestLength A pointer to receive the number of units written to the destination. If
806
* pDestLength!=NULL then *pDestLength is always set to the
807
* number of output units corresponding to the transformation of
808
* all the input units, even in case of a buffer overflow.
809
* @param src The original source string
810
* @param srcLength The length of the original string. If -1, then src must be zero-terminated.
811
* @param pErrorCode Must be a valid pointer to an error code value,
812
* which must not indicate a failure before the function call.
813
* @return The pointer to destination buffer.
816
U_CAPI wchar_t* U_EXPORT2
817
u_strToWCS(wchar_t *dest,
818
int32_t destCapacity,
819
int32_t *pDestLength,
822
UErrorCode *pErrorCode);
824
* Converts a sequence of wchar_t units to UChars
826
* @param dest A buffer for the result string. The result will be zero-terminated if
827
* the buffer is large enough.
828
* @param destCapacity The size of the buffer (number of UChars). If it is 0, then
829
* dest may be NULL and the function will only return the length of the
830
* result without writing any of the result string (pre-flighting).
831
* @param pDestLength A pointer to receive the number of units written to the destination. If
832
* pDestLength!=NULL then *pDestLength is always set to the
833
* number of output units corresponding to the transformation of
834
* all the input units, even in case of a buffer overflow.
835
* @param src The original source string
836
* @param srcLength The length of the original string. If -1, then src must be zero-terminated.
837
* @param pErrorCode Must be a valid pointer to an error code value,
838
* which must not indicate a failure before the function call.
839
* @return The pointer to destination buffer.
842
U_CAPI UChar* U_EXPORT2
843
u_strFromWCS(UChar *dest,
844
int32_t destCapacity,
845
int32_t *pDestLength,
848
UErrorCode *pErrorCode);
850
* Converts a sequence of UChars (UTF-16) to UTF-8 bytes
852
* @param dest A buffer for the result string. The result will be zero-terminated if
853
* the buffer is large enough.
854
* @param destCapacity The size of the buffer (number of UChars). If it is 0, then
855
* dest may be NULL and the function will only return the length of the
856
* result without writing any of the result string (pre-flighting).
857
* @param pDestLength A pointer to receive the number of units written to the destination. If
858
* pDestLength!=NULL then *pDestLength is always set to the
859
* number of output units corresponding to the transformation of
860
* all the input units, even in case of a buffer overflow.
861
* @param src The original source string
862
* @param srcLength The length of the original string. If -1, then src must be zero-terminated.
863
* @param pErrorCode Must be a valid pointer to an error code value,
864
* which must not indicate a failure before the function call.
865
* @return The pointer to destination buffer.
868
U_CAPI char* U_EXPORT2
869
u_strToUTF8(char *dest,
870
int32_t destCapacity,
871
int32_t *pDestLength,
874
UErrorCode *pErrorCode);
877
* Converts a sequence of UTF-8 bytes to UChars (UTF-16).
879
* @param dest A buffer for the result string. The result will be zero-terminated if
880
* the buffer is large enough.
881
* @param destCapacity The size of the buffer (number of UChars). If it is 0, then
882
* dest may be NULL and the function will only return the length of the
883
* result without writing any of the result string (pre-flighting).
884
* @param pDestLength A pointer to receive the number of units written to the destination. If
885
* pDestLength!=NULL then *pDestLength is always set to the
886
* number of output units corresponding to the transformation of
887
* all the input units, even in case of a buffer overflow.
888
* @param src The original source string
889
* @param srcLength The length of the original string. If -1, then src must be zero-terminated.
890
* @param pErrorCode Must be a valid pointer to an error code value,
891
* which must not indicate a failure before the function call.
892
* @return The pointer to destination buffer.
895
U_CAPI UChar* U_EXPORT2
896
u_strFromUTF8(UChar *dest,
897
int32_t destCapacity,
898
int32_t *pDestLength,
901
UErrorCode *pErrorCode);
904
* Converts a sequence of UTF32 units to UChars
906
* @param dest A buffer for the result string. The result will be zero-terminated if
907
* the buffer is large enough.
908
* @param destCapacity The size of the buffer (number of UChars). If it is 0, then
909
* dest may be NULL and the function will only return the length of the
910
* result without writing any of the result string (pre-flighting).
911
* @param pDestLength A pointer to receive the number of units written to the destination. If
912
* pDestLength!=NULL then *pDestLength is always set to the
913
* number of output units corresponding to the transformation of
914
* all the input units, even in case of a buffer overflow.
915
* @param src The original source string
916
* @param srcLength The length of the original string. If -1, then src must be zero-terminated.
917
* @param pErrorCode Must be a valid pointer to an error code value,
918
* which must not indicate a failure before the function call.
919
* @return The pointer to destination buffer.
922
U_CAPI UChar32* U_EXPORT2
923
u_strToUTF32(UChar32 *dest,
924
int32_t destCapacity,
925
int32_t *pDestLength,
928
UErrorCode *pErrorCode);
931
* Converts a sequence of UChars to UTF32 units.
933
* @param dest A buffer for the result string. The result will be zero-terminated if
934
* the buffer is large enough.
935
* @param destCapacity The size of the buffer (number of UChars). If it is 0, then
936
* dest may be NULL and the function will only return the length of the
937
* result without writing any of the result string (pre-flighting).
938
* @param pDestLength A pointer to receive the number of units written to the destination. If
939
* pDestLength!=NULL then *pDestLength is always set to the
940
* number of output units corresponding to the transformation of
941
* all the input units, even in case of a buffer overflow.
942
* @param src The original source string
943
* @param srcLength The length of the original string. If -1, then src must be zero-terminated.
944
* @param pErrorCode Must be a valid pointer to an error code value,
945
* which must not indicate a failure before the function call.
946
* @return The pointer to destination buffer.
949
U_CAPI UChar* U_EXPORT2
950
u_strFromUTF32(UChar *dest,
951
int32_t destCapacity,
952
int32_t *pDestLength,
955
UErrorCode *pErrorCode);
added
removed
source/common/unicode/ustring.h
