Constant to be used in the UnicodeString(char *, int32_t, EInvariant) constructor which constructs a Unicode string from an invariant-character char * string.

Use the macro US_INV instead of the full qualification for this value.

See also

US_INV

Stable:

ICU 3.2

Definition at line 307 of file unistr.h.

Construct an empty UnicodeString.

Stable:

ICU 2.0

Definition at line 4182 of file unistr.h.

Construct a UnicodeString with capacity to hold capacity char16_ts.

Parameters

capacity	the number of char16_ts this UnicodeString should hold before a resize is necessary; if count is greater than 0 and count code points c take up more space than capacity, then capacity is adjusted accordingly.
c	is used to initially fill the string
count	specifies how many code points c are to be written in the string

Stable:

ICU 2.0

Single char16_t (code unit) constructor.

It is recommended to mark this constructor "explicit" by -DUNISTR_FROM_CHAR_EXPLICIT=explicit on the compiler command line or similar.

Parameters

ch	the character to place in the UnicodeString

Stable:

ICU 2.0

Single UChar32 (code point) constructor.

It is recommended to mark this constructor "explicit" by -DUNISTR_FROM_CHAR_EXPLICIT=explicit on the compiler command line or similar.

Parameters

ch	the character to place in the UnicodeString

Stable:

ICU 2.0

nullptr_t constructor.

Effectively the same as the default constructor, makes an empty string object.

It is recommended to mark this constructor "explicit" by -DUNISTR_FROM_STRING_EXPLICIT=explicit on the compiler command line or similar.

Parameters

text

nullptr

Stable:

ICU 59

Definition at line 4186 of file unistr.h.

char16_t* constructor.

Note, for string literals: Since C++17 and ICU 76, you can use UTF-16 string literals with compile-time length determination:

Parameters

text	The characters to place in the UnicodeString.
textLength	The number of Unicode characters in text to copy.

Stable:

ICU 2.0

uint16_t * constructor.

Delegates to UnicodeString(const char16_t *, int32_t).

Note, for string literals: Since C++17 and ICU 76, you can use UTF-16 string literals with compile-time length determination:

Parameters

text	UTF-16 string
textLength	string length

Stable:

ICU 59

Definition at line 3225 of file unistr.h.

wchar_t * constructor.

(Only defined if U_SIZEOF_WCHAR_T==2.) Delegates to UnicodeString(const char16_t *, int32_t).

Note, for string literals: Since C++17 and ICU 76, you can use UTF-16 string literals with compile-time length determination:

Parameters

text	UTF-16 string
textLength	string length

Stable:

ICU 59

Definition at line 3247 of file unistr.h.

nullptr_t constructor.

Effectively the same as the default constructor, makes an empty string object.

Parameters

text	nullptr
textLength	ignored

Stable:

ICU 59

Definition at line 4190 of file unistr.h.

Constructor from text which is, or which is implicitly convertible to, a std::u16string_view or (if U_SIZEOF_WCHAR_T==2) std::wstring_view.

The string is bogus if the string view is too long.

If you need a UnicodeString but need not copy the string view contents, then you can call the UnicodeString::readOnlyAlias() function instead of this constructor.

Parameters

text	UTF-16 string

Draft:

This API may be changed in the future versions and was introduced in ICU 76

Definition at line 3274 of file unistr.h.

Readonly-aliasing char16_t* constructor.

The text will be used for the UnicodeString object, but it will not be released when the UnicodeString is destroyed. This has copy-on-write semantics: When the string is modified, then the buffer is first copied into newly allocated memory. The aliased buffer is never modified.

In an assignment to another UnicodeString, when using the copy constructor or the assignment operator, the text will be copied. When using fastCopyFrom(), the text will be aliased again, so that both strings then alias the same readonly-text.

Note, for string literals: Since C++17 and ICU 76, you can use UTF-16 string literals with compile-time length determination:

Parameters

isTerminated	specifies if text is NUL-terminated. This must be true if textLength==-1.
text	The characters to alias for the UnicodeString.
textLength	The number of Unicode characters in text to alias. If -1, then this constructor will determine the length by calling u_strlen().

