#include "unicode/utypes.h"
#include "unicode/putil.h"
#include "unicode/uiter.h"
Go to the source code of this file.
Defines | |
#define | U_COMPARE_CODE_POINT_ORDER 0x8000 |
Option bit for u_strCaseCompare, u_strcasecmp, unorm_compare, etc: Compare strings in code point order instead of code unit order. | |
#define | U_STRING_DECL(var, cs, length) static const UChar var[(length)+1]=L ## cs |
Unicode String literals in C. | |
#define | U_STRING_INIT(var, cs, length) |
Typedefs | |
typedef void | UBreakIterator |
Simple declaration for u_strToTitle() to avoid including unicode/ubrk.h. | |
Functions | |
int32_t | u_countChar32 (const UChar *s, int32_t length) |
Count Unicode code points in the length UChar code units of the string. | |
UBool | u_strHasMoreChar32Than (const UChar *s, int32_t length, int32_t number) |
Check if the string contains more Unicode code points than a certain number. | |
UChar * | u_strcat (UChar *dst, const UChar *src) |
Concatenate two ustrings. | |
UChar * | u_strncat (UChar *dst, const UChar *src, int32_t n) |
Concatenate two ustrings. | |
UChar * | u_strstr (const UChar *s, const UChar *substring) |
Find the first occurrence of a substring in a string. | |
UChar * | u_strFindFirst (const UChar *s, int32_t length, const UChar *substring, int32_t subLength) |
Find the first occurrence of a substring in a string. | |
UChar * | u_strchr (const UChar *s, UChar c) |
Find the first occurrence of a BMP code point in a string. | |
UChar * | u_strchr32 (const UChar *s, UChar32 c) |
Find the first occurrence of a code point in a string. | |
UChar * | u_strrstr (const UChar *s, const UChar *substring) |
Find the last occurrence of a substring in a string. | |
UChar * | u_strFindLast (const UChar *s, int32_t length, const UChar *substring, int32_t subLength) |
Find the last occurrence of a substring in a string. | |
UChar * | u_strrchr (const UChar *s, UChar c) |
Find the last occurrence of a BMP code point in a string. | |
UChar * | u_strrchr32 (const UChar *s, UChar32 c) |
Find the last occurrence of a code point in a string. | |
UChar * | u_strpbrk (const UChar *string, const UChar *matchSet) |
Locates the first occurrence in the string string of any of the characters in the string matchSet . | |
int32_t | u_strcspn (const UChar *string, const UChar *matchSet) |
Returns the number of consecutive characters in string , beginning with the first, that do not occur somewhere in matchSet . | |
int32_t | u_strspn (const UChar *string, const UChar *matchSet) |
Returns the number of consecutive characters in string , beginning with the first, that occur somewhere in matchSet . | |
UChar * | u_strtok_r (UChar *src, const UChar *delim, UChar **saveState) |
The string tokenizer API allows an application to break a string into tokens. | |
int32_t | u_strcmp (const UChar *s1, const UChar *s2) |
Compare two Unicode strings for bitwise equality (code unit order). | |
int32_t | u_strcmpCodePointOrder (const UChar *s1, const UChar *s2) |
Compare two Unicode strings in code point order. | |
int32_t | u_strCompare (const UChar *s1, int32_t length1, const UChar *s2, int32_t length2, UBool codePointOrder) |
Compare two Unicode strings (binary order). | |
int32_t | u_strCompareIter (UCharIterator *iter1, UCharIterator *iter2, UBool codePointOrder) |
Compare two Unicode strings (binary order) as presented by UCharIterator objects. | |
int32_t | u_strCaseCompare (const UChar *s1, int32_t length1, const UChar *s2, int32_t length2, uint32_t options, UErrorCode *pErrorCode) |
Compare two strings case-insensitively using full case folding. | |
int32_t | u_strncmp (const UChar *ucs1, const UChar *ucs2, int32_t n) |
Compare two ustrings for bitwise equality. | |
int32_t | u_strncmpCodePointOrder (const UChar *s1, const UChar *s2, int32_t n) |
Compare two Unicode strings in code point order. | |
int32_t | u_strcasecmp (const UChar *s1, const UChar *s2, uint32_t options) |
Compare two strings case-insensitively using full case folding. | |
int32_t | u_strncasecmp (const UChar *s1, const UChar *s2, int32_t n, uint32_t options) |
Compare two strings case-insensitively using full case folding. | |
int32_t | u_memcasecmp (const UChar *s1, const UChar *s2, int32_t length, uint32_t options) |
Compare two strings case-insensitively using full case folding. | |
UChar * | u_strcpy (UChar *dst, const UChar *src) |
Copy a ustring. | |
UChar * | u_strncpy (UChar *dst, const UChar *src, int32_t n) |
Copy a ustring. | |
UChar * | u_uastrcpy (UChar *dst, const char *src) |
Copy a byte string encoded in the default codepage to a ustring. | |
UChar * | u_uastrncpy (UChar *dst, const char *src, int32_t n) |
Copy a byte string encoded in the default codepage to a ustring. | |
char * | u_austrcpy (char *dst, const UChar *src) |
Copy ustring to a byte string encoded in the default codepage. | |
char * | u_austrncpy (char *dst, const UChar *src, int32_t n) |
Copy ustring to a byte string encoded in the default codepage. | |
UChar * | u_memcpy (UChar *dest, const UChar *src, int32_t count) |
Synonym for memcpy(), but with UChars only. | |
UChar * | u_memmove (UChar *dest, const UChar *src, int32_t count) |
Synonym for memmove(), but with UChars only. | |
UChar * | u_memset (UChar *dest, UChar c, int32_t count) |
Initialize count characters of dest to c . | |
int32_t | u_memcmp (const UChar *buf1, const UChar *buf2, int32_t count) |
Compare the first count UChars of each buffer. | |
int32_t | u_memcmpCodePointOrder (const UChar *s1, const UChar *s2, int32_t count) |
Compare two Unicode strings in code point order. | |
UChar * | u_memchr (const UChar *s, UChar c, int32_t count) |
Find the first occurrence of a BMP code point in a string. | |
UChar * | u_memchr32 (const UChar *s, UChar32 c, int32_t count) |
Find the first occurrence of a code point in a string. | |
UChar * | u_memrchr (const UChar *s, UChar c, int32_t count) |
Find the last occurrence of a BMP code point in a string. | |
UChar * | u_memrchr32 (const UChar *s, UChar32 c, int32_t count) |
Find the last occurrence of a code point in a string. | |
int32_t | u_unescape (const char *src, UChar *dest, int32_t destCapacity) |
Unescape a string of characters and write the resulting Unicode characters to the destination buffer. | |
U_CDECL_BEGIN typedef | UChar (U_CALLCONV *UNESCAPE_CHAR_AT)(int32_t offset |
Callback function for u_unescapeAt() that returns a character of the source text given an offset and a context pointer. | |
U_CDECL_END UChar32 | u_unescapeAt (UNESCAPE_CHAR_AT charAt, int32_t *offset, int32_t length, void *context) |
Unescape a single sequence. | |
int32_t | u_strToUpper (UChar *dest, int32_t destCapacity, const UChar *src, int32_t srcLength, const char *locale, UErrorCode *pErrorCode) |
Uppercase the characters in a string. | |
int32_t | u_strToLower (UChar *dest, int32_t destCapacity, const UChar *src, int32_t srcLength, const char *locale, UErrorCode *pErrorCode) |
Lowercase the characters in a string. | |
int32_t | u_strToTitle (UChar *dest, int32_t destCapacity, const UChar *src, int32_t srcLength, UBreakIterator *titleIter, const char *locale, UErrorCode *pErrorCode) |
Titlecase a string. | |
int32_t | u_strFoldCase (UChar *dest, int32_t destCapacity, const UChar *src, int32_t srcLength, uint32_t options, UErrorCode *pErrorCode) |
Case-fold the characters in a string. | |
wchar_t * | u_strToWCS (wchar_t *dest, int32_t destCapacity, int32_t *pDestLength, const UChar *src, int32_t srcLength, UErrorCode *pErrorCode) |
Converts a sequence of UChars to wchar_t units. | |
UChar * | u_strFromWCS (UChar *dest, int32_t destCapacity, int32_t *pDestLength, const wchar_t *src, int32_t srcLength, UErrorCode *pErrorCode) |
Converts a sequence of wchar_t units to UChars. | |
char * | u_strToUTF8 (char *dest, int32_t destCapacity, int32_t *pDestLength, const UChar *src, int32_t srcLength, UErrorCode *pErrorCode) |
Converts a sequence of UChars (UTF-16) to UTF-8 bytes. | |
UChar * | u_strFromUTF8 (UChar *dest, int32_t destCapacity, int32_t *pDestLength, const char *src, int32_t srcLength, UErrorCode *pErrorCode) |
Converts a sequence of UTF-8 bytes to UChars (UTF-16). | |
char * | u_strToUTF8WithSub (char *dest, int32_t destCapacity, int32_t *pDestLength, const UChar *src, int32_t srcLength, UChar32 subchar, int32_t *pNumSubstitutions, UErrorCode *pErrorCode) |
Converts a sequence of UChars (UTF-16) to UTF-8 bytes. | |
UChar * | u_strFromUTF8WithSub (UChar *dest, int32_t destCapacity, int32_t *pDestLength, const char *src, int32_t srcLength, UChar32 subchar, int32_t *pNumSubstitutions, UErrorCode *pErrorCode) |
Converts a sequence of UTF-8 bytes to UChars (UTF-16). | |
UChar * | u_strFromUTF8Lenient (UChar *dest, int32_t destCapacity, int32_t *pDestLength, const char *src, int32_t srcLength, UErrorCode *pErrorCode) |
Converts a sequence of UTF-8 bytes to UChars (UTF-16). | |
UChar32 * | u_strToUTF32 (UChar32 *dest, int32_t destCapacity, int32_t *pDestLength, const UChar *src, int32_t srcLength, UErrorCode *pErrorCode) |
Converts a sequence of UChars (UTF-16) to UTF32 units. | |
UChar * | u_strFromUTF32 (UChar *dest, int32_t destCapacity, int32_t *pDestLength, const UChar32 *src, int32_t srcLength, UErrorCode *pErrorCode) |
Converts a sequence of UTF32 units to UChars (UTF-16). | |
Variables | |
U_CDECL_BEGIN typedef void * | context |
These C API functions provide general Unicode string handling.
Some functions are equivalent in name, signature, and behavior to the ANSI C <string.h> functions. (For example, they do not check for bad arguments like NULL string pointers.) In some cases, only the thread-safe variant of such a function is implemented here (see u_strtok_r()).
Other functions provide more Unicode-specific functionality like locale-specific upper/lower-casing and string comparison in code point order.
ICU uses 16-bit Unicode (UTF-16) in the form of arrays of UChar code units. UTF-16 encodes each Unicode code point with either one or two UChar code units. (This is the default form of Unicode, and a forward-compatible extension of the original, fixed-width form that was known as UCS-2. UTF-16 superseded UCS-2 with Unicode 2.0 in 1996.)
Some APIs accept a 32-bit UChar32 value for a single code point.
ICU also handles 16-bit Unicode text with unpaired surrogates. Such text is not well-formed UTF-16. Code-point-related functions treat unpaired surrogates as surrogate code points, i.e., as separate units.
Although UTF-16 is a variable-width encoding form (like some legacy multi-byte encodings), it is much more efficient even for random access because the code unit values for single-unit characters vs. lead units vs. trail units are completely disjoint. This means that it is easy to determine character (code point) boundaries from random offsets in the string.
Unicode (UTF-16) string processing is optimized for the single-unit case. Although it is important to support supplementary characters (which use pairs of lead/trail code units called "surrogates"), their occurrence is rare. Almost all characters in modern use require only a single UChar code unit (i.e., their code point values are <=0xffff).
For more details see the User Guide Strings chapter (http://icu-project.org/userguide/strings.html). For a discussion of the handling of unpaired surrogates see also Jitterbug 2145 and its icu mailing list proposal on 2002-sep-18.
Definition in file ustring.h.
|
Option bit for u_strCaseCompare, u_strcasecmp, unorm_compare, etc: Compare strings in code point order instead of code unit order.
|
|
Unicode String literals in C. We need one macro to declare a variable for the string and to statically preinitialize it if possible, and a second macro to dynamically intialize such a string variable if necessary. The macros are defined for maximum performance. They work only for strings that contain "invariant characters", i.e., only latin letters, digits, and some punctuation. See utypes.h for details.
A pair of macros for a single string must be used with the same parameters. The string parameter must be a C string literal. The length of the string, not including the terminating Usage: U_STRING_DECL(ustringVar1, "Quick-Fox 2", 11); U_STRING_DECL(ustringVar2, "jumps 5%", 8); static UBool didInit=FALSE;
int32_t function() { if(!didInit) { U_STRING_INIT(ustringVar1, "Quick-Fox 2", 11); U_STRING_INIT(ustringVar2, "jumps 5%", 8); didInit=TRUE; } return u_strcmp(ustringVar1, ustringVar2); }
|
|
|
|
Simple declaration for u_strToTitle() to avoid including unicode/ubrk.h.
|
|
Copy ustring to a byte string encoded in the default codepage. Adds a null terminator. Performs a UChar to host byte conversion
|
|
Copy ustring to a byte string encoded in the default codepage.
Copies at most
|
|
Count Unicode code points in the length UChar code units of the string. A code point may occupy either one or two UChar code units. Counting code points involves reading all code units. This functions is basically the inverse of the U16_FWD_N() macro (see utf.h).
|
|
Compare two strings case-insensitively using full case folding. This is equivalent to u_strcmp(u_strFoldCase(s1, n, options), u_strFoldCase(s2, n, options)).
|
|
Find the first occurrence of a BMP code point in a string. A surrogate code point is found only if its match in the text is not part of a surrogate pair. A NUL character is found at the string terminator.
|
|
Find the first occurrence of a code point in a string. A surrogate code point is found only if its match in the text is not part of a surrogate pair. A NUL character is found at the string terminator.
|
|
Compare the first
|
|
Compare two Unicode strings in code point order. This is different in UTF-16 from u_memcmp() if supplementary characters are present. For details, see u_strCompare().
|
|
Synonym for memcpy(), but with UChars only.
|
|
Synonym for memmove(), but with UChars only.
|
|
Find the last occurrence of a BMP code point in a string. A surrogate code point is found only if its match in the text is not part of a surrogate pair. A NUL character is found at the string terminator.
|
|
Find the last occurrence of a code point in a string. A surrogate code point is found only if its match in the text is not part of a surrogate pair. A NUL character is found at the string terminator.
|
|
Initialize
|
|
Compare two strings case-insensitively using full case folding. This is equivalent to u_strcmp(u_strFoldCase(s1, options), u_strFoldCase(s2, options)).
|
|
Compare two strings case-insensitively using full case folding. This is equivalent to u_strCompare(u_strFoldCase(s1, options), u_strFoldCase(s2, options), (options&U_COMPARE_CODE_POINT_ORDER)!=0). The comparison can be done in UTF-16 code unit order or in code point order. They differ only when comparing supplementary code points (U+10000..U+10ffff) to BMP code points near the end of the BMP (i.e., U+e000..U+ffff). In code unit order, high BMP code points sort after supplementary code points because they are stored as pairs of surrogates which are at U+d800..U+dfff. This functions works with strings of different explicitly specified lengths unlike the ANSI C-like u_strcmp() and u_memcmp() etc. NUL-terminated strings are possible with length arguments of -1.
|
|
Concatenate two ustrings.
Appends a copy of
|
|
Find the first occurrence of a BMP code point in a string. A surrogate code point is found only if its match in the text is not part of a surrogate pair. A NUL character is found at the string terminator.
|
|
Find the first occurrence of a code point in a string. A surrogate code point is found only if its match in the text is not part of a surrogate pair. A NUL character is found at the string terminator.
|
|
Compare two Unicode strings for bitwise equality (code unit order).
|
|
Compare two Unicode strings in code point order. See u_strCompare for details.
|
|
Compare two Unicode strings (binary order). The comparison can be done in code unit order or in code point order. They differ only in UTF-16 when comparing supplementary code points (U+10000..U+10ffff) to BMP code points near the end of the BMP (i.e., U+e000..U+ffff). In code unit order, high BMP code points sort after supplementary code points because they are stored as pairs of surrogates which are at U+d800..U+dfff. This functions works with strings of different explicitly specified lengths unlike the ANSI C-like u_strcmp() and u_memcmp() etc. NUL-terminated strings are possible with length arguments of -1.
|
|
Compare two Unicode strings (binary order) as presented by UCharIterator objects. Works otherwise just like u_strCompare(). Both iterators are reset to their start positions. When the function returns, it is undefined where the iterators have stopped.
|
|
Copy a ustring. Adds a null terminator.
|
|
Returns the number of consecutive characters in Works just like C's strcspn but with Unicode.
|
|
Find the first occurrence of a substring in a string. The substring is found at code point boundaries. That means that if the substring begins with a trail surrogate or ends with a lead surrogate, then it is found only if these surrogates stand alone in the text. Otherwise, the substring edge units would be matched against halves of surrogate pairs.
|
|
Find the last occurrence of a substring in a string. The substring is found at code point boundaries. That means that if the substring begins with a trail surrogate or ends with a lead surrogate, then it is found only if these surrogates stand alone in the text. Otherwise, the substring edge units would be matched against halves of surrogate pairs.
|
|
Case-fold the characters in a string. Case-folding is locale-independent and not context-sensitive, but there is an option for whether to include or exclude mappings for dotted I and dotless i that are marked with 'I' in CaseFolding.txt. The result may be longer or shorter than the original. The source string and the destination buffer are allowed to overlap.
|
|
Converts a sequence of UTF32 units to UChars (UTF-16).
|
|
Converts a sequence of UTF-8 bytes to UChars (UTF-16).
|
|
Converts a sequence of UTF-8 bytes to UChars (UTF-16). Same as u_strFromUTF8() except that this function is designed to be very fast, which it achieves by being lenient about malformed UTF-8 sequences. This function is intended for use in environments where UTF-8 text is expected to be well-formed. Its semantics are:
For further performance improvement, if srcLength is given (>=0), then it must be destCapacity>=srcLength.
|
|
Converts a sequence of UTF-8 bytes to UChars (UTF-16). Same as u_strFromUTF8() except for the additional subchar which is output for illegal input sequences, instead of stopping with the U_INVALID_CHAR_FOUND error code. With subchar==U_SENTINEL, this function behaves exactly like u_strFromUTF8().
|
|
Converts a sequence of wchar_t units to UChars.
|
|
Check if the string contains more Unicode code points than a certain number. This is more efficient than counting all code points in the entire string and comparing that number with a threshold. This function may not need to scan the string at all if the length is known (not -1 for NUL-termination) and falls within a certain range, and never needs to count more than 'number+1' code points. Logically equivalent to (u_countChar32(s, length)>number). A Unicode code point may occupy either one or two UChar code units.
|
|
Compare two strings case-insensitively using full case folding. This is equivalent to u_strcmp(u_strFoldCase(s1, at most n, options), u_strFoldCase(s2, at most n, options)).
|
|
Concatenate two ustrings.
Appends at most
|
|
Compare two ustrings for bitwise equality.
Compares at most
|
|
Compare two Unicode strings in code point order. This is different in UTF-16 from u_strncmp() if supplementary characters are present. For details, see u_strCompare().
|
|
Copy a ustring.
Copies at most
|
|
Locates the first occurrence in the string Works just like C's strpbrk but with Unicode.
|
|
Find the last occurrence of a BMP code point in a string. A surrogate code point is found only if its match in the text is not part of a surrogate pair. A NUL character is found at the string terminator.
|
|
Find the last occurrence of a code point in a string. A surrogate code point is found only if its match in the text is not part of a surrogate pair. A NUL character is found at the string terminator.
|
|
Find the last occurrence of a substring in a string. The substring is found at code point boundaries. That means that if the substring begins with a trail surrogate or ends with a lead surrogate, then it is found only if these surrogates stand alone in the text. Otherwise, the substring edge units would be matched against halves of surrogate pairs.
|
|
Returns the number of consecutive characters in Works just like C's strspn but with Unicode.
|
|
Find the first occurrence of a substring in a string. The substring is found at code point boundaries. That means that if the substring begins with a trail surrogate or ends with a lead surrogate, then it is found only if these surrogates stand alone in the text. Otherwise, the substring edge units would be matched against halves of surrogate pairs.
|
|
The string tokenizer API allows an application to break a string into tokens. Unlike strtok(), the saveState (the current pointer within the original string) is maintained in saveState. In the first call, the argument src is a pointer to the string. In subsequent calls to return successive tokens of that string, src must be specified as NULL. The value saveState is set by this function to maintain the function's position within the string, and on each subsequent call you must give this argument the same variable. This function does handle surrogate pairs. This function is similar to the strtok_r() the POSIX Threads Extension (1003.1c-1995) version.
|
|
Lowercase the characters in a string. Casing is locale-dependent and context-sensitive. The result may be longer or shorter than the original. The source string and the destination buffer are allowed to overlap.
|
|
Titlecase a string. Casing is locale-dependent and context-sensitive. Titlecasing uses a break iterator to find the first characters of words that are to be titlecased. It titlecases those characters and lowercases all others. The titlecase break iterator can be provided to customize for arbitrary styles, using rules and dictionaries beyond the standard iterators. It may be more efficient to always provide an iterator to avoid opening and closing one for each string. The standard titlecase iterator for the root locale implements the algorithm of Unicode TR 21. This function uses only the setText(), first() and next() methods of the provided break iterator. The result may be longer or shorter than the original. The source string and the destination buffer are allowed to overlap.
|
|
Uppercase the characters in a string. Casing is locale-dependent and context-sensitive. The result may be longer or shorter than the original. The source string and the destination buffer are allowed to overlap.
|
|
Converts a sequence of UChars (UTF-16) to UTF32 units.
|
|
Converts a sequence of UChars (UTF-16) to UTF-8 bytes.
|
|
Converts a sequence of UChars (UTF-16) to UTF-8 bytes. Same as u_strToUTF8() except for the additional subchar which is output for illegal input sequences, instead of stopping with the U_INVALID_CHAR_FOUND error code. With subchar==U_SENTINEL, this function behaves exactly like u_strToUTF8().
|
|
Converts a sequence of UChars to wchar_t units.
|
|
Copy a byte string encoded in the default codepage to a ustring. Adds a null terminator. Performs a host byte to UChar conversion
|
|
Copy a byte string encoded in the default codepage to a ustring.
Copies at most
|
|
Unescape a string of characters and write the resulting Unicode characters to the destination buffer. The following escape sequences are recognized: \uhhhh 4 hex digits; h in [0-9A-Fa-f] \Uhhhhhhhh 8 hex digits \xhh 1-2 hex digits \x{h...} 1-8 hex digits \ooo 1-3 octal digits; o in [0-7] \cX control-X; X is masked with 0x1F as well as the standard ANSI C escapes: \a => U+0007, \b => U+0008, \t => U+0009, \n => U+000A, \v => U+000B, \f => U+000C, \r => U+000D, \e => U+001B, \" => U+0022, \' => U+0027, \? => U+003F, \\ => U+005C Anything else following a backslash is generically escaped. For example, "[a\\-z]" returns "[a-z]". If an escape sequence is ill-formed, this method returns an empty string. An example of an ill-formed sequence is "\\u" followed by fewer than 4 hex digits. The above characters are recognized in the compiler's codepage, that is, they are coded as 'u', '\', etc. Characters that are not parts of escape sequences are converted using u_charsToUChars(). This function is similar to UnicodeString::unescape() but not identical to it. The latter takes a source UnicodeString, so it does escape recognition but no conversion.
|
|
Unescape a single sequence. The character at offset-1 is assumed (without checking) to be a backslash. This method takes a callback pointer to a function that returns the UChar at a given offset. By varying this callback, ICU functions are able to unescape char* strings, UnicodeString objects, and UFILE pointers. If offset is out of range, or if the escape sequence is ill-formed, (UChar32)0xFFFFFFFF is returned. See documentation of u_unescape() for a list of recognized sequences.
|
|
Callback function for u_unescapeAt() that returns a character of the source text given an offset and a context pointer. The context pointer will be whatever is passed into u_unescapeAt().
|