ICU 72.1 72.1
Macros | Typedefs | Functions
ustring.h File Reference

C API: Unicode string handling functions. More...

#include "unicode/utypes.h"
#include "unicode/putil.h"
#include "unicode/uiter.h"

Go to the source code of this file.

Macros

#define UBRK_TYPEDEF_UBREAK_ITERATOR
 
#define U_STRING_DECL(var, cs, length)   static const UChar var[(length)+1]=L ## cs
 Unicode String literals in C. More...
 
#define U_STRING_INIT(var, cs, length)
 

Typedefs

typedef struct UBreakIterator UBreakIterator
 Simple declaration for u_strToTitle() to avoid including unicode/ubrk.h. More...
 
typedef UChar(* UNESCAPE_CHAR_AT) (int32_t offset, void *context)
 Callback function for u_unescapeAt() that returns a character of the source text given an offset and a context pointer. More...
 

Functions

U_CAPI int32_t u_strlen (const UChar *s)
 Determine the length of an array of UChar. More...
 
U_CAPI int32_t u_countChar32 (const UChar *s, int32_t length)
 Count Unicode code points in the length UChar code units of the string. More...
 
U_CAPI 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. More...
 
U_CAPI UCharu_strcat (UChar *dst, const UChar *src)
 Concatenate two ustrings. More...
 
U_CAPI UCharu_strncat (UChar *dst, const UChar *src, int32_t n)
 Concatenate two ustrings. More...
 
U_CAPI UCharu_strstr (const UChar *s, const UChar *substring)
 Find the first occurrence of a substring in a string. More...
 
U_CAPI UCharu_strFindFirst (const UChar *s, int32_t length, const UChar *substring, int32_t subLength)
 Find the first occurrence of a substring in a string. More...
 
U_CAPI UCharu_strchr (const UChar *s, UChar c)
 Find the first occurrence of a BMP code point in a string. More...
 
U_CAPI UCharu_strchr32 (const UChar *s, UChar32 c)
 Find the first occurrence of a code point in a string. More...
 
U_CAPI UCharu_strrstr (const UChar *s, const UChar *substring)
 Find the last occurrence of a substring in a string. More...
 
U_CAPI UCharu_strFindLast (const UChar *s, int32_t length, const UChar *substring, int32_t subLength)
 Find the last occurrence of a substring in a string. More...
 
U_CAPI UCharu_strrchr (const UChar *s, UChar c)
 Find the last occurrence of a BMP code point in a string. More...
 
U_CAPI UCharu_strrchr32 (const UChar *s, UChar32 c)
 Find the last occurrence of a code point in a string. More...
 
U_CAPI UCharu_strpbrk (const UChar *string, const UChar *matchSet)
 Locates the first occurrence in the string string of any of the characters in the string matchSet. More...
 
U_CAPI 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. More...
 
U_CAPI 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. More...
 
U_CAPI UCharu_strtok_r (UChar *src, const UChar *delim, UChar **saveState)
 The string tokenizer API allows an application to break a string into tokens. More...
 
U_CAPI int32_t u_strcmp (const UChar *s1, const UChar *s2)
 Compare two Unicode strings for bitwise equality (code unit order). More...
 
U_CAPI int32_t u_strcmpCodePointOrder (const UChar *s1, const UChar *s2)
 Compare two Unicode strings in code point order. More...
 
U_CAPI int32_t u_strCompare (const UChar *s1, int32_t length1, const UChar *s2, int32_t length2, UBool codePointOrder)
 Compare two Unicode strings (binary order). More...
 
U_CAPI int32_t u_strCompareIter (UCharIterator *iter1, UCharIterator *iter2, UBool codePointOrder)
 Compare two Unicode strings (binary order) as presented by UCharIterator objects. More...
 
U_CAPI 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. More...
 
U_CAPI int32_t u_strncmp (const UChar *ucs1, const UChar *ucs2, int32_t n)
 Compare two ustrings for bitwise equality. More...
 
U_CAPI int32_t u_strncmpCodePointOrder (const UChar *s1, const UChar *s2, int32_t n)
 Compare two Unicode strings in code point order. More...
 
U_CAPI int32_t u_strcasecmp (const UChar *s1, const UChar *s2, uint32_t options)
 Compare two strings case-insensitively using full case folding. More...
 
U_CAPI 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. More...
 
U_CAPI 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. More...
 
U_CAPI UCharu_strcpy (UChar *dst, const UChar *src)
 Copy a ustring. More...
 
U_CAPI UCharu_strncpy (UChar *dst, const UChar *src, int32_t n)
 Copy a ustring. More...
 
U_CAPI UCharu_uastrcpy (UChar *dst, const char *src)
 Copy a byte string encoded in the default codepage to a ustring. More...
 
U_CAPI UCharu_uastrncpy (UChar *dst, const char *src, int32_t n)
 Copy a byte string encoded in the default codepage to a ustring. More...
 
U_CAPI char * u_austrcpy (char *dst, const UChar *src)
 Copy ustring to a byte string encoded in the default codepage. More...
 
U_CAPI char * u_austrncpy (char *dst, const UChar *src, int32_t n)
 Copy ustring to a byte string encoded in the default codepage. More...
 
U_CAPI UCharu_memcpy (UChar *dest, const UChar *src, int32_t count)
 Synonym for memcpy(), but with UChars only. More...
 
U_CAPI UCharu_memmove (UChar *dest, const UChar *src, int32_t count)
 Synonym for memmove(), but with UChars only. More...
 
U_CAPI UCharu_memset (UChar *dest, UChar c, int32_t count)
 Initialize count characters of dest to c. More...
 
U_CAPI int32_t u_memcmp (const UChar *buf1, const UChar *buf2, int32_t count)
 Compare the first count UChars of each buffer. More...
 
U_CAPI int32_t u_memcmpCodePointOrder (const UChar *s1, const UChar *s2, int32_t count)
 Compare two Unicode strings in code point order. More...
 
U_CAPI UCharu_memchr (const UChar *s, UChar c, int32_t count)
 Find the first occurrence of a BMP code point in a string. More...
 
U_CAPI UCharu_memchr32 (const UChar *s, UChar32 c, int32_t count)
 Find the first occurrence of a code point in a string. More...
 
U_CAPI UCharu_memrchr (const UChar *s, UChar c, int32_t count)
 Find the last occurrence of a BMP code point in a string. More...
 
U_CAPI UCharu_memrchr32 (const UChar *s, UChar32 c, int32_t count)
 Find the last occurrence of a code point in a string. More...
 
U_CAPI 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. More...
 