Stable:

ICU 2.0

Writable-aliasing char16_t* constructor.

The text will be used for the UnicodeString object, but it will not be released when the UnicodeString is destroyed. This has write-through semantics: For as long as the capacity of the buffer is sufficient, write operations will directly affect the buffer. When more capacity is necessary, then a new buffer will be allocated and the contents copied as with regularly constructed strings. In an assignment to another UnicodeString, the buffer will be copied. The extract(Char16Ptr dst) function detects whether the dst pointer is the same as the string buffer itself and will in this case not copy the contents.

Parameters

buffer	The characters to alias for the UnicodeString.
buffLength	The number of Unicode characters in buffer to alias.
buffCapacity	The size of buffer in char16_ts.

Stable:

ICU 2.0

Writable-aliasing uint16_t * constructor.

Delegates to UnicodeString(const char16_t *, int32_t, int32_t).

Parameters

buffer	writable buffer of/for UTF-16 text
buffLength	length of the current buffer contents
buffCapacity	buffer capacity

Stable:

ICU 59

Definition at line 3343 of file unistr.h.

Writable-aliasing wchar_t * constructor.

(Only defined if U_SIZEOF_WCHAR_T==2.) Delegates to UnicodeString(const char16_t *, int32_t, int32_t).

Parameters

buffer	writable buffer of/for UTF-16 text
buffLength	length of the current buffer contents
buffCapacity	buffer capacity

Stable:

ICU 59

Definition at line 3357 of file unistr.h.

Writable-aliasing nullptr_t constructor.

Effectively the same as the default constructor, makes an empty string object.

Parameters

buffer	nullptr
buffLength	ignored
buffCapacity	ignored

Stable:

ICU 59

Definition at line 4194 of file unistr.h.

char* constructor.

Uses the default converter (and thus depends on the ICU conversion code) unless U_CHARSET_IS_UTF8 is set to 1.

For ASCII (really "invariant character") strings it is more efficient to use the constructor that takes a US_INV (for its enum EInvariant).

Note, for string literals: Since C++17 and ICU 76, you can use UTF-16 string literals with compile-time length determination:

It is recommended to mark this constructor "explicit" by -DUNISTR_FROM_STRING_EXPLICIT=explicit on the compiler command line or similar.

Parameters

codepageData

an array of bytes, null-terminated, in the platform's default codepage.

Stable:

ICU 2.0

char* constructor.

Uses the default converter (and thus depends on the ICU conversion code) unless U_CHARSET_IS_UTF8 is set to 1.

Parameters

codepageData	an array of bytes in the platform's default codepage.
dataLength	The number of bytes in codepageData.

Stable:

ICU 2.0

char* constructor.

Parameters

codepageData	an array of bytes, null-terminated
codepage	the encoding of codepageData. The special value 0 for codepage indicates that the text is in the platform's default codepage.

If codepage is an empty string (""), then a simple conversion is performed on the codepage-invariant subset ("invariant characters") of the platform encoding. See utypes.h. Recommendation: For invariant-character strings use the constructor UnicodeString(const char *src, int32_t length, enum EInvariant inv) because it avoids object code dependencies of UnicodeString on the conversion code.

Stable:

ICU 2.0

char* constructor.

Parameters

codepageData	an array of bytes.
dataLength	The number of bytes in codepageData.
codepage	the encoding of codepageData. The special value 0 for codepage indicates that the text is in the platform's default codepage. If codepage is an empty string (""), then a simple conversion is performed on the codepage-invariant subset ("invariant characters") of the platform encoding. See utypes.h. Recommendation: For invariant-character strings use the constructor UnicodeString(const char *src, int32_t length, enum EInvariant inv) because it avoids object code dependencies of UnicodeString on the conversion code.

Stable:

ICU 2.0

char * / UConverter constructor.

This constructor uses an existing UConverter object to convert the codepage string to Unicode and construct a UnicodeString from that.

