sl@0: /* sl@0: ********************************************************************** sl@0: * Copyright (C) 1998-2005, International Business Machines sl@0: * Corporation and others. All Rights Reserved. sl@0: ********************************************************************** sl@0: * sl@0: * File ustring.h sl@0: * sl@0: * Modification History: sl@0: * sl@0: * Date Name Description sl@0: * 12/07/98 bertrand Creation. sl@0: ****************************************************************************** sl@0: */ sl@0: sl@0: #ifndef USTRING_H sl@0: #define USTRING_H sl@0: sl@0: #include "unicode/utypes.h" sl@0: #include "unicode/putil.h" sl@0: #include "unicode/uiter.h" sl@0: sl@0: /** Simple declaration for u_strToTitle() to avoid including unicode/ubrk.h. @stable ICU 2.1*/ sl@0: #ifndef UBRK_TYPEDEF_UBREAK_ITERATOR sl@0: # define UBRK_TYPEDEF_UBREAK_ITERATOR sl@0: typedef void UBreakIterator; sl@0: #endif sl@0: sl@0: /** sl@0: * \file sl@0: * \brief C API: Unicode string handling functions sl@0: * sl@0: * These C API functions provide general Unicode string handling. sl@0: * sl@0: * Some functions are equivalent in name, signature, and behavior to the ANSI C sl@0: * functions. (For example, they do not check for bad arguments like NULL string pointers.) sl@0: * In some cases, only the thread-safe variant of such a function is implemented here sl@0: * (see u_strtok_r()). sl@0: * sl@0: * Other functions provide more Unicode-specific functionality like locale-specific sl@0: * upper/lower-casing and string comparison in code point order. sl@0: * sl@0: * ICU uses 16-bit Unicode (UTF-16) in the form of arrays of UChar code units. sl@0: * UTF-16 encodes each Unicode code point with either one or two UChar code units. sl@0: * (This is the default form of Unicode, and a forward-compatible extension of the original, sl@0: * fixed-width form that was known as UCS-2. UTF-16 superseded UCS-2 with Unicode 2.0 sl@0: * in 1996.) sl@0: * sl@0: * Some APIs accept a 32-bit UChar32 value for a single code point. sl@0: * sl@0: * ICU also handles 16-bit Unicode text with unpaired surrogates. sl@0: * Such text is not well-formed UTF-16. sl@0: * Code-point-related functions treat unpaired surrogates as surrogate code points, sl@0: * i.e., as separate units. sl@0: * sl@0: * Although UTF-16 is a variable-width encoding form (like some legacy multi-byte encodings), sl@0: * it is much more efficient even for random access because the code unit values sl@0: * for single-unit characters vs. lead units vs. trail units are completely disjoint. sl@0: * This means that it is easy to determine character (code point) boundaries from sl@0: * random offsets in the string. sl@0: * sl@0: * Unicode (UTF-16) string processing is optimized for the single-unit case. sl@0: * Although it is important to support supplementary characters sl@0: * (which use pairs of lead/trail code units called "surrogates"), sl@0: * their occurrence is rare. Almost all characters in modern use require only sl@0: * a single UChar code unit (i.e., their code point values are <=0xffff). sl@0: * sl@0: * For more details see the User Guide Strings chapter (http://icu.sourceforge.net/userguide/strings.html). sl@0: * For a discussion of the handling of unpaired surrogates see also sl@0: * Jitterbug 2145 and its icu mailing list proposal on 2002-sep-18. sl@0: */ sl@0: sl@0: /** sl@0: * Determine the length of an array of UChar. sl@0: * sl@0: * @param s The array of UChars, NULL (U+0000) terminated. sl@0: * @return The number of UChars in chars, minus the terminator. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_strlen(const UChar *s); sl@0: sl@0: /** sl@0: * Count Unicode code points in the length UChar code units of the string. sl@0: * A code point may occupy either one or two UChar code units. sl@0: * Counting code points involves reading all code units. sl@0: * sl@0: * This functions is basically the inverse of the U16_FWD_N() macro (see utf.h). sl@0: * sl@0: * @param s The input string. sl@0: * @param length The number of UChar code units to be checked, or -1 to count all sl@0: * code points before the first NUL (U+0000). sl@0: * @return The number of code points in the specified code units. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_countChar32(const UChar *s, int32_t length); sl@0: sl@0: /** sl@0: * Check if the string contains more Unicode code points than a certain number. sl@0: * This is more efficient than counting all code points in the entire string sl@0: * and comparing that number with a threshold. sl@0: * This function may not need to scan the string at all if the length is known sl@0: * (not -1 for NUL-termination) and falls within a certain range, and sl@0: * never needs to count more than 'number+1' code points. sl@0: * Logically equivalent to (u_countChar32(s, length)>number). sl@0: * A Unicode code point may occupy either one or two UChar code units. sl@0: * sl@0: * @param s The input string. sl@0: * @param length The length of the string, or -1 if it is NUL-terminated. sl@0: * @param number The number of code points in the string is compared against sl@0: * the 'number' parameter. sl@0: * @return Boolean value for whether the string contains more Unicode code points sl@0: * than 'number'. Same as (u_countChar32(s, length)>number). sl@0: * @stable ICU 2.4 sl@0: */ sl@0: U_STABLE UBool U_EXPORT2 sl@0: u_strHasMoreChar32Than(const UChar *s, int32_t length, int32_t number); sl@0: sl@0: /** sl@0: * Concatenate two ustrings. Appends a copy of src, sl@0: * including the null terminator, to dst. The initial copied sl@0: * character from src overwrites the null terminator in dst. sl@0: * sl@0: * @param dst The destination string. sl@0: * @param src The source string. sl@0: * @return A pointer to dst. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UChar* U_EXPORT2 sl@0: u_strcat(UChar *dst, sl@0: const UChar *src); sl@0: sl@0: /** sl@0: * Concatenate two ustrings. sl@0: * Appends at most n characters from src to dst. sl@0: * Adds a terminating NUL. sl@0: * If src is too long, then only n-1 characters will be copied sl@0: * before the terminating NUL. sl@0: * If n<=0 then dst is not modified. sl@0: * sl@0: * @param dst The destination string. sl@0: * @param src The source string. sl@0: * @param n The maximum number of characters to compare. sl@0: * @return A pointer to dst. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UChar* U_EXPORT2 sl@0: u_strncat(UChar *dst, sl@0: const UChar *src, sl@0: int32_t n); sl@0: sl@0: /** sl@0: * Find the first occurrence of a substring in a string. sl@0: * The substring is found at code point boundaries. sl@0: * That means that if the substring begins with sl@0: * a trail surrogate or ends with a lead surrogate, sl@0: * then it is found only if these surrogates stand alone in the text. sl@0: * Otherwise, the substring edge units would be matched against sl@0: * halves of surrogate pairs. sl@0: * sl@0: * @param s The string to search (NUL-terminated). sl@0: * @param substring The substring to find (NUL-terminated). sl@0: * @return A pointer to the first occurrence of substring in s, sl@0: * or s itself if the substring is empty, sl@0: * or NULL if substring is not in s. sl@0: * @stable ICU 2.0 sl@0: * sl@0: * @see u_strrstr sl@0: * @see u_strFindFirst sl@0: * @see u_strFindLast sl@0: */ sl@0: U_STABLE UChar * U_EXPORT2 sl@0: u_strstr(const UChar *s, const UChar *substring); sl@0: sl@0: /** sl@0: * Find the first occurrence of a substring in a string. sl@0: * The substring is found at code point boundaries. sl@0: * That means that if the substring begins with sl@0: * a trail surrogate or ends with a lead surrogate, sl@0: * then it is found only if these surrogates stand alone in the text. sl@0: * Otherwise, the substring edge units would be matched against sl@0: * halves of surrogate pairs. sl@0: * sl@0: * @param s The string to search. sl@0: * @param length The length of s (number of UChars), or -1 if it is NUL-terminated. sl@0: * @param substring The substring to find (NUL-terminated). sl@0: * @param subLength The length of substring (number of UChars), or -1 if it is NUL-terminated. sl@0: * @return A pointer to the first occurrence of substring in s, sl@0: * or s itself if the substring is empty, sl@0: * or NULL if substring is not in s. sl@0: * @stable ICU 2.4 sl@0: * sl@0: * @see u_strstr sl@0: * @see u_strFindLast sl@0: */ sl@0: U_STABLE UChar * U_EXPORT2 sl@0: u_strFindFirst(const UChar *s, int32_t length, const UChar *substring, int32_t subLength); sl@0: sl@0: /** sl@0: * Find the first occurrence of a BMP code point in a string. sl@0: * A surrogate code point is found only if its match in the text is not sl@0: * part of a surrogate pair. sl@0: * A NUL character is found at the string terminator. sl@0: * sl@0: * @param s The string to search (NUL-terminated). sl@0: * @param c The BMP code point to find. sl@0: * @return A pointer to the first occurrence of c in s sl@0: * or NULL if c is not in s. sl@0: * @stable ICU 2.0 sl@0: * sl@0: * @see u_strchr32 sl@0: * @see u_memchr sl@0: * @see u_strstr sl@0: * @see u_strFindFirst sl@0: */ sl@0: U_STABLE UChar * U_EXPORT2 sl@0: u_strchr(const UChar *s, UChar c); sl@0: sl@0: /** sl@0: * Find the first occurrence of a code point in a string. sl@0: * A surrogate code point is found only if its match in the text is not sl@0: * part of a surrogate pair. sl@0: * A NUL character is found at the string terminator. sl@0: * sl@0: * @param s The string to search (NUL-terminated). sl@0: * @param c The code point to find. sl@0: * @return A pointer to the first occurrence of c in s sl@0: * or NULL if c is not in s. sl@0: * @stable ICU 2.0 sl@0: * sl@0: * @see u_strchr sl@0: * @see u_memchr32 sl@0: * @see u_strstr sl@0: * @see u_strFindFirst sl@0: */ sl@0: U_STABLE UChar * U_EXPORT2 sl@0: u_strchr32(const UChar *s, UChar32 c); sl@0: sl@0: /** sl@0: * Find the last occurrence of a substring in a string. sl@0: * The substring is found at code point boundaries. sl@0: * That means that if the substring begins with sl@0: * a trail surrogate or ends with a lead surrogate, sl@0: * then it is found only if these surrogates stand alone in the text. sl@0: * Otherwise, the substring edge units would be matched against sl@0: * halves of surrogate pairs. sl@0: * sl@0: * @param s The string to search (NUL-terminated). sl@0: * @param substring The substring to find (NUL-terminated). sl@0: * @return A pointer to the last occurrence of substring in s, sl@0: * or s itself if the substring is empty, sl@0: * or NULL if substring is not in s. sl@0: * @stable ICU 2.4 sl@0: * sl@0: * @see u_strstr sl@0: * @see u_strFindFirst sl@0: * @see u_strFindLast sl@0: */ sl@0: U_STABLE UChar * U_EXPORT2 sl@0: u_strrstr(const UChar *s, const UChar *substring); sl@0: sl@0: /** sl@0: * Find the last occurrence of a substring in a string. sl@0: * The substring is found at code point boundaries. sl@0: * That means that if the substring begins with sl@0: * a trail surrogate or ends with a lead surrogate, sl@0: * then it is found only if these surrogates stand alone in the text. sl@0: * Otherwise, the substring edge units would be matched against sl@0: * halves of surrogate pairs. sl@0: * sl@0: * @param s The string to search. sl@0: * @param length The length of s (number of UChars), or -1 if it is NUL-terminated. sl@0: * @param substring The substring to find (NUL-terminated). sl@0: * @param subLength The length of substring (number of UChars), or -1 if it is NUL-terminated. sl@0: * @return A pointer to the last occurrence of substring in s, sl@0: * or s itself if the substring is empty, sl@0: * or NULL if substring is not in s. sl@0: * @stable ICU 2.4 sl@0: * sl@0: * @see u_strstr sl@0: * @see u_strFindLast sl@0: */ sl@0: U_STABLE UChar * U_EXPORT2 sl@0: u_strFindLast(const UChar *s, int32_t length, const UChar *substring, int32_t subLength); sl@0: sl@0: /** sl@0: * Find the last occurrence of a BMP code point in a string. sl@0: * A surrogate code point is found only if its match in the text is not sl@0: * part of a surrogate pair. sl@0: * A NUL character is found at the string terminator. sl@0: * sl@0: * @param s The string to search (NUL-terminated). sl@0: * @param c The BMP code point to find. sl@0: * @return A pointer to the last occurrence of c in s sl@0: * or NULL if c is not in s. sl@0: * @stable ICU 2.4 sl@0: * sl@0: * @see u_strrchr32 sl@0: * @see u_memrchr sl@0: * @see u_strrstr sl@0: * @see u_strFindLast sl@0: */ sl@0: U_STABLE UChar * U_EXPORT2 sl@0: u_strrchr(const UChar *s, UChar c); sl@0: sl@0: /** sl@0: * Find the last occurrence of a code point in a string. sl@0: * A surrogate code point is found only if its match in the text is not sl@0: * part of a surrogate pair. sl@0: * A NUL character is found at the string terminator. sl@0: * sl@0: * @param s The string to search (NUL-terminated). sl@0: * @param c The code point to find. sl@0: * @return A pointer to the last occurrence of c in s sl@0: * or NULL if c is not in s. sl@0: * @stable ICU 2.4 sl@0: * sl@0: * @see u_strrchr sl@0: * @see u_memchr32 sl@0: * @see u_strrstr sl@0: * @see u_strFindLast sl@0: */ sl@0: U_STABLE UChar * U_EXPORT2 sl@0: u_strrchr32(const UChar *s, UChar32 c); sl@0: sl@0: /** sl@0: * Locates the first occurrence in the string string of any of the characters sl@0: * in the string matchSet. sl@0: * Works just like C's strpbrk but with Unicode. sl@0: * sl@0: * @param string The string in which to search, NUL-terminated. sl@0: * @param matchSet A NUL-terminated string defining a set of code points sl@0: * for which to search in the text string. sl@0: * @return A pointer to the character in string that matches one of the sl@0: * characters in matchSet, or NULL if no such character is found. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UChar * U_EXPORT2 sl@0: u_strpbrk(const UChar *string, const UChar *matchSet); sl@0: sl@0: /** sl@0: * Returns the number of consecutive characters in string, sl@0: * beginning with the first, that do not occur somewhere in matchSet. sl@0: * Works just like C's strcspn but with Unicode. sl@0: * sl@0: * @param string The string in which to search, NUL-terminated. sl@0: * @param matchSet A NUL-terminated string defining a set of code points sl@0: * for which to search in the text string. sl@0: * @return The number of initial characters in string that do not sl@0: * occur in matchSet. sl@0: * @see u_strspn sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_strcspn(const UChar *string, const UChar *matchSet); sl@0: sl@0: /** sl@0: * Returns the number of consecutive characters in string, sl@0: * beginning with the first, that occur somewhere in matchSet. sl@0: * Works just like C's strspn but with Unicode. sl@0: * sl@0: * @param string The string in which to search, NUL-terminated. sl@0: * @param matchSet A NUL-terminated string defining a set of code points sl@0: * for which to search in the text string. sl@0: * @return The number of initial characters in string that do sl@0: * occur in matchSet. sl@0: * @see u_strcspn sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_strspn(const UChar *string, const UChar *matchSet); sl@0: sl@0: /** sl@0: * The string tokenizer API allows an application to break a string into sl@0: * tokens. Unlike strtok(), the saveState (the current pointer within the sl@0: * original string) is maintained in saveState. In the first call, the sl@0: * argument src is a pointer to the string. In subsequent calls to sl@0: * return successive tokens of that string, src must be specified as sl@0: * NULL. The value saveState is set by this function to maintain the sl@0: * function's position within the string, and on each subsequent call sl@0: * you must give this argument the same variable. This function does sl@0: * handle surrogate pairs. This function is similar to the strtok_r() sl@0: * the POSIX Threads Extension (1003.1c-1995) version. sl@0: * sl@0: * @param src String containing token(s). This string will be modified. sl@0: * After the first call to u_strtok_r(), this argument must sl@0: * be NULL to get to the next token. sl@0: * @param delim Set of delimiter characters (Unicode code points). sl@0: * @param saveState The current pointer within the original string, sl@0: * which is set by this function. The saveState sl@0: * parameter should the address of a local variable of type sl@0: * UChar *. (i.e. defined "Uhar *myLocalSaveState" and use sl@0: * &myLocalSaveState for this parameter). sl@0: * @return A pointer to the next token found in src, or NULL sl@0: * when there are no more tokens. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UChar * U_EXPORT2 sl@0: u_strtok_r(UChar *src, sl@0: const UChar *delim, sl@0: UChar **saveState); sl@0: sl@0: /** sl@0: * Compare two Unicode strings for bitwise equality (code unit order). sl@0: * sl@0: * @param s1 A string to compare. sl@0: * @param s2 A string to compare. sl@0: * @return 0 if s1 and s2 are bitwise equal; a negative sl@0: * value if s1 is bitwise less than s2,; a positive sl@0: * value if s1 is bitwise greater than s2. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_strcmp(const UChar *s1, sl@0: const UChar *s2); sl@0: sl@0: /** sl@0: * Compare two Unicode strings in code point order. sl@0: * See u_strCompare for details. sl@0: * sl@0: * @param s1 A string to compare. sl@0: * @param s2 A string to compare. sl@0: * @return a negative/zero/positive integer corresponding to whether sl@0: * the first string is less than/equal to/greater than the second one sl@0: * in code point order sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_strcmpCodePointOrder(const UChar *s1, const UChar *s2); sl@0: sl@0: /** sl@0: * Compare two Unicode strings (binary order). sl@0: * sl@0: * The comparison can be done in code unit order or in code point order. sl@0: * They differ only in UTF-16 when sl@0: * comparing supplementary code points (U+10000..U+10ffff) sl@0: * to BMP code points near the end of the BMP (i.e., U+e000..U+ffff). sl@0: * In code unit order, high BMP code points sort after supplementary code points sl@0: * because they are stored as pairs of surrogates which are at U+d800..U+dfff. sl@0: * sl@0: * This functions works with strings of different explicitly specified lengths sl@0: * unlike the ANSI C-like u_strcmp() and u_memcmp() etc. sl@0: * NUL-terminated strings are possible with length arguments of -1. sl@0: * sl@0: * @param s1 First source string. sl@0: * @param length1 Length of first source string, or -1 if NUL-terminated. sl@0: * sl@0: * @param s2 Second source string. sl@0: * @param length2 Length of second source string, or -1 if NUL-terminated. sl@0: * sl@0: * @param codePointOrder Choose between code unit order (FALSE) sl@0: * and code point order (TRUE). sl@0: * sl@0: * @return <0 or 0 or >0 as usual for string comparisons sl@0: * sl@0: * @stable ICU 2.2 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_strCompare(const UChar *s1, int32_t length1, sl@0: const UChar *s2, int32_t length2, sl@0: UBool codePointOrder); sl@0: sl@0: /** sl@0: * Compare two Unicode strings (binary order) sl@0: * as presented by UCharIterator objects. sl@0: * Works otherwise just like u_strCompare(). sl@0: * sl@0: * Both iterators are reset to their start positions. sl@0: * When the function returns, it is undefined where the iterators sl@0: * have stopped. sl@0: * sl@0: * @param iter1 First source string iterator. sl@0: * @param iter2 Second source string iterator. sl@0: * @param codePointOrder Choose between code unit order (FALSE) sl@0: * and code point order (TRUE). sl@0: * sl@0: * @return <0 or 0 or >0 as usual for string comparisons sl@0: * sl@0: * @see u_strCompare sl@0: * sl@0: * @stable ICU 2.6 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_strCompareIter(UCharIterator *iter1, UCharIterator *iter2, UBool codePointOrder); sl@0: sl@0: #ifndef U_COMPARE_CODE_POINT_ORDER sl@0: /* see also unistr.h and unorm.h */ sl@0: /** sl@0: * Option bit for u_strCaseCompare, u_strcasecmp, unorm_compare, etc: sl@0: * Compare strings in code point order instead of code unit order. sl@0: * @stable ICU 2.2 sl@0: */ sl@0: #define U_COMPARE_CODE_POINT_ORDER 0x8000 sl@0: #endif sl@0: sl@0: /** sl@0: * Compare two strings case-insensitively using full case folding. sl@0: * This is equivalent to sl@0: * u_strCompare(u_strFoldCase(s1, options), sl@0: * u_strFoldCase(s2, options), sl@0: * (options&U_COMPARE_CODE_POINT_ORDER)!=0). sl@0: * sl@0: * The comparison can be done in UTF-16 code unit order or in code point order. sl@0: * They differ only when comparing supplementary code points (U+10000..U+10ffff) sl@0: * to BMP code points near the end of the BMP (i.e., U+e000..U+ffff). sl@0: * In code unit order, high BMP code points sort after supplementary code points sl@0: * because they are stored as pairs of surrogates which are at U+d800..U+dfff. sl@0: * sl@0: * This functions works with strings of different explicitly specified lengths sl@0: * unlike the ANSI C-like u_strcmp() and u_memcmp() etc. sl@0: * NUL-terminated strings are possible with length arguments of -1. sl@0: * sl@0: * @param s1 First source string. sl@0: * @param length1 Length of first source string, or -1 if NUL-terminated. sl@0: * sl@0: * @param s2 Second source string. sl@0: * @param length2 Length of second source string, or -1 if NUL-terminated. sl@0: * sl@0: * @param options A bit set of options: sl@0: * - U_FOLD_CASE_DEFAULT or 0 is used for default options: sl@0: * Comparison in code unit order with default case folding. sl@0: * sl@0: * - U_COMPARE_CODE_POINT_ORDER sl@0: * Set to choose code point order instead of code unit order sl@0: * (see u_strCompare for details). sl@0: * sl@0: * - U_FOLD_CASE_EXCLUDE_SPECIAL_I sl@0: * sl@0: * @param pErrorCode Must be a valid pointer to an error code value, sl@0: * which must not indicate a failure before the function call. sl@0: * sl@0: * @return <0 or 0 or >0 as usual for string comparisons sl@0: * sl@0: * @stable ICU 2.2 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_strCaseCompare(const UChar *s1, int32_t length1, sl@0: const UChar *s2, int32_t length2, sl@0: uint32_t options, sl@0: UErrorCode *pErrorCode); sl@0: sl@0: /** sl@0: * Compare two ustrings for bitwise equality. sl@0: * Compares at most n characters. sl@0: * sl@0: * @param ucs1 A string to compare. sl@0: * @param ucs2 A string to compare. sl@0: * @param n The maximum number of characters to compare. sl@0: * @return 0 if s1 and s2 are bitwise equal; a negative sl@0: * value if s1 is bitwise less than s2; a positive sl@0: * value if s1 is bitwise greater than s2. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_strncmp(const UChar *ucs1, sl@0: const UChar *ucs2, sl@0: int32_t n); sl@0: sl@0: /** sl@0: * Compare two Unicode strings in code point order. sl@0: * This is different in UTF-16 from u_strncmp() if supplementary characters are present. sl@0: * For details, see u_strCompare(). sl@0: * sl@0: * @param s1 A string to compare. sl@0: * @param s2 A string to compare. sl@0: * @param n The maximum number of characters to compare. sl@0: * @return a negative/zero/positive integer corresponding to whether sl@0: * the first string is less than/equal to/greater than the second one sl@0: * in code point order sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_strncmpCodePointOrder(const UChar *s1, const UChar *s2, int32_t n); sl@0: sl@0: /** sl@0: * Compare two strings case-insensitively using full case folding. sl@0: * This is equivalent to u_strcmp(u_strFoldCase(s1, options), u_strFoldCase(s2, options)). sl@0: * sl@0: * @param s1 A string to compare. sl@0: * @param s2 A string to compare. sl@0: * @param options A bit set of options: sl@0: * - U_FOLD_CASE_DEFAULT or 0 is used for default options: sl@0: * Comparison in code unit order with default case folding. sl@0: * sl@0: * - U_COMPARE_CODE_POINT_ORDER sl@0: * Set to choose code point order instead of code unit order sl@0: * (see u_strCompare for details). sl@0: * sl@0: * - U_FOLD_CASE_EXCLUDE_SPECIAL_I sl@0: * sl@0: * @return A negative, zero, or positive integer indicating the comparison result. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_strcasecmp(const UChar *s1, const UChar *s2, uint32_t options); sl@0: sl@0: /** sl@0: * Compare two strings case-insensitively using full case folding. sl@0: * This is equivalent to u_strcmp(u_strFoldCase(s1, at most n, options), sl@0: * u_strFoldCase(s2, at most n, options)). sl@0: * sl@0: * @param s1 A string to compare. sl@0: * @param s2 A string to compare. sl@0: * @param n The maximum number of characters each string to case-fold and then compare. sl@0: * @param options A bit set of options: sl@0: * - U_FOLD_CASE_DEFAULT or 0 is used for default options: sl@0: * Comparison in code unit order with default case folding. sl@0: * sl@0: * - U_COMPARE_CODE_POINT_ORDER sl@0: * Set to choose code point order instead of code unit order sl@0: * (see u_strCompare for details). sl@0: * sl@0: * - U_FOLD_CASE_EXCLUDE_SPECIAL_I sl@0: * sl@0: * @return A negative, zero, or positive integer indicating the comparison result. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_strncasecmp(const UChar *s1, const UChar *s2, int32_t n, uint32_t options); sl@0: sl@0: /** sl@0: * Compare two strings case-insensitively using full case folding. sl@0: * This is equivalent to u_strcmp(u_strFoldCase(s1, n, options), sl@0: * u_strFoldCase(s2, n, options)). sl@0: * sl@0: * @param s1 A string to compare. sl@0: * @param s2 A string to compare. sl@0: * @param length The number of characters in each string to case-fold and then compare. sl@0: * @param options A bit set of options: sl@0: * - U_FOLD_CASE_DEFAULT or 0 is used for default options: sl@0: * Comparison in code unit order with default case folding. sl@0: * sl@0: * - U_COMPARE_CODE_POINT_ORDER sl@0: * Set to choose code point order instead of code unit order sl@0: * (see u_strCompare for details). sl@0: * sl@0: * - U_FOLD_CASE_EXCLUDE_SPECIAL_I sl@0: * sl@0: * @return A negative, zero, or positive integer indicating the comparison result. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_memcasecmp(const UChar *s1, const UChar *s2, int32_t length, uint32_t options); sl@0: sl@0: /** sl@0: * Copy a ustring. Adds a null terminator. sl@0: * sl@0: * @param dst The destination string. sl@0: * @param src The source string. sl@0: * @return A pointer to dst. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UChar* U_EXPORT2 sl@0: u_strcpy(UChar *dst, sl@0: const UChar *src); sl@0: sl@0: /** sl@0: * Copy a ustring. sl@0: * Copies at most n characters. The result will be null terminated sl@0: * if the length of src is less than n. sl@0: * sl@0: * @param dst The destination string. sl@0: * @param src The source string. sl@0: * @param n The maximum number of characters to copy. sl@0: * @return A pointer to dst. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UChar* U_EXPORT2 sl@0: u_strncpy(UChar *dst, sl@0: const UChar *src, sl@0: int32_t n); sl@0: sl@0: #if !UCONFIG_NO_CONVERSION sl@0: sl@0: /** sl@0: * Copy a byte string encoded in the default codepage to a ustring. sl@0: * Adds a null terminator. sl@0: * Performs a host byte to UChar conversion sl@0: * sl@0: * @param dst The destination string. sl@0: * @param src The source string. sl@0: * @return A pointer to dst. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UChar* U_EXPORT2 u_uastrcpy(UChar *dst, sl@0: const char *src ); sl@0: sl@0: /** sl@0: * Copy a byte string encoded in the default codepage to a ustring. sl@0: * Copies at most n characters. The result will be null terminated sl@0: * if the length of src is less than n. sl@0: * Performs a host byte to UChar conversion sl@0: * sl@0: * @param dst The destination string. sl@0: * @param src The source string. sl@0: * @param n The maximum number of characters to copy. sl@0: * @return A pointer to dst. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UChar* U_EXPORT2 u_uastrncpy(UChar *dst, sl@0: const char *src, sl@0: int32_t n); sl@0: sl@0: /** sl@0: * Copy ustring to a byte string encoded in the default codepage. sl@0: * Adds a null terminator. sl@0: * Performs a UChar to host byte conversion sl@0: * sl@0: * @param dst The destination string. sl@0: * @param src The source string. sl@0: * @return A pointer to dst. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE char* U_EXPORT2 u_austrcpy(char *dst, sl@0: const UChar *src ); sl@0: sl@0: /** sl@0: * Copy ustring to a byte string encoded in the default codepage. sl@0: * Copies at most n characters. The result will be null terminated sl@0: * if the length of src is less than n. sl@0: * Performs a UChar to host byte conversion sl@0: * sl@0: * @param dst The destination string. sl@0: * @param src The source string. sl@0: * @param n The maximum number of characters to copy. sl@0: * @return A pointer to dst. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE char* U_EXPORT2 u_austrncpy(char *dst, sl@0: const UChar *src, sl@0: int32_t n ); sl@0: sl@0: #endif sl@0: sl@0: /** sl@0: * Synonym for memcpy(), but with UChars only. sl@0: * @param dest The destination string sl@0: * @param src The source string sl@0: * @param count The number of characters to copy sl@0: * @return A pointer to dest sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UChar* U_EXPORT2 sl@0: u_memcpy(UChar *dest, const UChar *src, int32_t count); sl@0: sl@0: /** sl@0: * Synonym for memmove(), but with UChars only. sl@0: * @param dest The destination string sl@0: * @param src The source string sl@0: * @param count The number of characters to move sl@0: * @return A pointer to dest sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UChar* U_EXPORT2 sl@0: u_memmove(UChar *dest, const UChar *src, int32_t count); sl@0: sl@0: /** sl@0: * Initialize count characters of dest to c. sl@0: * sl@0: * @param dest The destination string. sl@0: * @param c The character to initialize the string. sl@0: * @param count The maximum number of characters to set. sl@0: * @return A pointer to dest. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UChar* U_EXPORT2 sl@0: u_memset(UChar *dest, UChar c, int32_t count); sl@0: sl@0: /** sl@0: * Compare the first count UChars of each buffer. sl@0: * sl@0: * @param buf1 The first string to compare. sl@0: * @param buf2 The second string to compare. sl@0: * @param count The maximum number of UChars to compare. sl@0: * @return When buf1 < buf2, a negative number is returned. sl@0: * When buf1 == buf2, 0 is returned. sl@0: * When buf1 > buf2, a positive number is returned. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_memcmp(const UChar *buf1, const UChar *buf2, int32_t count); sl@0: sl@0: /** sl@0: * Compare two Unicode strings in code point order. sl@0: * This is different in UTF-16 from u_memcmp() if supplementary characters are present. sl@0: * For details, see u_strCompare(). sl@0: * sl@0: * @param s1 A string to compare. sl@0: * @param s2 A string to compare. sl@0: * @param count The maximum number of characters to compare. sl@0: * @return a negative/zero/positive integer corresponding to whether sl@0: * the first string is less than/equal to/greater than the second one sl@0: * in code point order sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_memcmpCodePointOrder(const UChar *s1, const UChar *s2, int32_t count); sl@0: sl@0: /** sl@0: * Find the first occurrence of a BMP code point in a string. sl@0: * A surrogate code point is found only if its match in the text is not sl@0: * part of a surrogate pair. sl@0: * A NUL character is found at the string terminator. sl@0: * sl@0: * @param s The string to search (contains count UChars). sl@0: * @param c The BMP code point to find. sl@0: * @param count The length of the string. sl@0: * @return A pointer to the first occurrence of c in s sl@0: * or NULL if c is not in s. sl@0: * @stable ICU 2.0 sl@0: * sl@0: * @see u_strchr sl@0: * @see u_memchr32 sl@0: * @see u_strFindFirst sl@0: */ sl@0: U_STABLE UChar* U_EXPORT2 sl@0: u_memchr(const UChar *s, UChar c, int32_t count); sl@0: sl@0: /** sl@0: * Find the first occurrence of a code point in a string. sl@0: * A surrogate code point is found only if its match in the text is not sl@0: * part of a surrogate pair. sl@0: * A NUL character is found at the string terminator. sl@0: * sl@0: * @param s The string to search (contains count UChars). sl@0: * @param c The code point to find. sl@0: * @param count The length of the string. sl@0: * @return A pointer to the first occurrence of c in s sl@0: * or NULL if c is not in s. sl@0: * @stable ICU 2.0 sl@0: * sl@0: * @see u_strchr32 sl@0: * @see u_memchr sl@0: * @see u_strFindFirst sl@0: */ sl@0: U_STABLE UChar* U_EXPORT2 sl@0: u_memchr32(const UChar *s, UChar32 c, int32_t count); sl@0: sl@0: /** sl@0: * Find the last occurrence of a BMP code point in a string. sl@0: * A surrogate code point is found only if its match in the text is not sl@0: * part of a surrogate pair. sl@0: * A NUL character is found at the string terminator. sl@0: * sl@0: * @param s The string to search (contains count UChars). sl@0: * @param c The BMP code point to find. sl@0: * @param count The length of the string. sl@0: * @return A pointer to the last occurrence of c in s sl@0: * or NULL if c is not in s. sl@0: * @stable ICU 2.4 sl@0: * sl@0: * @see u_strrchr sl@0: * @see u_memrchr32 sl@0: * @see u_strFindLast sl@0: */ sl@0: U_STABLE UChar* U_EXPORT2 sl@0: u_memrchr(const UChar *s, UChar c, int32_t count); sl@0: sl@0: /** sl@0: * Find the last occurrence of a code point in a string. sl@0: * A surrogate code point is found only if its match in the text is not sl@0: * part of a surrogate pair. sl@0: * A NUL character is found at the string terminator. sl@0: * sl@0: * @param s The string to search (contains count UChars). sl@0: * @param c The code point to find. sl@0: * @param count The length of the string. sl@0: * @return A pointer to the last occurrence of c in s sl@0: * or NULL if c is not in s. sl@0: * @stable ICU 2.4 sl@0: * sl@0: * @see u_strrchr32 sl@0: * @see u_memrchr sl@0: * @see u_strFindLast sl@0: */ sl@0: U_STABLE UChar* U_EXPORT2 sl@0: u_memrchr32(const UChar *s, UChar32 c, int32_t count); sl@0: sl@0: /** sl@0: * Unicode String literals in C. sl@0: * We need one macro to declare a variable for the string sl@0: * and to statically preinitialize it if possible, sl@0: * and a second macro to dynamically intialize such a string variable if necessary. sl@0: * sl@0: * The macros are defined for maximum performance. sl@0: * They work only for strings that contain "invariant characters", i.e., sl@0: * only latin letters, digits, and some punctuation. sl@0: * See utypes.h for details. sl@0: * sl@0: * A pair of macros for a single string must be used with the same sl@0: * parameters. sl@0: * The string parameter must be a C string literal. sl@0: * The length of the string, not including the terminating sl@0: * NUL, must be specified as a constant. sl@0: * The U_STRING_DECL macro should be invoked exactly once for one sl@0: * such string variable before it is used. sl@0: * sl@0: * Usage: sl@0: * 
sl@0:  *    U_STRING_DECL(ustringVar1, "Quick-Fox 2", 11);
sl@0:  *    U_STRING_DECL(ustringVar2, "jumps 5%", 8);
sl@0:  *    static UBool didInit=FALSE;
sl@0:  * 
sl@0:  *    int32_t function() {
sl@0:  *        if(!didInit) {
sl@0:  *            U_STRING_INIT(ustringVar1, "Quick-Fox 2", 11);
sl@0:  *            U_STRING_INIT(ustringVar2, "jumps 5%", 8);
sl@0:  *            didInit=TRUE;
sl@0:  *        }
sl@0:  *        return u_strcmp(ustringVar1, ustringVar2);
sl@0:  *    }
sl@0:  *
sl@0: * @stable ICU 2.0 sl@0: */ sl@0: #if U_SIZEOF_WCHAR_T==U_SIZEOF_UCHAR && (U_CHARSET_FAMILY==U_ASCII_FAMILY || (U_SIZEOF_UCHAR == 2 && defined(U_WCHAR_IS_UTF16))) sl@0: # define U_STRING_DECL(var, cs, length) static const wchar_t var[(length)+1]={ L ## cs } sl@0: /**@stable ICU 2.0 */ sl@0: # define U_STRING_INIT(var, cs, length) sl@0: #elif U_SIZEOF_UCHAR==1 && U_CHARSET_FAMILY==U_ASCII_FAMILY sl@0: # define U_STRING_DECL(var, cs, length) static const UChar var[(length)+1]={ (const UChar *)cs } sl@0: /**@stable ICU 2.0 */ sl@0: # define U_STRING_INIT(var, cs, length) sl@0: #else sl@0: # define U_STRING_DECL(var, cs, length) static UChar var[(length)+1] sl@0: /**@stable ICU 2.0 */ sl@0: # define U_STRING_INIT(var, cs, length) u_charsToUChars(cs, var, length+1) sl@0: #endif sl@0: sl@0: /** sl@0: * Unescape a string of characters and write the resulting sl@0: * Unicode characters to the destination buffer. The following escape sl@0: * sequences are recognized: sl@0: * sl@0: * \\uhhhh 4 hex digits; h in [0-9A-Fa-f] sl@0: * \\Uhhhhhhhh 8 hex digits sl@0: * \\xhh 1-2 hex digits sl@0: * \\x{h...} 1-8 hex digits sl@0: * \\ooo 1-3 octal digits; o in [0-7] sl@0: * \\cX control-X; X is masked with 0x1F sl@0: * sl@0: * as well as the standard ANSI C escapes: sl@0: * sl@0: * \\a => U+0007, \\b => U+0008, \\t => U+0009, \\n => U+000A, sl@0: * \\v => U+000B, \\f => U+000C, \\r => U+000D, \\e => U+001B, sl@0: * \\" => U+0022, \\' => U+0027, \\? => U+003F, \\\\ => U+005C sl@0: * sl@0: * Anything else following a backslash is generically escaped. For sl@0: * example, "[a\\-z]" returns "[a-z]". sl@0: * sl@0: * If an escape sequence is ill-formed, this method returns an empty sl@0: * string. An example of an ill-formed sequence is "\\u" followed by sl@0: * fewer than 4 hex digits. sl@0: * sl@0: * The above characters are recognized in the compiler's codepage, sl@0: * that is, they are coded as 'u', '\\', etc. Characters that are sl@0: * not parts of escape sequences are converted using u_charsToUChars(). sl@0: * sl@0: * This function is similar to UnicodeString::unescape() but not sl@0: * identical to it. The latter takes a source UnicodeString, so it sl@0: * does escape recognition but no conversion. sl@0: * sl@0: * @param src a zero-terminated string of invariant characters sl@0: * @param dest pointer to buffer to receive converted and unescaped sl@0: * text and, if there is room, a zero terminator. May be NULL for sl@0: * preflighting, in which case no UChars will be written, but the sl@0: * return value will still be valid. On error, an empty string is sl@0: * stored here (if possible). sl@0: * @param destCapacity the number of UChars that may be written at sl@0: * dest. Ignored if dest == NULL. sl@0: * @return the length of unescaped string. sl@0: * @see u_unescapeAt sl@0: * @see UnicodeString#unescape() sl@0: * @see UnicodeString#unescapeAt() sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_unescape(const char *src, sl@0: UChar *dest, int32_t destCapacity); sl@0: sl@0: U_CDECL_BEGIN sl@0: /** sl@0: * Callback function for u_unescapeAt() that returns a character of sl@0: * the source text given an offset and a context pointer. The context sl@0: * pointer will be whatever is passed into u_unescapeAt(). sl@0: * sl@0: * @param offset pointer to the offset that will be passed to u_unescapeAt(). sl@0: * @param context an opaque pointer passed directly into u_unescapeAt() sl@0: * @return the character represented by the escape sequence at sl@0: * offset sl@0: * @see u_unescapeAt sl@0: * @stable ICU 2.0 sl@0: */ sl@0: typedef UChar (U_CALLCONV *UNESCAPE_CHAR_AT)(int32_t offset, void *context); sl@0: U_CDECL_END sl@0: sl@0: /** sl@0: * Unescape a single sequence. The character at offset-1 is assumed sl@0: * (without checking) to be a backslash. This method takes a callback sl@0: * pointer to a function that returns the UChar at a given offset. By sl@0: * varying this callback, ICU functions are able to unescape char* sl@0: * strings, UnicodeString objects, and UFILE pointers. sl@0: * sl@0: * If offset is out of range, or if the escape sequence is ill-formed, sl@0: * (UChar32)0xFFFFFFFF is returned. See documentation of u_unescape() sl@0: * for a list of recognized sequences. sl@0: * sl@0: * @param charAt callback function that returns a UChar of the source sl@0: * text given an offset and a context pointer. sl@0: * @param offset pointer to the offset that will be passed to charAt. sl@0: * The offset value will be updated upon return to point after the sl@0: * last parsed character of the escape sequence. On error the offset sl@0: * is unchanged. sl@0: * @param length the number of characters in the source text. The sl@0: * last character of the source text is considered to be at offset sl@0: * length-1. sl@0: * @param context an opaque pointer passed directly into charAt. sl@0: * @return the character represented by the escape sequence at sl@0: * offset, or (UChar32)0xFFFFFFFF on error. sl@0: * @see u_unescape() sl@0: * @see UnicodeString#unescape() sl@0: * @see UnicodeString#unescapeAt() sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UChar32 U_EXPORT2 sl@0: u_unescapeAt(UNESCAPE_CHAR_AT charAt, sl@0: int32_t *offset, sl@0: int32_t length, sl@0: void *context); sl@0: sl@0: /** sl@0: * Uppercase the characters in a string. sl@0: * Casing is locale-dependent and context-sensitive. sl@0: * The result may be longer or shorter than the original. sl@0: * The source string and the destination buffer are allowed to overlap. sl@0: * sl@0: * @param dest A buffer for the result string. The result will be zero-terminated if sl@0: * the buffer is large enough. sl@0: * @param destCapacity The size of the buffer (number of UChars). If it is 0, then sl@0: * dest may be NULL and the function will only return the length of the result sl@0: * without writing any of the result string. sl@0: * @param src The original string sl@0: * @param srcLength The length of the original string. If -1, then src must be zero-terminated. sl@0: * @param locale The locale to consider, or "" for the root locale or NULL for the default locale. sl@0: * @param pErrorCode Must be a valid pointer to an error code value, sl@0: * which must not indicate a failure before the function call. sl@0: * @return The length of the result string. It may be greater than destCapacity. In that case, sl@0: * only some of the result was written to the destination buffer. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_strToUpper(UChar *dest, int32_t destCapacity, sl@0: const UChar *src, int32_t srcLength, sl@0: const char *locale, sl@0: UErrorCode *pErrorCode); sl@0: sl@0: /** sl@0: * Lowercase the characters in a string. sl@0: * Casing is locale-dependent and context-sensitive. sl@0: * The result may be longer or shorter than the original. sl@0: * The source string and the destination buffer are allowed to overlap. sl@0: * sl@0: * @param dest A buffer for the result string. The result will be zero-terminated if sl@0: * the buffer is large enough. sl@0: * @param destCapacity The size of the buffer (number of UChars). If it is 0, then sl@0: * dest may be NULL and the function will only return the length of the result sl@0: * without writing any of the result string. sl@0: * @param src The original string sl@0: * @param srcLength The length of the original string. If -1, then src must be zero-terminated. sl@0: * @param locale The locale to consider, or "" for the root locale or NULL for the default locale. sl@0: * @param pErrorCode Must be a valid pointer to an error code value, sl@0: * which must not indicate a failure before the function call. sl@0: * @return The length of the result string. It may be greater than destCapacity. In that case, sl@0: * only some of the result was written to the destination buffer. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_strToLower(UChar *dest, int32_t destCapacity, sl@0: const UChar *src, int32_t srcLength, sl@0: const char *locale, sl@0: UErrorCode *pErrorCode); sl@0: sl@0: #if !UCONFIG_NO_BREAK_ITERATION sl@0: sl@0: /** sl@0: * Titlecase a string. sl@0: * Casing is locale-dependent and context-sensitive. sl@0: * Titlecasing uses a break iterator to find the first characters of words sl@0: * that are to be titlecased. It titlecases those characters and lowercases sl@0: * all others. sl@0: * sl@0: * The titlecase break iterator can be provided to customize for arbitrary sl@0: * styles, using rules and dictionaries beyond the standard iterators. sl@0: * It may be more efficient to always provide an iterator to avoid sl@0: * opening and closing one for each string. sl@0: * The standard titlecase iterator for the root locale implements the sl@0: * algorithm of Unicode TR 21. sl@0: * sl@0: * This function uses only the first() and next() methods of the sl@0: * provided break iterator. sl@0: * sl@0: * The result may be longer or shorter than the original. sl@0: * The source string and the destination buffer are allowed to overlap. sl@0: * sl@0: * @param dest A buffer for the result string. The result will be zero-terminated if sl@0: * the buffer is large enough. sl@0: * @param destCapacity The size of the buffer (number of UChars). If it is 0, then sl@0: * dest may be NULL and the function will only return the length of the result sl@0: * without writing any of the result string. sl@0: * @param src The original string sl@0: * @param srcLength The length of the original string. If -1, then src must be zero-terminated. sl@0: * @param titleIter A break iterator to find the first characters of words sl@0: * that are to be titlecased. sl@0: * If none is provided (NULL), then a standard titlecase sl@0: * break iterator is opened. sl@0: * @param locale The locale to consider, or "" for the root locale or NULL for the default locale. sl@0: * @param pErrorCode Must be a valid pointer to an error code value, sl@0: * which must not indicate a failure before the function call. sl@0: * @return The length of the result string. It may be greater than destCapacity. In that case, sl@0: * only some of the result was written to the destination buffer. sl@0: * @stable ICU 2.1 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_strToTitle(UChar *dest, int32_t destCapacity, sl@0: const UChar *src, int32_t srcLength, sl@0: UBreakIterator *titleIter, sl@0: const char *locale, sl@0: UErrorCode *pErrorCode); sl@0: sl@0: #endif sl@0: sl@0: /** sl@0: * Case-fold the characters in a string. sl@0: * Case-folding is locale-independent and not context-sensitive, sl@0: * but there is an option for whether to include or exclude mappings for dotted I sl@0: * and dotless i that are marked with 'I' in CaseFolding.txt. sl@0: * The result may be longer or shorter than the original. sl@0: * The source string and the destination buffer are allowed to overlap. sl@0: * sl@0: * @param dest A buffer for the result string. The result will be zero-terminated if sl@0: * the buffer is large enough. sl@0: * @param destCapacity The size of the buffer (number of UChars). If it is 0, then sl@0: * dest may be NULL and the function will only return the length of the result sl@0: * without writing any of the result string. sl@0: * @param src The original string sl@0: * @param srcLength The length of the original string. If -1, then src must be zero-terminated. sl@0: * @param options Either U_FOLD_CASE_DEFAULT or U_FOLD_CASE_EXCLUDE_SPECIAL_I sl@0: * @param pErrorCode Must be a valid pointer to an error code value, sl@0: * which must not indicate a failure before the function call. sl@0: * @return The length of the result string. It may be greater than destCapacity. In that case, sl@0: * only some of the result was written to the destination buffer. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: u_strFoldCase(UChar *dest, int32_t destCapacity, sl@0: const UChar *src, int32_t srcLength, sl@0: uint32_t options, sl@0: UErrorCode *pErrorCode); sl@0: sl@0: /** sl@0: * Converts a sequence of UChars to wchar_t units. sl@0: * sl@0: * @param dest A buffer for the result string. The result will be zero-terminated if sl@0: * the buffer is large enough. sl@0: * @param destCapacity The size of the buffer (number of wchar_t's). If it is 0, then sl@0: * dest may be NULL and the function will only return the length of the sl@0: * result without writing any of the result string (pre-flighting). sl@0: * @param pDestLength A pointer to receive the number of units written to the destination. If sl@0: * pDestLength!=NULL then *pDestLength is always set to the sl@0: * number of output units corresponding to the transformation of sl@0: * all the input units, even in case of a buffer overflow. sl@0: * @param src The original source string sl@0: * @param srcLength The length of the original string. If -1, then src must be zero-terminated. sl@0: * @param pErrorCode Must be a valid pointer to an error code value, sl@0: * which must not indicate a failure before the function call. sl@0: * @return The pointer to destination buffer. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE wchar_t* U_EXPORT2 sl@0: u_strToWCS(wchar_t *dest, sl@0: int32_t destCapacity, sl@0: int32_t *pDestLength, sl@0: const UChar *src, sl@0: int32_t srcLength, sl@0: UErrorCode *pErrorCode); sl@0: /** sl@0: * Converts a sequence of wchar_t units to UChars sl@0: * sl@0: * @param dest A buffer for the result string. The result will be zero-terminated if sl@0: * the buffer is large enough. sl@0: * @param destCapacity The size of the buffer (number of UChars). If it is 0, then sl@0: * dest may be NULL and the function will only return the length of the sl@0: * result without writing any of the result string (pre-flighting). sl@0: * @param pDestLength A pointer to receive the number of units written to the destination. If sl@0: * pDestLength!=NULL then *pDestLength is always set to the sl@0: * number of output units corresponding to the transformation of sl@0: * all the input units, even in case of a buffer overflow. sl@0: * @param src The original source string sl@0: * @param srcLength The length of the original string. If -1, then src must be zero-terminated. sl@0: * @param pErrorCode Must be a valid pointer to an error code value, sl@0: * which must not indicate a failure before the function call. sl@0: * @return The pointer to destination buffer. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UChar* U_EXPORT2 sl@0: u_strFromWCS(UChar *dest, sl@0: int32_t destCapacity, sl@0: int32_t *pDestLength, sl@0: const wchar_t *src, sl@0: int32_t srcLength, sl@0: UErrorCode *pErrorCode); sl@0: /** sl@0: * Converts a sequence of UChars (UTF-16) to UTF-8 bytes sl@0: * sl@0: * @param dest A buffer for the result string. The result will be zero-terminated if sl@0: * the buffer is large enough. sl@0: * @param destCapacity The size of the buffer (number of chars). If it is 0, then sl@0: * dest may be NULL and the function will only return the length of the sl@0: * result without writing any of the result string (pre-flighting). sl@0: * @param pDestLength A pointer to receive the number of units written to the destination. If sl@0: * pDestLength!=NULL then *pDestLength is always set to the sl@0: * number of output units corresponding to the transformation of sl@0: * all the input units, even in case of a buffer overflow. sl@0: * @param src The original source string sl@0: * @param srcLength The length of the original string. If -1, then src must be zero-terminated. sl@0: * @param pErrorCode Must be a valid pointer to an error code value, sl@0: * which must not indicate a failure before the function call. sl@0: * @return The pointer to destination buffer. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE char* U_EXPORT2 sl@0: u_strToUTF8(char *dest, sl@0: int32_t destCapacity, sl@0: int32_t *pDestLength, sl@0: const UChar *src, sl@0: int32_t srcLength, sl@0: UErrorCode *pErrorCode); sl@0: sl@0: /** sl@0: * Converts a sequence of UTF-8 bytes to UChars (UTF-16). sl@0: * sl@0: * @param dest A buffer for the result string. The result will be zero-terminated if sl@0: * the buffer is large enough. sl@0: * @param destCapacity The size of the buffer (number of UChars). If it is 0, then sl@0: * dest may be NULL and the function will only return the length of the sl@0: * result without writing any of the result string (pre-flighting). sl@0: * @param pDestLength A pointer to receive the number of units written to the destination. If sl@0: * pDestLength!=NULL then *pDestLength is always set to the sl@0: * number of output units corresponding to the transformation of sl@0: * all the input units, even in case of a buffer overflow. sl@0: * @param src The original source string sl@0: * @param srcLength The length of the original string. If -1, then src must be zero-terminated. sl@0: * @param pErrorCode Must be a valid pointer to an error code value, sl@0: * which must not indicate a failure before the function call. sl@0: * @return The pointer to destination buffer. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UChar* U_EXPORT2 sl@0: u_strFromUTF8(UChar *dest, sl@0: int32_t destCapacity, sl@0: int32_t *pDestLength, sl@0: const char *src, sl@0: int32_t srcLength, sl@0: UErrorCode *pErrorCode); sl@0: sl@0: /** sl@0: * Converts a sequence of UChars (UTF-16) to UTF32 units. sl@0: * sl@0: * @param dest A buffer for the result string. The result will be zero-terminated if sl@0: * the buffer is large enough. sl@0: * @param destCapacity The size of the buffer (number of UChar32s). If it is 0, then sl@0: * dest may be NULL and the function will only return the length of the sl@0: * result without writing any of the result string (pre-flighting). sl@0: * @param pDestLength A pointer to receive the number of units written to the destination. If sl@0: * pDestLength!=NULL then *pDestLength is always set to the sl@0: * number of output units corresponding to the transformation of sl@0: * all the input units, even in case of a buffer overflow. sl@0: * @param src The original source string sl@0: * @param srcLength The length of the original string. If -1, then src must be zero-terminated. sl@0: * @param pErrorCode Must be a valid pointer to an error code value, sl@0: * which must not indicate a failure before the function call. sl@0: * @return The pointer to destination buffer. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UChar32* U_EXPORT2 sl@0: u_strToUTF32(UChar32 *dest, sl@0: int32_t destCapacity, sl@0: int32_t *pDestLength, sl@0: const UChar *src, sl@0: int32_t srcLength, sl@0: UErrorCode *pErrorCode); sl@0: sl@0: /** sl@0: * Converts a sequence of UTF32 units to UChars (UTF-16) sl@0: * sl@0: * @param dest A buffer for the result string. The result will be zero-terminated if sl@0: * the buffer is large enough. sl@0: * @param destCapacity The size of the buffer (number of UChars). If it is 0, then sl@0: * dest may be NULL and the function will only return the length of the sl@0: * result without writing any of the result string (pre-flighting). sl@0: * @param pDestLength A pointer to receive the number of units written to the destination. If sl@0: * pDestLength!=NULL then *pDestLength is always set to the sl@0: * number of output units corresponding to the transformation of sl@0: * all the input units, even in case of a buffer overflow. sl@0: * @param src The original source string sl@0: * @param srcLength The length of the original string. If -1, then src must be zero-terminated. sl@0: * @param pErrorCode Must be a valid pointer to an error code value, sl@0: * which must not indicate a failure before the function call. sl@0: * @return The pointer to destination buffer. sl@0: * @stable ICU 2.0 sl@0: */ sl@0: U_STABLE UChar* U_EXPORT2 sl@0: u_strFromUTF32(UChar *dest, sl@0: int32_t destCapacity, sl@0: int32_t *pDestLength, sl@0: const UChar32 *src, sl@0: int32_t srcLength, sl@0: UErrorCode *pErrorCode); sl@0: sl@0: #endif