U_CAPI UChar32 u_unescapeAt (UNESCAPE_CHAR_AT charAt, int32_t *offset, int32_t length, void *context)
 Unescape a single sequence. More...
 
U_CAPI 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. More...
 
U_CAPI 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. More...
 
U_CAPI 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. More...
 
U_CAPI int32_t u_strFoldCase (UChar *dest, int32_t destCapacity, const UChar *src, int32_t srcLength, uint32_t options, UErrorCode *pErrorCode)
 Case-folds the characters in a string. More...
 
U_CAPI wchar_t * u_strToWCS (wchar_t *dest, int32_t destCapacity, int32_t *pDestLength, const UChar *src, int32_t srcLength, UErrorCode *pErrorCode)
 Convert a UTF-16 string to a wchar_t string. More...
 
U_CAPI UCharu_strFromWCS (UChar *dest, int32_t destCapacity, int32_t *pDestLength, const wchar_t *src, int32_t srcLength, UErrorCode *pErrorCode)
 Convert a wchar_t string to UTF-16. More...
 
U_CAPI char * u_strToUTF8 (char *dest, int32_t destCapacity, int32_t *pDestLength, const UChar *src, int32_t srcLength, UErrorCode *pErrorCode)
 Convert a UTF-16 string to UTF-8. More...
 
U_CAPI UCharu_strFromUTF8 (UChar *dest, int32_t destCapacity, int32_t *pDestLength, const char *src, int32_t srcLength, UErrorCode *pErrorCode)
 Convert a UTF-8 string to UTF-16. More...
 
U_CAPI char * u_strToUTF8WithSub (char *dest, int32_t destCapacity, int32_t *pDestLength, const UChar *src, int32_t srcLength, UChar32 subchar, int32_t *pNumSubstitutions, UErrorCode *pErrorCode)
 Convert a UTF-16 string to UTF-8. More...
 
U_CAPI UCharu_strFromUTF8WithSub (UChar *dest, int32_t destCapacity, int32_t *pDestLength, const char *src, int32_t srcLength, UChar32 subchar, int32_t *pNumSubstitutions, UErrorCode *pErrorCode)
 Convert a UTF-8 string to UTF-16. More...
 
U_CAPI UCharu_strFromUTF8Lenient (UChar *dest, int32_t destCapacity, int32_t *pDestLength, const char *src, int32_t srcLength, UErrorCode *pErrorCode)
 Convert a UTF-8 string to UTF-16. More...
 
U_CAPI UChar32u_strToUTF32 (UChar32 *dest, int32_t destCapacity, int32_t *pDestLength, const UChar *src, int32_t srcLength, UErrorCode *pErrorCode)
 Convert a UTF-16 string to UTF-32. More...
 
U_CAPI UCharu_strFromUTF32 (UChar *dest, int32_t destCapacity, int32_t *pDestLength, const UChar32 *src, int32_t srcLength, UErrorCode *pErrorCode)
 Convert a UTF-32 string to UTF-16. More...
 
U_CAPI UChar32u_strToUTF32WithSub (UChar32 *dest, int32_t destCapacity, int32_t *pDestLength, const UChar *src, int32_t srcLength, UChar32 subchar, int32_t *pNumSubstitutions, UErrorCode *pErrorCode)
 Convert a UTF-16 string to UTF-32. More...
 
U_CAPI UCharu_strFromUTF32WithSub (UChar *dest, int32_t destCapacity, int32_t *pDestLength, const UChar32 *src, int32_t srcLength, UChar32 subchar, int32_t *pNumSubstitutions, UErrorCode *pErrorCode)
 Convert a UTF-32 string to UTF-16. More...
 
U_CAPI char * u_strToJavaModifiedUTF8 (char *dest, int32_t destCapacity, int32_t *pDestLength, const UChar *src, int32_t srcLength, UErrorCode *pErrorCode)
 Convert a 16-bit Unicode string to Java Modified UTF-8. More...
 
U_CAPI UCharu_strFromJavaModifiedUTF8WithSub (UChar *dest, int32_t destCapacity, int32_t *pDestLength, const char *src, int32_t srcLength, UChar32 subchar, int32_t *pNumSubstitutions, UErrorCode *pErrorCode)
 Convert a Java Modified UTF-8 string to a 16-bit Unicode string. More...
 

Detailed Description

C API: Unicode string handling functions.

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 (https://unicode-org.github.io/icu/userguide/strings/). 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.

Macro Definition Documentation

◆ U_STRING_DECL

#define U_STRING_DECL (   var,
  cs,
  length 
)    static const UChar var[(length)+1]=L ## cs

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 initialize 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 NUL, must be specified as a constant. The U_STRING_DECL macro should be invoked exactly once for one such string variable before it is used.

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);
}

Note that the macros will NOT consistently work if their argument is another #define. The following will not work on all platforms, don't use it.

#define GLUCK "Mr. Gluck"
U_STRING_DECL(var, GLUCK, 9)
U_STRING_INIT(var, GLUCK, 9)

Instead, use the string literal "Mr. Gluck" as the argument to both macro calls.

Stable:
ICU 2.0

Definition at line 935 of file ustring.h.

◆ U_STRING_INIT

#define U_STRING_INIT (   var,
  cs,
  length 
)
Stable:
ICU 2.0

Definition at line 937 of file ustring.h.

◆ UBRK_TYPEDEF_UBREAK_ITERATOR

#define UBRK_TYPEDEF_UBREAK_ITERATOR
Internal:
Do not use. This API is for internal use only.

Definition at line 31 of file ustring.h.

Typedef Documentation

◆ UBreakIterator

Simple declaration for u_strToTitle() to avoid including unicode/ubrk.h.

Stable:
ICU 2.1

Definition at line 33 of file ustring.h.

◆ UNESCAPE_CHAR_AT

typedef UChar(* UNESCAPE_CHAR_AT) (int32_t offset, void *context)

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().

Parameters
offsetpointer to the offset that will be passed to u_unescapeAt().
contextan opaque pointer passed directly into u_unescapeAt()
Returns
the character represented by the escape sequence at offset
See also
u_unescapeAt
Stable:
ICU 2.0

Definition at line 1012 of file ustring.h.

Function Documentation

◆ u_austrcpy()

U_CAPI char * u_austrcpy ( char *  dst,
const UChar src 
)

Copy ustring to a byte string encoded in the default codepage.

Adds a null terminator. Performs a UChar to host byte conversion

Parameters
dstThe destination string.
srcThe source string.
Returns
A pointer to dst.
Stable:
ICU 2.0

◆ u_austrncpy()