The converter is reset at first. If the error code indicates a failure before this constructor is called, or if an error occurs during conversion or construction, then the string will be bogus.

This function avoids the overhead of opening and closing a converter if multiple strings are constructed.

Parameters

src	input codepage string
srcLength	length of the input string, can be -1 for NUL-terminated strings
cnv	converter object (ucnv_resetToUnicode() will be called), can be nullptr for the default converter
errorCode	normal ICU error code

Stable:

ICU 2.0

Constructs a Unicode string from an invariant-character char * string.

About invariant characters see utypes.h. This constructor has no runtime dependency on conversion code and is therefore recommended over ones taking a charset name string (where the empty string "" indicates invariant-character conversion).

Use the macro US_INV as the third, signature-distinguishing parameter.

For example:

Note, for string literals: Since C++17 and ICU 76, you can use UTF-16 string literals with compile-time length determination:

Parameters

src	String using only invariant characters.
textLength	Length of src, or -1 if NUL-terminated.
inv	Signature-distinguishing parameter, use US_INV.

See also

US_INV

Stable:

ICU 3.2

Copy constructor.

Starting with ICU 2.4, the assignment operator and the copy constructor allocate a new buffer and copy the buffer contents even for readonly aliases. By contrast, the fastCopyFrom() function implements the old, more efficient but less safe behavior of making this string also a readonly alias to the same buffer.

If the source object has an "open" buffer from getBuffer(minCapacity), then the copy is an empty string.

Parameters

that	The UnicodeString object to copy.

Stable:

ICU 2.0

See also

fastCopyFrom

Move constructor; might leave src in bogus state.

This string will have the same contents and state that the source string had.

Parameters

src	source string

Stable:

ICU 56

'Substring' constructor from tail of source string.

Parameters

src	The UnicodeString object to copy.
srcStart	The offset into src at which to start copying.

Stable:

ICU 2.2

'Substring' constructor from subrange of source string.

Parameters

src	The UnicodeString object to copy.
srcStart	The offset into src at which to start copying.
srcLength	The number of characters from src to copy.

Stable:

ICU 2.2

Destructor.

Stable:

ICU 2.0

Append the code unit srcChar to the UnicodeString object.

Parameters

srcChar

the code unit to append

Returns

a reference to this

Stable:

ICU 2.0

Definition at line 4981 of file unistr.h.

Append the characters in srcChars in the range [srcStart, srcStart + srcLength) to the UnicodeString object at offset start.

srcChars is not modified.

Parameters

srcChars	the source for the new characters
srcStart	the offset into srcChars where new characters will be obtained
srcLength	the number of characters in srcChars in the append string; can be -1 if srcChars is NUL-terminated

Returns

a reference to this

Stable:

ICU 2.0

Definition at line 4970 of file unistr.h.

Appends the characters in src which is, or which is implicitly convertible to, a std::u16string_view or (if U_SIZEOF_WCHAR_T==2) std::wstring_view, to the UnicodeString object.

Parameters

src	the source for the new characters

Returns

a reference to this

Draft:

This API may be changed in the future versions and was introduced in ICU 76

Definition at line 2300 of file unistr.h.

Append the characters in srcText to the UnicodeString object.

srcText is not modified.

Parameters

srcText

the source for the new characters

Returns

a reference to this

Stable:

ICU 2.0

Definition at line 4966 of file unistr.h.

References length().

Append the characters in srcText in the range [srcStart, srcStart + srcLength) to the UnicodeString object at offset start.

srcText is not modified.

Parameters

srcText	the source for the new characters
srcStart	the offset into srcText where new characters will be obtained
srcLength	the number of characters in srcText in the append string

Returns

a reference to this

Stable:

ICU 2.0

Definition at line 4960 of file unistr.h.

Referenced by icu::Transliterator::setID().

Append the characters in srcChars to the UnicodeString object.

srcChars is not modified.

Parameters

srcChars	the source for the new characters
srcLength	the number of Unicode characters in srcChars; can be -1 if srcChars is NUL-terminated

Returns

a reference to this

Stable:

ICU 2.0

Definition at line 4976 of file unistr.h.

Append the code point srcChar to the UnicodeString object.

Parameters

srcChar

the code point to append

Returns

a reference to this

Stable:

ICU 2.0

Compare two strings case-insensitively using full case folding.

This is equivalent to this->foldCase(options).compare(text.foldCase(options)).

Parameters

text	Another string to compare this one to.
options	A 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

Definition at line 4443 of file unistr.h.

References length().

Compare two strings case-insensitively using full case folding.

This is equivalent to this->foldCase(options).compare(srcChars.foldCase(options)).

Parameters

srcChars	A pointer to another string to compare this one to.
srcLength	The number of code units from that string to compare.
options	A 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

Definition at line 4456 of file unistr.h.

Compare two strings case-insensitively using full case folding.

This is equivalent to this->foldCase(options).compare(srcChars.foldCase(options)).

Parameters

start	The start offset in this string at which the compare operation begins.
length	The number of code units from this string to compare.
srcChars	A pointer to another string to compare this one to.
srcStart	The start offset in that string at which the compare operation begins.
srcLength	The number of code units from that string to compare.
options	A 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

Definition at line 4481 of file unistr.h.

Compare two strings case-insensitively using full case folding.

This is equivalent to this->foldCase(options).compare(srcChars.foldCase(options)).

Parameters

start	The start offset in this string at which the compare operation begins.
length	The number of code units from this string to compare.
srcChars	A pointer to another string to compare this one to.
options	A 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

Definition at line 4473 of file unistr.h.

Compare two strings case-insensitively using full case folding.

This is equivalent to this->foldCase(options).compare(srcText.foldCase(options)).

Parameters

start	The start offset in this string at which the compare operation begins.
length	The number of code units from this string to compare.
srcText	Another string to compare this one to.
srcStart	The start offset in that string at which the compare operation begins.
srcLength	The number of code units from that string to compare.
options	A 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

Definition at line 4463 of file unistr.h.

Compare two strings case-insensitively using full case folding.

This is equivalent to this->foldCase(options).compare(srcText.foldCase(options)).

Parameters

start	The start offset in this string at which the compare operation begins.
length	The number of code units from this string to compare.
srcText	Another string to compare this one to.
options	A 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

Definition at line 4448 of file unistr.h.

References length().

Compare two strings case-insensitively using full case folding.

This is equivalent to this->foldCase(options).compareBetween(text.foldCase(options)).

Parameters

start	The start offset in this string at which the compare operation begins.
limit	The offset after the last code unit from this string to compare.
srcText	Another string to compare this one to.
srcStart	The start offset in that string at which the compare operation begins.
srcLimit	The offset after the last code unit from that string to compare.
options	A 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

Definition at line 4491 of file unistr.h.

Return the code point that contains the code unit at offset offset.

If the offset is not valid (0..length()-1) then U+ffff is returned.

Parameters

offset

a valid offset into the text that indicates the text offset of any of the code units that will be assembled into a code point (21-bit value) and returned

Returns

the code point of text at offset or 0xffff if the offset is not valid for this string

Stable:

ICU 2.0

Referenced by icu::DecimalFormatSymbols::setSymbol().

Return the code unit at offset offset.

If the offset is not valid (0..length()-1) then U+ffff is returned.

Parameters

offset

a valid offset into the text

Returns

the code unit at offset offset or 0xffff if the offset is not valid for this string

Stable:

ICU 2.0

Definition at line 4855 of file unistr.h.

Clone this object, an instance of a subclass of Replaceable.

Clones can be used concurrently in multiple threads. If a subclass does not implement clone(), or if an error occurs, then nullptr is returned. The caller must delete the clone.

Returns

a clone of this object

See also

Replaceable::clone

getDynamicClassID

Stable:

ICU 2.6

Reimplemented from icu::Replaceable.

Compare the characters bitwise in this UnicodeString to the characters in text.

Parameters

text	The UnicodeString to compare to this one.

Returns