U_CAPI char * u_austrncpy ( char *  dst,
const UChar src,
int32_t  n 
)

Copy ustring to a byte string encoded in the default codepage.

Copies at most n characters. The result will be null terminated if the length of src is less than n. Performs a UChar to host byte conversion

Parameters
dstThe destination string.
srcThe source string.
nThe maximum number of characters to copy.
Returns
A pointer to dst.
Stable:
ICU 2.0

◆ u_countChar32()

U_CAPI int32_t u_countChar32 ( const UChar s,
int32_t  length 
)

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).

Parameters
sThe input string.
lengthThe number of UChar code units to be checked, or -1 to count all code points before the first NUL (U+0000).
Returns
The number of code points in the specified code units.
Stable:
ICU 2.0

◆ u_memcasecmp()

U_CAPI 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.

This is equivalent to u_strcmp(u_strFoldCase(s1, n, options), u_strFoldCase(s2, n, options)).

Parameters
s1A string to compare.
s2A string to compare.
lengthThe number of characters in each string to case-fold and then compare.
optionsA bit set of options:
  • U_FOLD_CASE_DEFAULT or 0 is used for default options: Comparison in code unit order with default case folding.
  • U_COMPARE_CODE_POINT_ORDER Set to choose code point order instead of code unit order (see u_strCompare for details).
  • U_FOLD_CASE_EXCLUDE_SPECIAL_I
Returns
A negative, zero, or positive integer indicating the comparison result.
Stable:
ICU 2.0

◆ u_memchr()

U_CAPI UChar * u_memchr ( const UChar s,
UChar  c,
int32_t  count 
)

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.

Parameters
sThe string to search (contains count UChars).
cThe BMP code point to find.
countThe length of the string.
Returns
A pointer to the first occurrence of c in s or NULL if c is not in s.
Stable:
ICU 2.0
See also
u_strchr
u_memchr32
u_strFindFirst

◆ u_memchr32()

U_CAPI UChar * u_memchr32 ( const UChar s,
UChar32  c,
int32_t  count 
)

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.

Parameters
sThe string to search (contains count UChars).
cThe code point to find.
countThe length of the string.
Returns
A pointer to the first occurrence of c in s or NULL if c is not in s.
Stable:
ICU 2.0
See also
u_strchr32
u_memchr
u_strFindFirst

◆ u_memcmp()

U_CAPI int32_t u_memcmp ( const UChar buf1,
const UChar buf2,
int32_t  count 
)

Compare the first count UChars of each buffer.

Parameters
buf1The first string to compare.
buf2The second string to compare.
countThe maximum number of UChars to compare.
Returns
When buf1 < buf2, a negative number is returned. When buf1 == buf2, 0 is returned. When buf1 > buf2, a positive number is returned.
Stable:
ICU 2.0

◆ u_memcmpCodePointOrder()

U_CAPI int32_t u_memcmpCodePointOrder ( const UChar s1,
const UChar s2,
int32_t  count 
)

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().

Parameters
s1A string to compare.
s2A string to compare.
countThe maximum number of characters to compare.
Returns
a negative/zero/positive integer corresponding to whether the first string is less than/equal to/greater than the second one in code point order
Stable:
ICU 2.0

◆ u_memcpy()

U_CAPI UChar * u_memcpy ( UChar dest,
const UChar src,
int32_t  count 
)

Synonym for memcpy(), but with UChars only.

Parameters
destThe destination string
srcThe source string (can be NULL/invalid if count<=0)
countThe number of characters to copy; no-op if <=0
Returns
A pointer to dest
Stable:
ICU 2.0

◆ u_memmove()

U_CAPI UChar * u_memmove ( UChar dest,
const UChar src,
int32_t  count 
)

Synonym for memmove(), but with UChars only.

Parameters
destThe destination string
srcThe source string (can be NULL/invalid if count<=0)
countThe number of characters to move; no-op if <=0
Returns
A pointer to dest
Stable:
ICU 2.0

◆ u_memrchr()

U_CAPI UChar * u_memrchr ( const UChar s,
UChar  c,
int32_t  count 
)

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.

Parameters
sThe string to search (contains count UChars).
cThe BMP code point to find.
countThe length of the string.
Returns
A pointer to the last occurrence of c in s or NULL if c is not in s.
Stable:
ICU 2.4
See also
u_strrchr
u_memrchr32
u_strFindLast

◆ u_memrchr32()

U_CAPI UChar * u_memrchr32 ( const UChar s,
UChar32  c,
int32_t  count 
)

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.

Parameters
sThe string to search (contains count UChars).
cThe code point to find.
countThe length of the string.
Returns
A pointer to the last occurrence of c in s or NULL if c is not in s.
Stable:
ICU 2.4
See also
u_strrchr32
u_memrchr
u_strFindLast

◆ u_memset()

U_CAPI UChar * u_memset ( UChar dest,
UChar  c,
int32_t  count 
)

Initialize count characters of dest to c.

Parameters
destThe destination string.
cThe character to initialize the string.
countThe maximum number of characters to set.
Returns
A pointer to dest.
Stable:
ICU 2.0

◆ u_strcasecmp()

U_CAPI int32_t u_strcasecmp ( const UChar s1,
const UChar s2,
uint32_t  options 
)

Compare two strings case-insensitively using full case folding.

This is equivalent to u_strcmp(u_strFoldCase(s1, options), u_strFoldCase(s2, options)).

Parameters
s1A string to compare.
s2A string to compare.
optionsA bit set of options:
  • U_FOLD_CASE_DEFAULT or 0 is used for default options: Comparison in code unit order with default case folding.
  • U_COMPARE_CODE_POINT_ORDER Set to choose code point order instead of code unit order (see u_strCompare for details).
  • U_FOLD_CASE_EXCLUDE_SPECIAL_I
Returns
A negative, zero, or positive integer indicating the comparison result.
Stable:
ICU 2.0

◆ u_strCaseCompare()

U_CAPI 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.

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.

Parameters
s1First source string.
length1Length of first source string, or -1 if NUL-terminated.
s2Second source string.
length2Length of second source string, or -1 if NUL-terminated.
optionsA bit set of options:
  • U_FOLD_CASE_DEFAULT or 0 is used for default options: Comparison in code unit order with default case folding.
  • U_COMPARE_CODE_POINT_ORDER Set to choose code point order instead of code unit order (see u_strCompare for details).
  • U_FOLD_CASE_EXCLUDE_SPECIAL_I
pErrorCodeMust be a valid pointer to an error code value, which must not indicate a failure before the function call.
Returns
<0 or 0 or >0 as usual for string comparisons
Stable:
ICU 2.2