The result of bitwise character comparison: 0 if this contains the same characters as text, -1 if the characters in this are bitwise less than the characters in text, +1 if the characters in this are bitwise greater than the characters in text.

Stable:

ICU 2.0

Definition at line 4320 of file unistr.h.

References length().

Compare the characters bitwise in this UnicodeString with the first srcLength characters in srcChars.

Parameters

srcChars	The characters to compare to this UnicodeString.
srcLength	the number of characters in srcChars to compare

Returns

The result of bitwise character comparison: 0 if this contains the same characters as srcChars, -1 if the characters in this are bitwise less than the characters in srcChars, +1 if the characters in this are bitwise greater than the characters in srcChars.

Stable:

ICU 2.0

Definition at line 4330 of file unistr.h.

Compare the characters bitwise in the range [start, start + length) with the first length characters in srcChars

Parameters

start	the offset at which the compare operation begins
length	the number of characters to compare.
srcChars	the characters to be compared

Returns

The result of bitwise character comparison: 0 if this contains the same characters as srcChars, -1 if the characters in this are bitwise less than the characters in srcChars, +1 if the characters in this are bitwise greater than the characters in srcChars.

Stable:

ICU 2.0

Definition at line 4343 of file unistr.h.

Compare the characters bitwise in the range [start, start + length) with the characters in srcChars in the range [srcStart, srcStart + srcLength).

Parameters

start	the offset at which the compare operation begins
length	the number of characters in this to compare
srcChars	the characters to be compared
srcStart	the offset into srcChars to start comparison
srcLength	the number of characters in srcChars to compare

Returns

The result of bitwise character comparison: 0 if this contains the same characters as srcChars, -1 if the characters in this are bitwise less than the characters in srcChars, +1 if the characters in this are bitwise greater than the characters in srcChars.

Stable:

ICU 2.0

Definition at line 4349 of file unistr.h.

Compare the characters bitwise in the range [start, start + length) with the characters in srcText in the range [srcStart, srcStart + srcLength).

Parameters

start	the offset at which the compare operation begins
length	the number of characters in this to compare.
srcText	the text to be compared
srcStart	the offset into srcText to start comparison
srcLength	the number of characters in src to compare

Returns

The result of bitwise character comparison: 0 if this contains the same characters as srcText, -1 if the characters in this are bitwise less than the characters in srcText, +1 if the characters in this are bitwise greater than the characters in srcText.

Stable:

ICU 2.0

Definition at line 4335 of file unistr.h.

Compare the characters bitwise in the range [start, start + length) with the characters in the entire string text.

(The parameters "start" and "length" are not applied to the other text "text".)

Parameters

start	the offset at which the compare operation begins
length	the number of characters of text to compare.
text	the other text to be compared against this string.

Returns

The result of bitwise character comparison: 0 if this contains the same characters as text, -1 if the characters in this are bitwise less than the characters in text, +1 if the characters in this are bitwise greater than the characters in text.

Stable:

ICU 2.0

Definition at line 4324 of file unistr.h.

References length().

Compare the characters bitwise in the range [start, limit) with the characters in srcText in the range [srcStart, srcLimit).

Parameters

start	the offset at which the compare operation begins
limit	the offset immediately following the compare operation
srcText	the text to be compared
srcStart	the offset into srcText to start comparison
srcLimit	the offset into srcText to limit comparison

Returns

The result of bitwise character comparison: 0 if this contains the same characters as srcText, -1 if the characters in this are bitwise less than the characters in srcText, +1 if the characters in this are bitwise greater than the characters in srcText.

Stable:

ICU 2.0

Definition at line 4357 of file unistr.h.

Compare two Unicode strings in code point order.

The result may be different from the results of compare(), operator<, etc. if supplementary characters are present:

In UTF-16, supplementary characters (with code points U+10000 and above) are stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff, which means that they compare as less than some other BMP characters like U+feff. This function compares Unicode strings in code point order. If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined.

Parameters

text	Another string to compare this one to.

Returns

a negative/zero/positive integer corresponding to whether this string is less than/equal to/greater than the second one in code point order