◆ u_strcat()

U_CAPI UChar * u_strcat ( UChar dst,
const UChar src 
)

Concatenate two ustrings.

Appends a copy of src, including the null terminator, to dst. The initial copied character from src overwrites the null terminator in dst.

Parameters
dstThe destination string.
srcThe source string.
Returns
A pointer to dst.
Stable:
ICU 2.0

◆ u_strchr()

U_CAPI UChar * u_strchr ( const UChar s,
UChar  c 
)

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.

Parameters
sThe string to search (NUL-terminated).
cThe BMP code point to find.
Returns
A pointer to the first occurrence of c in s or NULL if c is not in s.
Stable:
ICU 2.0
See also
u_strchr32
u_memchr
u_strstr
u_strFindFirst

◆ u_strchr32()

U_CAPI UChar * u_strchr32 ( const UChar s,
UChar32  c 
)

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.

Parameters
sThe string to search (NUL-terminated).
cThe code point to find.
Returns
A pointer to the first occurrence of c in s or NULL if c is not in s.
Stable:
ICU 2.0
See also
u_strchr
u_memchr32
u_strstr
u_strFindFirst

◆ u_strcmp()

U_CAPI int32_t u_strcmp ( const UChar s1,
const UChar s2 
)

Compare two Unicode strings for bitwise equality (code unit order).

Parameters
s1A string to compare.
s2A string to compare.
Returns
0 if s1 and s2 are bitwise equal; a negative value if s1 is bitwise less than s2,; a positive value if s1 is bitwise greater than s2.
Stable:
ICU 2.0

◆ u_strcmpCodePointOrder()

U_CAPI int32_t u_strcmpCodePointOrder ( const UChar s1,
const UChar s2 
)

Compare two Unicode strings in code point order.

See u_strCompare for details.

Parameters
s1A string to compare.
s2A string to compare.
Returns
a negative/zero/positive integer corresponding to whether the first string is less than/equal to/greater than the second one in code point order
Stable:
ICU 2.0

◆ u_strCompare()

U_CAPI int32_t u_strCompare ( const UChar s1,
int32_t  length1,
const UChar s2,
int32_t  length2,
UBool  codePointOrder 
)

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.

Parameters
s1First source string.
length1Length of first source string, or -1 if NUL-terminated.
s2Second source string.
length2Length of second source string, or -1 if NUL-terminated.
codePointOrderChoose between code unit order (false) and code point order (true).
Returns
<0 or 0 or >0 as usual for string comparisons
Stable:
ICU 2.2

◆ u_strCompareIter()

U_CAPI int32_t u_strCompareIter ( UCharIterator iter1,
UCharIterator iter2,
UBool  codePointOrder 
)

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.

Parameters
iter1First source string iterator.
iter2Second source string iterator.
codePointOrderChoose between code unit order (false) and code point order (true).
Returns
<0 or 0 or >0 as usual for string comparisons
See also
u_strCompare
Stable:
ICU 2.6

◆ u_strcpy()

U_CAPI UChar * u_strcpy ( UChar dst,
const UChar src 
)

Copy a ustring.

Adds a null terminator.

Parameters
dstThe destination string.
srcThe source string.
Returns
A pointer to dst.
Stable:
ICU 2.0

◆ u_strcspn()

U_CAPI 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.

Works just like C's strcspn but with Unicode.

Parameters
stringThe string in which to search, NUL-terminated.
matchSetA NUL-terminated string defining a set of code points for which to search in the text string.
Returns
The number of initial characters in string that do not occur in matchSet.
See also
u_strspn
Stable:
ICU 2.0

◆ u_strFindFirst()

U_CAPI 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.

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.

Parameters
sThe string to search.
lengthThe length of s (number of UChars), or -1 if it is NUL-terminated.
substringThe substring to find (NUL-terminated).
subLengthThe length of substring (number of UChars), or -1 if it is NUL-terminated.
Returns
A pointer to the first occurrence of substring in s, or s itself if the substring is empty, or NULL if substring is not in s.
Stable:
ICU 2.4
See also
u_strstr
u_strFindLast

◆ u_strFindLast()

U_CAPI 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.

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.

Parameters
sThe string to search.
lengthThe length of s (number of UChars), or -1 if it is NUL-terminated.
substringThe substring to find (NUL-terminated).
subLengthThe length of substring (number of UChars), or -1 if it is NUL-terminated.
Returns
A pointer to the last occurrence of substring in s, or s itself if the substring is empty, or NULL if substring is not in s.
Stable:
ICU 2.4
See also
u_strstr
u_strFindLast

◆ u_strFoldCase()

U_CAPI int32_t u_strFoldCase ( UChar dest,
int32_t  destCapacity,
const UChar src,
int32_t  srcLength,
uint32_t  options,
UErrorCode pErrorCode 
)

Case-folds 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 'T' in CaseFolding.txt.

The result may be longer or shorter than the original. The source string and the destination buffer are allowed to overlap.

Parameters
destA buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacityThe size of the buffer (number of UChars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string.
srcThe original string
srcLengthThe length of the original string. If -1, then src must be zero-terminated.
optionsEither U_FOLD_CASE_DEFAULT or U_FOLD_CASE_EXCLUDE_SPECIAL_I
pErrorCodeMust be a valid pointer to an error code value, which must not indicate a failure before the function call.
Returns
The length of the result string. It may be greater than destCapacity. In that case, only some of the result was written to the destination buffer.
Stable:
ICU 2.0

◆ u_strFromJavaModifiedUTF8WithSub()

U_CAPI UChar * u_strFromJavaModifiedUTF8WithSub ( UChar dest,
int32_t  destCapacity,
int32_t *  pDestLength,
const char *  src,
int32_t  srcLength,
UChar32  subchar,
int32_t *  pNumSubstitutions,
UErrorCode pErrorCode 
)

Convert a Java Modified UTF-8 string to a 16-bit Unicode string.

If the input string is not well-formed and no substitution char is specified, then the U_INVALID_CHAR_FOUND error code is set.

This function behaves according to the documentation for Java DataInput.readUTF() except that it takes a length parameter rather than interpreting the first two input bytes as the length. See http://java.sun.com/javase/6/docs/api/java/io/DataInput.html#readUTF()

The output string may not be well-formed UTF-16.

Parameters
destA buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacityThe size of the buffer (number of UChars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
pDestLengthA pointer to receive the number of units written to the destination. If pDestLength!=NULL then *pDestLength is always set to the number of output units corresponding to the transformation of all the input units, even in case of a buffer overflow.
srcThe original source string
srcLengthThe length of the original string. If -1, then src must be zero-terminated.
subcharThe substitution character to use in place of an illegal input sequence, or U_SENTINEL if the function is to return with U_INVALID_CHAR_FOUND instead. A substitution character can be any valid Unicode code point (up to U+10FFFF) except for surrogate code points (U+D800..U+DFFF). The recommended value is U+FFFD "REPLACEMENT CHARACTER".
pNumSubstitutionsOutput parameter receiving the number of substitutions if subchar>=0. Set to 0 if no substitutions occur or subchar<0. pNumSubstitutions can be NULL.
pErrorCodePointer to a standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)
Returns
The pointer to destination buffer.
See also
u_strFromUTF8WithSub
u_strFromUTF8Lenient
u_strToJavaModifiedUTF8
Stable:
ICU 4.4

◆ u_strFromUTF32()

U_CAPI UChar * u_strFromUTF32 ( UChar dest,
int32_t  destCapacity,
int32_t *  pDestLength,
const UChar32 src,
int32_t  srcLength,
UErrorCode pErrorCode 
)

Convert a UTF-32 string to UTF-16.

If the input string is not well-formed, then the U_INVALID_CHAR_FOUND error code is set.

Parameters
destA buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacityThe size of the buffer (number of UChars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
pDestLengthA pointer to receive the number of units written to the destination. If pDestLength!=NULL then *pDestLength is always set to the number of output units corresponding to the transformation of all the input units, even in case of a buffer overflow.
srcThe original source string
srcLengthThe length of the original string. If -1, then src must be zero-terminated.
pErrorCodeMust be a valid pointer to an error code value, which must not indicate a failure before the function call.
Returns
The pointer to destination buffer.
See also
u_strFromUTF32WithSub
u_strToUTF32
Stable:
ICU 2.0

◆ u_strFromUTF32WithSub()

U_CAPI UChar * u_strFromUTF32WithSub ( UChar dest,
int32_t  destCapacity,
int32_t *  pDestLength,
const UChar32 src,
int32_t  srcLength,
UChar32  subchar,
int32_t *  pNumSubstitutions,
UErrorCode pErrorCode 
)

Convert a UTF-32 string to UTF-16.

Same as u_strFromUTF32() 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_strFromUTF32().

Parameters
destA buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacityThe size of the buffer (number of UChars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
pDestLengthA pointer to receive the number of units written to the destination. If pDestLength!=NULL then *pDestLength is always set to the number of output units corresponding to the transformation of all the input units, even in case of a buffer overflow.
srcThe original source string
srcLengthThe length of the original string. If -1, then src must be zero-terminated.
subcharThe substitution character to use in place of an illegal input sequence, or U_SENTINEL if the function is to return with U_INVALID_CHAR_FOUND instead. A substitution character can be any valid Unicode code point (up to U+10FFFF) except for surrogate code points (U+D800..U+DFFF). The recommended value is U+FFFD "REPLACEMENT CHARACTER".
pNumSubstitutionsOutput parameter receiving the number of substitutions if subchar>=0. Set to 0 if no substitutions occur or subchar<0. pNumSubstitutions can be NULL.
pErrorCodePointer to a standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)
Returns
The pointer to destination buffer.
See also
u_strFromUTF32
u_strToUTF32WithSub
Stable:
ICU 4.2

◆ u_strFromUTF8()

U_CAPI UChar * u_strFromUTF8 ( UChar dest,
int32_t  destCapacity,
int32_t *  pDestLength,
const char *  src,
int32_t  srcLength,
UErrorCode pErrorCode 
)

Convert a UTF-8 string to UTF-16.

If the input string is not well-formed, then the U_INVALID_CHAR_FOUND error code is set.

Parameters
destA buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacityThe size of the buffer (number of UChars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
pDestLengthA pointer to receive the number of units written to the destination. If pDestLength!=NULL then *pDestLength is always set to the number of output units corresponding to the transformation of all the input units, even in case of a buffer overflow.
srcThe original source string
srcLengthThe length of the original string. If -1, then src must be zero-terminated.
pErrorCodeMust be a valid pointer to an error code value, which must not indicate a failure before the function call.
Returns
The pointer to destination buffer.
Stable:
ICU 2.0
See also
u_strFromUTF8WithSub
u_strFromUTF8Lenient

◆ u_strFromUTF8Lenient()

U_CAPI UChar * u_strFromUTF8Lenient ( UChar dest,
int32_t  destCapacity,
int32_t *  pDestLength,
const char *  src,
int32_t  srcLength,
UErrorCode pErrorCode 
)

Convert a UTF-8 string to 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:

  • Well-formed UTF-8 text is correctly converted to well-formed UTF-16 text.
  • The function will not read beyond the input string, nor write beyond the destCapacity.
  • Malformed UTF-8 results in "garbage" 16-bit Unicode strings which may not be well-formed UTF-16. The function will resynchronize to valid code point boundaries within a small number of code points after an illegal sequence.
  • Non-shortest forms are not detected and will result in "spoofing" output.

For further performance improvement, if srcLength is given (>=0), then it must be destCapacity>=srcLength.

There is no inverse u_strToUTF8Lenient() function because there is practically no performance gain from not checking that a UTF-16 string is well-formed.

Parameters
destA buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacityThe size of the buffer (number of UChars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting). Unlike for other ICU functions, if srcLength>=0 then it must be destCapacity>=srcLength.
pDestLengthA pointer to receive the number of units written to the destination. If pDestLength!=NULL then *pDestLength is always set to the number of output units corresponding to the transformation of all the input units, even in case of a buffer overflow. Unlike for other ICU functions, if srcLength>=0 but destCapacity<srcLength, then *pDestLength will be set to srcLength (and U_BUFFER_OVERFLOW_ERROR will be set) regardless of the actual result length.
srcThe original source string
srcLengthThe length of the original string. If -1, then src must be zero-terminated.
pErrorCodePointer to a standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)
Returns
The pointer to destination buffer.
See also
u_strFromUTF8
u_strFromUTF8WithSub
u_strToUTF8WithSub
Stable:
ICU 3.6

◆ u_strFromUTF8WithSub()

U_CAPI UChar * u_strFromUTF8WithSub ( UChar dest,
int32_t  destCapacity,
int32_t *  pDestLength,
const char *  src,
int32_t  srcLength,
UChar32  subchar,
int32_t *  pNumSubstitutions,
UErrorCode pErrorCode 
)

Convert a UTF-8 string to 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().

Parameters
destA buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacityThe size of the buffer (number of UChars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
pDestLengthA pointer to receive the number of units written to the destination. If pDestLength!=NULL then *pDestLength is always set to the number of output units corresponding to the transformation of all the input units, even in case of a buffer overflow.
srcThe original source string
srcLengthThe length of the original string. If -1, then src must be zero-terminated.
subcharThe substitution character to use in place of an illegal input sequence, or U_SENTINEL if the function is to return with U_INVALID_CHAR_FOUND instead. A substitution character can be any valid Unicode code point (up to U+10FFFF) except for surrogate code points (U+D800..U+DFFF). The recommended value is U+FFFD "REPLACEMENT CHARACTER".
pNumSubstitutionsOutput parameter receiving the number of substitutions if subchar>=0. Set to 0 if no substitutions occur or subchar<0. pNumSubstitutions can be NULL.
pErrorCodePointer to a standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)
Returns
The pointer to destination buffer.
See also
u_strFromUTF8
u_strFromUTF8Lenient
u_strToUTF8WithSub
Stable:
ICU 3.6

◆ u_strFromWCS()

U_CAPI UChar * u_strFromWCS ( UChar dest,
int32_t  destCapacity,
int32_t *  pDestLength,
const wchar_t *  src,
int32_t  srcLength,
UErrorCode pErrorCode 
)

Convert a wchar_t string to UTF-16.

If it is known at compile time that wchar_t strings are in UTF-16 or UTF-32, then this function simply calls the fast, dedicated function for that. Otherwise, two conversions wchar_t* -> default charset -> UTF-16 are performed.

Parameters
destA buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacityThe size of the buffer (number of UChars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
pDestLengthA pointer to receive the number of units written to the destination. If pDestLength!=NULL then *pDestLength is always set to the number of output units corresponding to the transformation of all the input units, even in case of a buffer overflow.
srcThe original source string
srcLengthThe length of the original string. If -1, then src must be zero-terminated.
pErrorCodeMust be a valid pointer to an error code value, which must not indicate a failure before the function call.
Returns
The pointer to destination buffer.
Stable:
ICU 2.0

◆ u_strHasMoreChar32Than()

U_CAPI 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.

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.

Parameters
sThe input string.
lengthThe length of the string, or -1 if it is NUL-terminated.
numberThe number of code points in the string is compared against the 'number' parameter.
Returns
Boolean value for whether the string contains more Unicode code points than 'number'. Same as (u_countChar32(s, length)>number).
Stable:
ICU 2.4

◆ u_strlen()

U_CAPI int32_t u_strlen ( const UChar s)

Determine the length of an array of UChar.

Parameters
sThe array of UChars, NULL (U+0000) terminated.
Returns
The number of UChars in chars, minus the terminator.
Stable:
ICU 2.0

◆ u_strncasecmp()

U_CAPI 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.

This is equivalent to u_strcmp(u_strFoldCase(s1, at most n, options), u_strFoldCase(s2, at most n, options)).

Parameters
s1A string to compare.
s2A string to compare.
nThe maximum number of characters each string to case-fold and then compare.
optionsA bit set of options:
  • U_FOLD_CASE_DEFAULT or 0 is used for default options: Comparison in code unit order with default case folding.
  • U_COMPARE_CODE_POINT_ORDER Set to choose code point order instead of code unit order (see u_strCompare for details).
  • U_FOLD_CASE_EXCLUDE_SPECIAL_I
Returns
A negative, zero, or positive integer indicating the comparison result.
Stable:
ICU 2.0

◆ u_strncat()

U_CAPI UChar * u_strncat ( UChar dst,
const UChar src,
int32_t  n 
)

Concatenate two ustrings.


Appends at most n characters from src to dst. Adds a terminating NUL. If src is too long, then only n-1 characters will be copied before the terminating NUL. If n<=0 then dst is not modified.

Parameters
dstThe destination string.
srcThe source string (can be NULL/invalid if n<=0).
nThe maximum number of characters to append; no-op if <=0.
Returns
A pointer to dst.
Stable:
ICU 2.0

◆ u_strncmp()

U_CAPI int32_t u_strncmp ( const UChar ucs1,
const UChar ucs2,
int32_t  n 
)

Compare two ustrings for bitwise equality.

Compares at most n characters.

Parameters
ucs1A string to compare (can be NULL/invalid if n<=0).
ucs2A string to compare (can be NULL/invalid if n<=0).
nThe maximum number of characters to compare; always returns 0 if n<=0.
Returns
0 if s1 and s2 are bitwise equal; a negative value if s1 is bitwise less than s2; a positive value if s1 is bitwise greater than s2.
Stable:
ICU 2.0

◆ u_strncmpCodePointOrder()

U_CAPI int32_t u_strncmpCodePointOrder ( const UChar s1,
const UChar s2,
int32_t  n 
)

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().

Parameters
s1A string to compare.
s2A string to compare.
nThe maximum number of characters to compare.
Returns
a negative/zero/positive integer corresponding to whether the first string is less than/equal to/greater than the second one in code point order
Stable:
ICU 2.0

◆ u_strncpy()

U_CAPI UChar * u_strncpy ( UChar dst,
const UChar src,
int32_t  n 
)

Copy a ustring.

Copies at most n characters. The result will be null terminated if the length of src is less than n.

Parameters
dstThe destination string.
srcThe source string (can be NULL/invalid if n<=0).
nThe maximum number of characters to copy; no-op if <=0.
Returns
A pointer to dst.
Stable:
ICU 2.0

◆ u_strpbrk()

U_CAPI 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.

Works just like C's strpbrk but with Unicode.

Parameters
stringThe string in which to search, NUL-terminated.
matchSetA NUL-terminated string defining a set of code points for which to search in the text string.
Returns
A pointer to the character in string that matches one of the characters in matchSet, or NULL if no such character is found.
Stable:
ICU 2.0

◆ u_strrchr()

U_CAPI UChar * u_strrchr ( const UChar s,
UChar  c 
)

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.

Parameters
sThe string to search (NUL-terminated).
cThe BMP code point to find.
Returns
A pointer to the last occurrence of c in s or NULL if c is not in s.
Stable:
ICU 2.4
See also
u_strrchr32
u_memrchr
u_strrstr
u_strFindLast

◆ u_strrchr32()

U_CAPI UChar * u_strrchr32 ( const UChar s,
UChar32  c 
)

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.

Parameters
sThe string to search (NUL-terminated).
cThe code point to find.
Returns
A pointer to the last occurrence of c in s or NULL if c is not in s.
Stable:
ICU 2.4
See also
u_strrchr
u_memchr32
u_strrstr
u_strFindLast

◆ u_strrstr()

U_CAPI UChar * u_strrstr ( const UChar s,
const UChar substring 
)

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.

Parameters
sThe string to search (NUL-terminated).
substringThe substring to find (NUL-terminated).
Returns
A pointer to the last occurrence of substring in s, or s itself if the substring is empty, or NULL if substring is not in s.
Stable:
ICU 2.4
See also
u_strstr
u_strFindFirst
u_strFindLast

◆ u_strspn()

U_CAPI 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.

Works just like C's strspn but with Unicode.

Parameters
stringThe string in which to search, NUL-terminated.
matchSetA NUL-terminated string defining a set of code points for which to search in the text string.
Returns
The number of initial characters in string that do occur in matchSet.
See also
u_strcspn
Stable:
ICU 2.0

◆ u_strstr()

U_CAPI UChar * u_strstr ( const UChar s,
const UChar substring 
)

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.

Parameters
sThe string to search (NUL-terminated).
substringThe substring to find (NUL-terminated).
Returns
A pointer to the first occurrence of substring in s, or s itself if the substring is empty, or NULL if substring is not in s.
Stable:
ICU 2.0
See also
u_strrstr
u_strFindFirst
u_strFindLast

◆ u_strToJavaModifiedUTF8()

U_CAPI char * u_strToJavaModifiedUTF8 ( char *  dest,
int32_t  destCapacity,
int32_t *  pDestLength,
const UChar src,
int32_t  srcLength,
UErrorCode pErrorCode 
)

Convert a 16-bit Unicode string to Java Modified UTF-8.

See http://java.sun.com/javase/6/docs/api/java/io/DataInput.html#modified-utf-8

This function behaves according to the documentation for Java DataOutput.writeUTF() except that it does not encode the output length in the destination buffer and does not have an output length restriction. See http://java.sun.com/javase/6/docs/api/java/io/DataOutput.html#writeUTF(java.lang.String)

The input string need not be well-formed UTF-16. (Therefore there is no subchar parameter.)

Parameters
destA buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacityThe size of the buffer (number of chars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
pDestLengthA pointer to receive the number of units written to the destination. If pDestLength!=NULL then *pDestLength is always set to the number of output units corresponding to the transformation of all the input units, even in case of a buffer overflow.
srcThe original source string
srcLengthThe length of the original string. If -1, then src must be zero-terminated.
pErrorCodePointer to a standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)
Returns
The pointer to destination buffer.
Stable:
ICU 4.4
See also
u_strToUTF8WithSub
u_strFromJavaModifiedUTF8WithSub

◆ u_strtok_r()

U_CAPI UChar * u_strtok_r ( UChar src,
const UChar delim,
UChar **  saveState 
)

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.

Parameters
srcString containing token(s). This string will be modified. After the first call to u_strtok_r(), this argument must be NULL to get to the next token.
delimSet of delimiter characters (Unicode code points).
saveStateThe current pointer within the original string, which is set by this function. The saveState parameter should the address of a local variable of type UChar *. (i.e. defined "UChar *myLocalSaveState" and use &myLocalSaveState for this parameter).
Returns
A pointer to the next token found in src, or NULL when there are no more tokens.
Stable:
ICU 2.0

◆ u_strToLower()

U_CAPI 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.

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.

Parameters
destA buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacityThe size of the buffer (number of UChars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string.
srcThe original string
srcLengthThe length of the original string. If -1, then src must be zero-terminated.
localeThe locale to consider, or "" for the root locale or NULL for the default locale.
pErrorCodeMust be a valid pointer to an error code value, which must not indicate a failure before the function call.
Returns
The length of the result string. It may be greater than destCapacity. In that case, only some of the result was written to the destination buffer.
Stable:
ICU 2.0

◆ u_strToTitle()

U_CAPI 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.

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.

Parameters
destA buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacityThe size of the buffer (number of UChars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string.
srcThe original string
srcLengthThe length of the original string. If -1, then src must be zero-terminated.
titleIterA break iterator to find the first characters of words that are to be titlecased. If none is provided (NULL), then a standard titlecase break iterator is opened.
localeThe locale to consider, or "" for the root locale or NULL for the default locale.
pErrorCodeMust be a valid pointer to an error code value, which must not indicate a failure before the function call.
Returns
The length of the result string. It may be greater than destCapacity. In that case, only some of the result was written to the destination buffer.
Stable:
ICU 2.1

◆ u_strToUpper()

U_CAPI 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.

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.

Parameters
destA buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacityThe size of the buffer (number of UChars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string.
srcThe original string
srcLengthThe length of the original string. If -1, then src must be zero-terminated.
localeThe locale to consider, or "" for the root locale or NULL for the default locale.
pErrorCodeMust be a valid pointer to an error code value, which must not indicate a failure before the function call.
Returns
The length of the result string. It may be greater than destCapacity. In that case, only some of the result was written to the destination buffer.
Stable:
ICU 2.0

◆ u_strToUTF32()

U_CAPI UChar32 * u_strToUTF32 ( UChar32 dest,
int32_t  destCapacity,
int32_t *  pDestLength,
const UChar src,
int32_t  srcLength,
UErrorCode pErrorCode 
)

Convert a UTF-16 string to UTF-32.

If the input string is not well-formed, then the U_INVALID_CHAR_FOUND error code is set.

Parameters
destA buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacityThe size of the buffer (number of UChar32s). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
pDestLengthA pointer to receive the number of units written to the destination. If pDestLength!=NULL then *pDestLength is always set to the number of output units corresponding to the transformation of all the input units, even in case of a buffer overflow.
srcThe original source string
srcLengthThe length of the original string. If -1, then src must be zero-terminated.
pErrorCodeMust be a valid pointer to an error code value, which must not indicate a failure before the function call.
Returns
The pointer to destination buffer.
See also
u_strToUTF32WithSub
u_strFromUTF32
Stable:
ICU 2.0

◆ u_strToUTF32WithSub()

U_CAPI UChar32 * u_strToUTF32WithSub ( UChar32 dest,
int32_t  destCapacity,
int32_t *  pDestLength,
const UChar src,
int32_t  srcLength,
UChar32  subchar,
int32_t *  pNumSubstitutions,
UErrorCode pErrorCode 
)

Convert a UTF-16 string to UTF-32.

Same as u_strToUTF32() 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_strToUTF32().

Parameters
destA buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacityThe size of the buffer (number of UChar32s). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
pDestLengthA pointer to receive the number of units written to the destination. If pDestLength!=NULL then *pDestLength is always set to the number of output units corresponding to the transformation of all the input units, even in case of a buffer overflow.
srcThe original source string
srcLengthThe length of the original string. If -1, then src must be zero-terminated.
subcharThe substitution character to use in place of an illegal input sequence, or U_SENTINEL if the function is to return with U_INVALID_CHAR_FOUND instead. A substitution character can be any valid Unicode code point (up to U+10FFFF) except for surrogate code points (U+D800..U+DFFF). The recommended value is U+FFFD "REPLACEMENT CHARACTER".
pNumSubstitutionsOutput parameter receiving the number of substitutions if subchar>=0. Set to 0 if no substitutions occur or subchar<0. pNumSubstitutions can be NULL.
pErrorCodePointer to a standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)
Returns
The pointer to destination buffer.
See also
u_strToUTF32
u_strFromUTF32WithSub
Stable:
ICU 4.2

◆ u_strToUTF8()

U_CAPI char * u_strToUTF8 ( char *  dest,
int32_t  destCapacity,
int32_t *  pDestLength,
const UChar src,
int32_t  srcLength,
UErrorCode pErrorCode 
)

Convert a UTF-16 string to UTF-8.

If the input string is not well-formed, then the U_INVALID_CHAR_FOUND error code is set.

Parameters
destA buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacityThe size of the buffer (number of chars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
pDestLengthA pointer to receive the number of units written to the destination. If pDestLength!=NULL then *pDestLength is always set to the number of output units corresponding to the transformation of all the input units, even in case of a buffer overflow.
srcThe original source string
srcLengthThe length of the original string. If -1, then src must be zero-terminated.
pErrorCodeMust be a valid pointer to an error code value, which must not indicate a failure before the function call.
Returns
The pointer to destination buffer.
Stable:
ICU 2.0
See also
u_strToUTF8WithSub
u_strFromUTF8

◆ u_strToUTF8WithSub()

U_CAPI char * u_strToUTF8WithSub ( char *  dest,
int32_t  destCapacity,
int32_t *  pDestLength,
const UChar src,
int32_t  srcLength,
UChar32  subchar,
int32_t *  pNumSubstitutions,
UErrorCode pErrorCode 
)

Convert a UTF-16 string to UTF-8.

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().

Parameters
destA buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacityThe size of the buffer (number of chars). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
pDestLengthA pointer to receive the number of units written to the destination. If pDestLength!=NULL then *pDestLength is always set to the number of output units corresponding to the transformation of all the input units, even in case of a buffer overflow.
srcThe original source string
srcLengthThe length of the original string. If -1, then src must be zero-terminated.
subcharThe substitution character to use in place of an illegal input sequence, or U_SENTINEL if the function is to return with U_INVALID_CHAR_FOUND instead. A substitution character can be any valid Unicode code point (up to U+10FFFF) except for surrogate code points (U+D800..U+DFFF). The recommended value is U+FFFD "REPLACEMENT CHARACTER".
pNumSubstitutionsOutput parameter receiving the number of substitutions if subchar>=0. Set to 0 if no substitutions occur or subchar<0. pNumSubstitutions can be NULL.
pErrorCodePointer to a standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)
Returns
The pointer to destination buffer.
See also
u_strToUTF8
u_strFromUTF8WithSub
Stable:
ICU 3.6

◆ u_strToWCS()

U_CAPI wchar_t * u_strToWCS ( wchar_t *  dest,
int32_t  destCapacity,
int32_t *  pDestLength,
const UChar src,
int32_t  srcLength,
UErrorCode pErrorCode 
)

Convert a UTF-16 string to a wchar_t string.

If it is known at compile time that wchar_t strings are in UTF-16 or UTF-32, then this function simply calls the fast, dedicated function for that. Otherwise, two conversions UTF-16 -> default charset -> wchar_t* are performed.

Parameters
destA buffer for the result string. The result will be zero-terminated if the buffer is large enough.
destCapacityThe size of the buffer (number of wchar_t's). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
pDestLengthA pointer to receive the number of units written to the destination. If pDestLength!=NULL then *pDestLength is always set to the number of output units corresponding to the transformation of all the input units, even in case of a buffer overflow.
srcThe original source string
srcLengthThe length of the original string. If -1, then src must be zero-terminated.
pErrorCodeMust be a valid pointer to an error code value, which must not indicate a failure before the function call.
Returns
The pointer to destination buffer.
Stable:
ICU 2.0

◆ u_uastrcpy()

U_CAPI UChar * u_uastrcpy ( UChar dst,
const char *  src 
)

Copy a byte string encoded in the default codepage to a ustring.

Adds a null terminator. Performs a host byte to UChar conversion

Parameters
dstThe destination string.
srcThe source string.
Returns
A pointer to dst.
Stable:
ICU 2.0

◆ u_uastrncpy()

U_CAPI UChar * u_uastrncpy ( UChar dst,
const char *  src,
int32_t  n 
)

Copy a byte string encoded in the default codepage to a ustring.

Copies at most n characters. The result will be null terminated if the length of src is less than n. Performs a host byte to UChar conversion

Parameters
dstThe destination string.
srcThe source string.
nThe maximum number of characters to copy.
Returns
A pointer to dst.
Stable:
ICU 2.0

◆ u_unescape()

U_CAPI 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.

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.

Parameters
srca zero-terminated string of invariant characters
destpointer to buffer to receive converted and unescaped text and, if there is room, a zero terminator. May be NULL for preflighting, in which case no UChars will be written, but the return value will still be valid. On error, an empty string is stored here (if possible).
destCapacitythe number of UChars that may be written at dest. Ignored if dest == NULL.
Returns
the length of unescaped string.
See also
u_unescapeAt
UnicodeString::unescape()
UnicodeString::unescapeAt()
Stable:
ICU 2.0

◆ u_unescapeAt()

U_CAPI UChar32 u_unescapeAt ( UNESCAPE_CHAR_AT  charAt,
int32_t *  offset,
int32_t  length,
void *  context 
)

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.

Parameters
charAtcallback function that returns a UChar of the source text given an offset and a context pointer.
offsetpointer to the offset that will be passed to charAt. The offset value will be updated upon return to point after the last parsed character of the escape sequence. On error the offset is unchanged.
lengththe number of characters in the source text. The last character of the source text is considered to be at offset length-1.
contextan opaque pointer passed directly into charAt.
Returns
the character represented by the escape sequence at offset, or (UChar32)0xFFFFFFFF on error.
See also
u_unescape()
UnicodeString::unescape()
UnicodeString::unescapeAt()
Stable:
ICU 2.0