Stable:

ICU 2.0

Definition at line 4381 of file unistr.h.

References length().

Compare two Unicode strings in code point order.

The result may be different from the results of compare(), operator<, etc. if supplementary characters are present:

In UTF-16, supplementary characters (with code points U+10000 and above) are stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff, which means that they compare as less than some other BMP characters like U+feff. This function compares Unicode strings in code point order. If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined.

Parameters

srcChars	A pointer to another string to compare this one to.
srcLength	The number of code units from that string to compare.

Returns

a negative/zero/positive integer corresponding to whether this string is less than/equal to/greater than the second one in code point order

Stable:

ICU 2.0

Definition at line 4391 of file unistr.h.

Compare two Unicode strings in code point order.

The result may be different from the results of compare(), operator<, etc. if supplementary characters are present:

In UTF-16, supplementary characters (with code points U+10000 and above) are stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff, which means that they compare as less than some other BMP characters like U+feff. This function compares Unicode strings in code point order. If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined.

Parameters

start	The start offset in this string at which the compare operation begins.
length	The number of code units from this string to compare.
srcChars	A pointer to another string to compare this one to.

Returns

a negative/zero/positive integer corresponding to whether this string is less than/equal to/greater than the second one in code point order

Stable:

ICU 2.0

Definition at line 4404 of file unistr.h.

Compare two Unicode strings in code point order.

The result may be different from the results of compare(), operator<, etc. if supplementary characters are present:

In UTF-16, supplementary characters (with code points U+10000 and above) are stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff, which means that they compare as less than some other BMP characters like U+feff. This function compares Unicode strings in code point order. If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined.

Parameters

start	The start offset in this string at which the compare operation begins.
length	The number of code units from this string to compare.
srcChars	A pointer to another string to compare this one to.
srcStart	The start offset in that string at which the compare operation begins.
srcLength	The number of code units from that string to compare.

Returns

a negative/zero/positive integer corresponding to whether this string is less than/equal to/greater than the second one in code point order

Stable:

ICU 2.0

Definition at line 4410 of file unistr.h.

Compare two Unicode strings in code point order.

The result may be different from the results of compare(), operator<, etc. if supplementary characters are present:

In UTF-16, supplementary characters (with code points U+10000 and above) are stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff, which means that they compare as less than some other BMP characters like U+feff. This function compares Unicode strings in code point order. If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined.

Parameters

start	The start offset in this string at which the compare operation begins.
length	The number of code units from this string to compare.
srcText	Another string to compare this one to.

Returns

a negative/zero/positive integer corresponding to whether this string is less than/equal to/greater than the second one in code point order

Stable:

ICU 2.0

Definition at line 4385 of file unistr.h.

References length().

Compare two Unicode strings in code point order.

The result may be different from the results of compare(), operator<, etc. if supplementary characters are present:

In UTF-16, supplementary characters (with code points U+10000 and above) are stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff, which means that they compare as less than some other BMP characters like U+feff. This function compares Unicode strings in code point order. If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined.

Parameters

start	The start offset in this string at which the compare operation begins.
length	The number of code units from this string to compare.
srcText	Another string to compare this one to.
srcStart	The start offset in that string at which the compare operation begins.
srcLength	The number of code units from that string to compare.

Returns

a negative/zero/positive integer corresponding to whether this string is less than/equal to/greater than the second one in code point order

Stable:

ICU 2.0

Definition at line 4396 of file unistr.h.

Compare two Unicode strings in code point order.

The result may be different from the results of compare(), operator<, etc. if supplementary characters are present:

In UTF-16, supplementary characters (with code points U+10000 and above) are stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff, which means that they compare as less than some other BMP characters like U+feff. This function compares Unicode strings in code point order. If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined.

Parameters

start	The start offset in this string at which the compare operation begins.
limit	The offset after the last code unit from this string to compare.
srcText	Another string to compare this one to.
srcStart	The start offset in that string at which the compare operation begins.
srcLimit	The offset after the last code unit from that string to compare.

Returns

a negative/zero/positive integer corresponding to whether this string is less than/equal to/greater than the second one in code point order

Stable:

ICU 2.0

Definition at line 4418 of file unistr.h.

Copy a substring of this object, retaining attribute (out-of-band) information.

This method is used to duplicate or reorder substrings. The destination index must not overlap the source range.

Parameters

start	the beginning index, inclusive; 0 <= start <= limit.
limit	the ending index, exclusive; start <= limit <= length().
dest	the destination index. The characters from start..limit-1 will be copied to dest. Implementations of this method may assume that dest <= start || dest >= limit.

Stable:

ICU 2.0

Implements icu::Replaceable.

Count Unicode code points in the length char16_t code units of the string.

A code point may occupy either one or two char16_t code units. Counting code points involves reading all code units.

This functions is basically the inverse of moveIndex32().

Parameters

start	the index of the first code unit to check
length	the number of char16_t code units to check

Returns

the number of code points in the specified code units

See also

length

Stable:

ICU 2.0

Referenced by icu::DecimalFormatSymbols::setSymbol().

Determine if this ends with the characters in srcChars in the range [srcStart, srcStart + srcLength).

Parameters

srcChars	The characters to match.
srcStart	the offset into srcText to start matching
srcLength	the number of characters in srcChars to match

Returns

true if this ends with the characters in srcChars, false otherwise

Stable:

ICU 2.0

Definition at line 4716 of file unistr.h.

References u_strlen().

Determine if this ends with the characters in srcText in the range [srcStart, srcStart + srcLength).

Parameters

srcText	The text to match.
srcStart	the offset into srcText to start matching
srcLength	the number of characters in srcText to match

Returns

true if this ends with the characters in text, false otherwise

Stable:

ICU 2.0

Definition at line 4698 of file unistr.h.

Determine if this ends with the characters in text

Parameters

text	The text to match.

Returns

true if this ends with the characters in text, false otherwise

Stable:

ICU 2.0

Definition at line 4693 of file unistr.h.

References length().

Determine if this ends with the characters in srcChars

Parameters

srcChars	The characters to match.
srcLength	the number of characters in srcChars

Returns

true if this ends with the characters in srcChars, false otherwise

Stable:

ICU 2.0

Definition at line 4707 of file unistr.h.

References u_strlen().

Convert the UnicodeString into a codepage string using an existing UConverter.

The output string is NUL-terminated if possible.

This function avoids the overhead of opening and closing a converter if multiple strings are extracted.

Parameters

dest	destination string buffer, can be nullptr if destCapacity==0
destCapacity	the number of chars available at dest
cnv	the converter object to be used (ucnv_resetFromUnicode() will be called), or nullptr for the default converter
errorCode	normal ICU error code

Returns

the length of the output string, not counting the terminating NUL; if the length is greater than destCapacity, then the string will not fit and a buffer of the indicated length would need to be passed in

Stable:

ICU 2.0

Copy the contents of the string into dest.

This is a convenience function that checks if there is enough space in dest, extracts the entire string if possible, and NUL-terminates dest if possible.

If the string fits into dest but cannot be NUL-terminated (length()==destCapacity) then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the string itself does not fit into dest (length()>destCapacity) then the error code is set to U_BUFFER_OVERFLOW_ERROR.

If the string aliases to dest itself as an external buffer, then extract() will not copy the contents.

Parameters

dest	Destination string buffer.
destCapacity	Number of char16_ts available at dest.
errorCode	ICU error code.

Returns

length()

Stable:

ICU 2.0

Copy the characters in the range [start, start + length) into the array dst, beginning at dstStart.

If the string aliases to dst itself as an external buffer, then extract() will not copy the contents.

Parameters

start	offset of first character which will be copied into the array
length	the number of characters to extract
dst	array in which to copy characters. The length of dst must be at least (dstStart + length).
dstStart	the offset in dst where the first character will be extracted

Stable:

ICU 2.0

Definition at line 4802 of file unistr.h.