class UnicodeString

Equality operator. Performs only bitwise comparison with `text`

which is, or which is implicitly convertible to,

a std::u16string_view or (if U_SIZEOF_WCHAR_T==2) std::wstring_view.

For performance, you can use UTF-16 string literals with compile-time

length determination:

Parameters

Returns

true if `text` contains the same characters as this one, false otherwise.

ICU 76

                                        
                                             UnicodeString str = ...;
                                             if (str == u"literal") { ... }
                                        
                                    

Inequality operator. Performs only bitwise comparison with `text`

which is, or which is implicitly convertible to,

a std::u16string_view or (if U_SIZEOF_WCHAR_T==2) std::wstring_view.

For performance, you can use std::u16string_view literals with compile-time

length determination:

Parameters

Returns

false if `text` contains the same characters as this one, true otherwise.

ICU 76

                                        
                                             #include <string_view>
                                             using namespace std::string_view_literals;
                                             UnicodeString str = ...;
                                             if (str != u"literal"sv) { ... }
                                        
                                    

Convert the UnicodeString to UTF-8 and append the result

to a standard string.

Unpaired surrogates are replaced with U+FFFD.

Calls toUTF8().

Parameters

Returns

The string object.

ICU 4.2

Assignment operator. Replaces the characters in this UnicodeString

with a copy of the characters from the `src`

which is, or which is implicitly convertible to,

a std::u16string_view or (if U_SIZEOF_WCHAR_T==2) std::wstring_view.

Parameters

Returns

a reference to this

ICU 76

Append operator. 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

Returns

a reference to this

ICU 76

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

Returns

a reference to this

ICU 76

Converts to a std::u16string_view.

Returns

a string view of the contents of this string

ICU 76

uint16_t * constructor.

Delegates to UnicodeString(const char16_t *).

It is recommended to mark this constructor "explicit" by

`-DUNISTR_FROM_STRING_EXPLICIT=explicit`

on the compiler command line or similar.

Note, for string literals:

Since C++17 and ICU 76, you can use UTF-16 string literals with compile-time

length determination:

Parameters

                                        
                                             UnicodeString str(u"literal");
                                             if (str == u"other literal") { ... }
                                        
                                    

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

                                        
                                             UnicodeString str(u"literal");
                                             if (str == u"other literal") { ... }
                                        
                                    

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

Writable-aliasing uint16_t * constructor.

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

Parameters

Readonly-aliasing factory method.

Aliases the same buffer as the input `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.

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.

Parameters

Readonly-aliasing factory method.

Aliases the same buffer as the input `text`.

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.

Parameters

Equality operator. Performs only bitwise comparison.

Parameters

Returns

true if `text` contains the same characters as this one,

false otherwise.

ICU 2.0

Inequality operator. Performs only bitwise comparison.

Parameters

Returns

false if `text` contains the same characters as this one,

true otherwise.

ICU 2.0

Greater than operator. Performs only bitwise comparison.

Parameters

Returns

true if the characters in this are bitwise

greater than the characters in `text`, false otherwise

ICU 2.0

Less than operator. Performs only bitwise comparison.

Parameters

Returns

true if the characters in this are bitwise

less than the characters in `text`, false otherwise

ICU 2.0

Greater than or equal operator. Performs only bitwise comparison.

Parameters

Returns

true if the characters in this are bitwise

greater than or equal to the characters in `text`, false otherwise

ICU 2.0

Less than or equal operator. Performs only bitwise comparison.

Parameters

Returns

true if the characters in this are bitwise

less than or equal to the characters in `text`, false otherwise

ICU 2.0

Compare the characters bitwise in this UnicodeString to

the characters in `text`.

Parameters

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

ICU 2.0

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

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

ICU 2.0

Compare the characters bitwise in the range

[`start`, `start + length`) with the characters

in `srcText` in the range

[`srcStart`, `srcStart + srcLength`).

Parameters

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

ICU 2.0

Compare the characters bitwise in this UnicodeString with the first

`srcLength` characters in `srcChars`.

Parameters

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

ICU 2.0

Compare the characters bitwise in the range

[`start`, `start + length`) with the first

`length` characters in `srcChars`

Parameters

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

ICU 2.0

Compare the characters bitwise in the range

[`start`, `start + length`) with the characters

in `srcChars` in the range

[`srcStart`, `srcStart + srcLength`).

Parameters

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

ICU 2.0

Compare the characters bitwise in the range

[`start`, `limit`) with the characters

in `srcText` in the range

[`srcStart`, `srcLimit`).

Parameters

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

ICU 2.0

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

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

ICU 2.0

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

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

ICU 2.0

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

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

ICU 2.0

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

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

ICU 2.0

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

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

ICU 2.0

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

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

ICU 2.0

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

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

ICU 2.0

Compare two strings case-insensitively using full case folding.

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

- 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

Parameters

Returns

A negative, zero, or positive integer indicating the comparison result.

ICU 2.0

Compare two strings case-insensitively using full case folding.

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

- 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

Parameters

Returns

A negative, zero, or positive integer indicating the comparison result.

ICU 2.0

Compare two strings case-insensitively using full case folding.

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

- 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

Parameters

Returns

A negative, zero, or positive integer indicating the comparison result.

ICU 2.0

Compare two strings case-insensitively using full case folding.

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

- 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

Parameters

Returns

A negative, zero, or positive integer indicating the comparison result.

ICU 2.0

Compare two strings case-insensitively using full case folding.

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

- 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

Parameters

Returns

A negative, zero, or positive integer indicating the comparison result.

ICU 2.0

Compare two strings case-insensitively using full case folding.

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

- 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

Parameters

Returns

A negative, zero, or positive integer indicating the comparison result.

ICU 2.0

Compare two strings case-insensitively using full case folding.

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

- 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

Parameters

Returns

A negative, zero, or positive integer indicating the comparison result.

ICU 2.0

Determine if this starts with the characters in `text`

Parameters

Returns

true if this starts with the characters in `text`,

false otherwise

ICU 2.0

Determine if this starts with the characters in `srcText`

in the range [`srcStart`, `srcStart + srcLength`).

Parameters

Returns

true if this starts with the characters in `text`,

false otherwise

ICU 2.0

Determine if this starts with the characters in `srcChars`

Parameters

Returns

true if this starts with the characters in `srcChars`,

false otherwise

ICU 2.0

Determine if this ends with the characters in `srcChars`

in the range [`srcStart`, `srcStart + srcLength`).

Parameters

Returns

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

ICU 2.0

Determine if this ends with the characters in `text`

Parameters

Returns

true if this ends with the characters in `text`,

false otherwise

ICU 2.0

Determine if this ends with the characters in `srcText`

in the range [`srcStart`, `srcStart + srcLength`).

Parameters

Returns

true if this ends with the characters in `text`,

false otherwise

ICU 2.0

Determine if this ends with the characters in `srcChars`

Parameters

Returns

true if this ends with the characters in `srcChars`,

false otherwise

ICU 2.0

Determine if this ends with the characters in `srcChars`

in the range [`srcStart`, `srcStart + srcLength`).

Parameters

Returns

true if this ends with the characters in `srcChars`,

false otherwise

ICU 2.0

Locate in this the first occurrence of the characters in `text`,

using bitwise comparison.

Parameters

Returns

The offset into this of the start of `text`,

or -1 if not found.

ICU 2.0

Locate in this the first occurrence of the characters in `text`

starting at offset `start`, using bitwise comparison.

Parameters

Returns

The offset into this of the start of `text`,

or -1 if not found.

ICU 2.0

Locate in this the first occurrence in the range

[`start`, `start + length`) of the characters

in `text`, using bitwise comparison.

Parameters

Returns

The offset into this of the start of `text`,

or -1 if not found.

ICU 2.0

Locate in this the first occurrence in the range

[`start`, `start + length`) of the characters

in `srcText` in the range

[`srcStart`, `srcStart + srcLength`),

using bitwise comparison.

Parameters

Returns

The offset into this of the start of `text`,

or -1 if not found.

ICU 2.0

Locate in this the first occurrence of the characters in

`srcChars`

starting at offset `start`, using bitwise comparison.

Parameters

Returns

The offset into this of the start of `text`,

or -1 if not found.

ICU 2.0

Locate in this the first occurrence in the range

[`start`, `start + length`) of the characters

in `srcChars`, using bitwise comparison.

Parameters

Returns

The offset into this of the start of `srcChars`,

or -1 if not found.

ICU 2.0

Locate in this the first occurrence in the range

[`start`, `start + length`) of the characters

in `srcChars` in the range

[`srcStart`, `srcStart + srcLength`),

using bitwise comparison.

Parameters

Returns

The offset into this of the start of `text`,

or -1 if not found.

ICU 2.0

Locate in this the first occurrence of the BMP code point `c`,

using bitwise comparison.

Parameters

Returns

The offset into this of `c`, or -1 if not found.

ICU 2.0

Locate in this the first occurrence of the code point `c`,

using bitwise comparison.

Parameters

Returns

The offset into this of `c`, or -1 if not found.

ICU 2.0

Locate in this the first occurrence of the BMP code point `c`,

starting at offset `start`, using bitwise comparison.

Parameters

Returns

The offset into this of `c`, or -1 if not found.

ICU 2.0

Locate in this the first occurrence of the code point `c`

starting at offset `start`, using bitwise comparison.

Parameters

Returns

The offset into this of `c`, or -1 if not found.

ICU 2.0

Locate in this the first occurrence of the BMP code point `c`

in the range [`start`, `start + length`),

using bitwise comparison.

Parameters

Returns

The offset into this of `c`, or -1 if not found.

ICU 2.0

Locate in this the first occurrence of the code point `c`

in the range [`start`, `start + length`),

using bitwise comparison.

Parameters

Returns

The offset into this of `c`, or -1 if not found.

ICU 2.0

Locate in this the last occurrence of the characters in `text`,

using bitwise comparison.

Parameters

Returns

The offset into this of the start of `text`,

or -1 if not found.

ICU 2.0

Locate in this the last occurrence of the characters in `text`

starting at offset `start`, using bitwise comparison.

Parameters

Returns

The offset into this of the start of `text`,

or -1 if not found.

ICU 2.0

Locate in this the last occurrence in the range

[`start`, `start + length`) of the characters

in `text`, using bitwise comparison.

Parameters

Returns

The offset into this of the start of `text`,

or -1 if not found.

ICU 2.0

Locate in this the last occurrence in the range

[`start`, `start + length`) of the characters

in `srcText` in the range

[`srcStart`, `srcStart + srcLength`),

using bitwise comparison.

Parameters

Returns

The offset into this of the start of `text`,

or -1 if not found.

ICU 2.0

Locate in this the last occurrence of the characters in `srcChars`

starting at offset `start`, using bitwise comparison.

Parameters

Returns

The offset into this of the start of `text`,

or -1 if not found.

ICU 2.0

Locate in this the last occurrence in the range

[`start`, `start + length`) of the characters

in `srcChars`, using bitwise comparison.

Parameters

Returns

The offset into this of the start of `srcChars`,

or -1 if not found.

ICU 2.0

Locate in this the last occurrence in the range

[`start`, `start + length`) of the characters

in `srcChars` in the range

[`srcStart`, `srcStart + srcLength`),

using bitwise comparison.

Parameters

Returns

The offset into this of the start of `text`,

or -1 if not found.

ICU 2.0

Locate in this the last occurrence of the BMP code point `c`,

using bitwise comparison.

Parameters

Returns

The offset into this of `c`, or -1 if not found.

ICU 2.0

Locate in this the last occurrence of the code point `c`,

using bitwise comparison.

Parameters

Returns

The offset into this of `c`, or -1 if not found.

ICU 2.0

Locate in this the last occurrence of the BMP code point `c`

starting at offset `start`, using bitwise comparison.

Parameters

Returns

The offset into this of `c`, or -1 if not found.

ICU 2.0

Locate in this the last occurrence of the code point `c`

starting at offset `start`, using bitwise comparison.

Parameters

Returns

The offset into this of `c`, or -1 if not found.

ICU 2.0

Locate in this the last occurrence of the BMP code point `c`

in the range [`start`, `start + length`),

using bitwise comparison.

Parameters

Returns

The offset into this of `c`, or -1 if not found.

ICU 2.0

Locate in this the last occurrence of the code point `c`

in the range [`start`, `start + length`),

using bitwise comparison.

Parameters

Returns

The offset into this of `c`, or -1 if not found.

ICU 2.0

Return the code unit at offset `offset`.

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

Parameters

Returns

the code unit at offset `offset`

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

ICU 2.0

Return the code unit at offset `offset`.

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

Parameters

Returns

the code unit at offset `offset`

ICU 2.0

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

Returns

the code point of text at `offset`

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

ICU 2.0

Adjust a random-access offset so that

it points to the beginning of a Unicode character.

The offset that is passed in points to

any code unit of a code point,

while the returned offset will point to the first code unit

of the same code point.

In UTF-16, if the input offset points to a second surrogate

of a surrogate pair, then the returned offset will point

to the first surrogate.

Parameters

Returns

offset of the first code unit of the same code point

Adjust a random-access offset so that

it points behind a Unicode character.

The offset that is passed in points behind

any code unit of a code point,

while the returned offset will point behind the last code unit

of the same code point.

In UTF-16, if the input offset points behind the first surrogate

(i.e., to the second surrogate)

of a surrogate pair, then the returned offset will point

behind the second surrogate (i.e., to the first surrogate).

Parameters

Returns

offset of the first code unit after the same code point

Move the code unit index along the string by delta code points.

Interpret the input index as a code unit-based offset into the string,

move the index forward or backward by delta code points, and

return the resulting index.

The input index should point to the first code unit of a code point,

if there is more than one.

Both input and output indexes are code unit-based as for all

string indexes/offsets in ICU (and other libraries, like MBCS char*).

If delta

<

0 then the index is moved backward (toward the start of the string).

If delta>0 then the index is moved forward (toward the end of the string).

This behaves like CharacterIterator::move32(delta, kCurrent).

Behavior for out-of-bounds indexes:

`moveIndex32` pins the input index to 0..length(), i.e.,

if the input index

<

0 then it is pinned to 0;

if it is index>length() then it is pinned to length().

Afterwards, the index is moved by `delta` code points

forward or backward,

but no further backward than to 0 and no further forward than to length().

The resulting index return value will be in between 0 and length(), inclusively.

Examples:

Parameters

Returns

the resulting code unit index

ICU 2.0

                                        
                                                 // s has code points 'a' U+10000 'b' U+10ffff U+2029
                                                 UnicodeString s(u"a\U00010000b\U0010ffff\u2029");
                                            
                                                 // initial index: position of U+10000
                                                 int32_t index=1;
                                            
                                                 // the following examples will all result in index==4, position of U+10ffff
                                            
                                                 // skip 2 code points from some position in the string
                                                 index=s.moveIndex32(index, 2); // skips U+10000 and 'b'
                                            
                                                 // go to the 3rd code point from the start of s (0-based)
                                                 index=s.moveIndex32(0, 3); // skips 'a', U+10000, and 'b'
                                            
                                                 // go to the next-to-last code point of s
                                                 index=s.moveIndex32(s.length(), -2); // backward-skips U+2029 and U+10ffff
                                        
                                    

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

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

Returns

length()

ICU 2.0

Copy the characters in the range

[`start`, `start + length`) into the UnicodeString

`target`.

Parameters

Copy the characters in the range [`start`, `limit`)

into the array `dst`, beginning at `dstStart`.

Parameters

Copy the characters in the range [`start`, `limit`)

into the UnicodeString `target`. Replaceable API.

Parameters

Copy the characters in the range

[`start`, `start + startLength`) into an array of characters.

All characters must be invariant (see utypes.h).

Use US_INV as the last, signature-distinguishing parameter.

This function does not write any more than `targetCapacity`

characters but returns the length of the entire output string

so that one can allocate a larger buffer and call the function again

if necessary.

The output string is NUL-terminated if possible.

Parameters

Returns

the output string length, not including the terminating NUL

ICU 3.2

Copy the characters in the range

[`start`, `start + length`) into an array of characters

in the platform's default codepage.

This function does not write any more than `targetLength`

characters but returns the length of the entire output string

so that one can allocate a larger buffer and call the function again

if necessary.

The output string is NUL-terminated if possible.

Parameters

Returns

the output string length, not including the terminating NUL

ICU 2.0

Copy the characters in the range

[`start`, `start + length`) into an array of characters

in a specified codepage.

The output string is NUL-terminated.

Recommendation: For invariant-character strings use

extract(int32_t start, int32_t length, char *target, int32_t targetCapacity, enum EInvariant inv) const

because it avoids object code dependencies of UnicodeString on

the conversion code.

Parameters

Returns

the output string length, not including the terminating NUL

ICU 2.0

Copy the characters in the range

[`start`, `start + length`) into an array of characters

in a specified codepage.

This function does not write any more than `targetLength`

characters but returns the length of the entire output string

so that one can allocate a larger buffer and call the function again

if necessary.

The output string is NUL-terminated if possible.

Recommendation: For invariant-character strings use

extract(int32_t start, int32_t length, char *target, int32_t targetCapacity, enum EInvariant inv) const

because it avoids object code dependencies of UnicodeString on

the conversion code.

Parameters

Returns

the output string length, not including the terminating NUL

ICU 2.0

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

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

ICU 2.0

Create a temporary substring for the specified range.

Unlike the substring constructor and setTo() functions,

the object returned here will be a read-only alias (using getBuffer())

rather than copying the text.

As a result, this substring operation is much faster but requires

that the original string not be modified or deleted during the lifetime

of the returned substring object.

Parameters

Returns

a read-only alias UnicodeString object for the substring

ICU 4.4

Create a temporary substring for the specified range.

Same as tempSubString(start, length) except that the substring range

is specified as a (start, limit) pair (with an exclusive limit index)

rather than a (start, length) pair.

Parameters

Returns

a read-only alias UnicodeString object for the substring

ICU 4.4

Convert the UnicodeString to UTF-8 and write the result

to a ByteSink. This is called by toUTF8String().

Unpaired surrogates are replaced with U+FFFD.

Calls u_strToUTF8WithSub().

Parameters

Convert the UnicodeString to UTF-32.

Unpaired surrogates are replaced with U+FFFD.

Calls u_strToUTF32WithSub().

Parameters

Returns

The length of the UTF-32 string.

Return the length of the UnicodeString object.

The length is the number of char16_t code units are in the UnicodeString.

If you want the number of code points, please use countChar32().

Returns

the length of the UnicodeString object

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

Returns

the number of code points in the specified code units

Check if the length char16_t code units of the string

contain more Unicode code points than a certain number.

This is more efficient than counting all code points in this part of the string

and comparing that number with a threshold.

This function may not need to scan the string at all if the length

falls within a certain range, and

never needs to count more than 'number+1' code points.

Logically equivalent to (countChar32(start, length)>number).

A Unicode code point may occupy either one or two char16_t code units.

Parameters

Returns

Boolean value for whether the string contains more Unicode code points

than 'number'. Same as (u_countChar32(s, length)>number).

Determine if this string is empty.

Returns

true if this string contains 0 characters, false otherwise.

ICU 2.0

Return the capacity of the internal buffer of the UnicodeString object.

This is useful together with the getBuffer functions.

See there for details.

Returns

the number of char16_ts available in the internal buffer

Generate a hash code for this object.

Returns

The hash code of this UnicodeString.

ICU 2.0

Determine if this object contains a valid string.

A bogus string has no value. It is different from an empty string,

although in both cases isEmpty() returns true and length() returns 0.

setToBogus() and isBogus() can be used to indicate that no string value is available.

For a bogus string, getBuffer() and getTerminatedBuffer() return nullptr, and

length() returns 0.

Returns

true if the string is bogus/invalid, false otherwise

Assignment operator. Replace the characters in this UnicodeString

with the characters from `srcText`.

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

Returns

a reference to this

ICU 2.0

Almost the same as the assignment operator.

Replace the characters in this UnicodeString

with the characters from `srcText`.

This function works the same as the assignment operator

for all strings except for ones that are readonly aliases.

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.

This function implements the old, more efficient but less safe behavior

of making this string also a readonly alias to the same buffer.

The fastCopyFrom function must be used only if it is known that the lifetime of

this UnicodeString does not exceed the lifetime of the aliased buffer

including its contents, for example for strings from resource bundles

or aliases to string constants.

If the source object has an "open" buffer from getBuffer(minCapacity),

then the copy is an empty string.

Parameters

Returns

a reference to this

ICU 2.4

Move assignment operator; might leave src in bogus state.

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

The behavior is undefined if *this and src are the same object.

Parameters

Returns

*this

ICU 56

Swap strings.

Parameters

Assignment operator. Replace the characters in this UnicodeString

with the code unit `ch`.

Parameters

Returns

a reference to this

ICU 2.0

Assignment operator. Replace the characters in this UnicodeString

with the code point `ch`.

Parameters

Returns

a reference to this

ICU 2.0

Set the text in the UnicodeString object to the characters

in `srcText` in the range

[`srcStart`, `srcText.length()`).

`srcText` is not modified.

Parameters

Returns

a reference to this

ICU 2.2

Set the text in the UnicodeString object to the characters

in `srcText` in the range

[`srcStart`, `srcStart + srcLength`).

`srcText` is not modified.

Parameters

Returns

a reference to this

ICU 2.0

Set the text in the UnicodeString object to the characters in

`srcText`.

`srcText` is not modified.

Parameters

Returns

a reference to this

ICU 2.0

Set the characters in the UnicodeString object to the characters

in `srcChars`. `srcChars` is not modified.

Parameters

Returns

a reference to this

ICU 2.0

Set the characters in the UnicodeString object to the code unit

`srcChar`.

Parameters

Returns

a reference to this

ICU 2.0

Set the characters in the UnicodeString object to the code point

`srcChar`.

Parameters

Returns

a reference to this

ICU 2.0

Aliasing setTo() function, analogous to the 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.

Parameters

Returns

a reference to this

ICU 2.0

Aliasing setTo() function, analogous to the 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

Returns

a reference to this

ICU 2.0

Make this UnicodeString object invalid.

The string will test true with isBogus().

A bogus string has no value. It is different from an empty string.

It can be used to indicate that no string value is available.

getBuffer() and getTerminatedBuffer() return nullptr, and

length() returns 0.

This utility function is used throughout the UnicodeString

implementation to indicate that a UnicodeString operation failed,

and may be used in other functions,

especially but not exclusively when such functions do not

take a UErrorCode for simplicity.

The following methods, and no others, will clear a string object's bogus flag:

- remove()

- remove(0, INT32_MAX)

- truncate(0)

- operator=() (assignment operator)

- setTo(...)

The simplest ways to turn a bogus string into an empty one

is to use the remove() function.

Examples for other functions that are equivalent to "set to empty string":

                                        
                                             if(s.isBogus()) {
                                               s.remove();           // set to an empty string (remove all), or
                                               s.remove(0, INT32_MAX); // set to an empty string (remove all), or
                                               s.truncate(0);        // set to an empty string (complete truncation), or
                                               s=UnicodeString();    // assign an empty string, or
                                               s.setTo((UChar32)-1); // set to a pseudo code point that is out of range, or
                                               s.setTo(u"", 0);      // set to an empty C Unicode string
                                             }
                                        
                                    

Set the character at the specified offset to the specified character.

Parameters

Returns

A reference to this

ICU 2.0

Append operator. Append the code unit `ch` to the UnicodeString

object.

Parameters

Returns

a reference to this

ICU 2.0

Append operator. Append the code point `ch` to the UnicodeString

object.

Parameters

Returns

a reference to this

ICU 2.0

Append operator. Append the characters in `srcText` to the

UnicodeString object. `srcText` is not modified.

Parameters

Returns

a reference to this

ICU 2.0

Append the characters

in `srcText` in the range

[`srcStart`, `srcStart + srcLength`) to the

UnicodeString object at offset `start`. `srcText`

is not modified.

Parameters

Returns

a reference to this

ICU 2.0

Append the characters in `srcText` to the UnicodeString object.

`srcText` is not modified.

Parameters

Returns

a reference to this

ICU 2.0

Append the characters in `srcChars` in the range

[`srcStart`, `srcStart + srcLength`) to the UnicodeString

object at offset

`start`. `srcChars` is not modified.

Parameters

Returns

a reference to this

ICU 2.0

Append the characters in `srcChars` to the UnicodeString object.

`srcChars` is not modified.

Parameters

Returns

a reference to this

ICU 2.0

Append the code unit `srcChar` to the UnicodeString object.

Parameters

Returns

a reference to this

ICU 2.0

Append the code point `srcChar` to the UnicodeString object.

Parameters

Returns

a reference to this

ICU 2.0

Insert the characters in `srcText` in the range

[`srcStart`, `srcStart + srcLength`) into the UnicodeString

object at offset `start`. `srcText` is not modified.

Parameters

Returns

a reference to this

ICU 2.0

Insert the characters in `srcText` into the UnicodeString object

at offset `start`. `srcText` is not modified.

Parameters

Returns

a reference to this

ICU 2.0

Insert the characters in `srcChars` in the range

[`srcStart`, `srcStart + srcLength`) into the UnicodeString

object at offset `start`. `srcChars` is not modified.

Parameters

Returns

a reference to this

ICU 2.0

Insert the characters in `srcChars` into the UnicodeString object

at offset `start`. `srcChars` is not modified.

Parameters

Returns

a reference to this

ICU 2.0

Insert the code unit `srcChar` into the UnicodeString object at

offset `start`.

Parameters

Returns

a reference to this

ICU 2.0

Insert the code point `srcChar` into the UnicodeString object at

offset `start`.

Parameters

Returns

a reference to this

ICU 2.0

Replace the characters in the range

[`start`, `start + length`) with the characters in

`srcText` in the range

[`srcStart`, `srcStart + srcLength`).

`srcText` is not modified.

Parameters

Returns

a reference to this

ICU 2.0

Replace the characters in the range

[`start`, `start + length`)

with the characters in `srcText`. `srcText` is

not modified.

Parameters

Returns

a reference to this

ICU 2.0

Replace the characters in the range

[`start`, `start + length`) with the characters in

`srcChars` in the range

[`srcStart`, `srcStart + srcLength`). `srcChars`

is not modified.

Parameters

Returns

a reference to this

ICU 2.0

Replace the characters in the range

[`start`, `start + length`) with the characters in

`srcChars`. `srcChars` is not modified.

Parameters

Returns

a reference to this

ICU 2.0

Replace the characters in the range

[`start`, `start + length`) with the code unit

`srcChar`.

Parameters

Returns

a reference to this

ICU 2.0

Replace the characters in the range

[`start`, `start + length`) with the code point

`srcChar`.

Parameters

Returns

a reference to this

ICU 2.0

Replace the characters in the range [`start`, `limit`)

with the characters in `srcText`. `srcText` is not modified.

Parameters

Returns

a reference to this

ICU 2.0

Replace the characters in the range [`start`, `limit`)

with the characters in `srcText` in the range

[`srcStart`, `srcLimit`). `srcText` is not modified.

Parameters

Returns

a reference to this

ICU 2.0

Replace a substring of this object with the given text.

Parameters

Replaceable API

Returns

true if it has MetaData

ICU 2.4

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

Replace all occurrences of characters in oldText with the characters

in newText

Parameters

Returns

a reference to this

ICU 2.0

Replace all occurrences of characters in oldText with characters

in newText

in the range [`start`, `start + length`).

Parameters

Returns

a reference to this

ICU 2.0

Replace all occurrences of characters in oldText in the range

[`oldStart`, `oldStart + oldLength`) with the characters

in newText in the range

[`newStart`, `newStart + newLength`)

in the range [`start`, `start + length`).

Parameters

Returns

a reference to this

ICU 2.0

Removes all characters from the UnicodeString object and clears the bogus flag.

This is the UnicodeString equivalent of std::string’s clear().

Returns

a reference to this

Remove the characters in the range

[`start`, `start + length`) from the UnicodeString object.

Parameters

Returns

a reference to this

ICU 2.0

Remove the characters in the range

[`start`, `limit`) from the UnicodeString object.

Parameters

Returns

a reference to this

ICU 2.0

Retain only the characters in the range

[`start`, `limit`) from the UnicodeString object.

Removes characters before `start` and at and after `limit`.

Parameters

Returns

a reference to this

ICU 4.4

Pad the start of this UnicodeString with the character `padChar`.

If the length of this UnicodeString is less than targetLength,

length() - targetLength copies of padChar will be added to the

beginning of this UnicodeString.

Parameters

Returns

true if the text was padded, false otherwise.

ICU 2.0

Pad the end of this UnicodeString with the character `padChar`.

If the length of this UnicodeString is less than targetLength,

length() - targetLength copies of padChar will be added to the

end of this UnicodeString.

Parameters

Returns

true if the text was padded, false otherwise.

ICU 2.0

Truncate this UnicodeString to the `targetLength`.

Parameters

Returns

true if the text was truncated, false otherwise

ICU 2.0

Trims leading and trailing whitespace from this UnicodeString.

Returns

a reference to this

ICU 2.0

Reverse this UnicodeString in place.

Returns

a reference to this

ICU 2.0

Reverse the range [`start`, `start + length`) in

this UnicodeString.

Parameters

Returns

a reference to this

ICU 2.0

Convert the characters in this to UPPER CASE following the conventions of

the default locale.

Returns

A reference to this.

ICU 2.0

Convert the characters in this to UPPER CASE following the conventions of

a specific locale.

Parameters

Returns

A reference to this.

ICU 2.0

Convert the characters in this to lower case following the conventions of

the default locale.

Returns

A reference to this.

ICU 2.0

Convert the characters in this to lower case following the conventions of

a specific locale.

Parameters

Returns

A reference to this.

ICU 2.0

Titlecase this string, convenience function using the default locale.

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.

If the break iterator passed in is null, the default Unicode algorithm

will be used to determine the titlecase positions.

This function uses only the setText(), first() and next() methods of the

provided break iterator.

Parameters

Returns

A reference to this.

ICU 2.1

Titlecase this 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.

If the break iterator passed in is null, the default Unicode algorithm

will be used to determine the titlecase positions.

This function uses only the setText(), first() and next() methods of the

provided break iterator.

Parameters

Returns

A reference to this.

ICU 2.1

Titlecase this string, with options.

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. (This can be modified with options.)

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.

If the break iterator passed in is null, the default Unicode algorithm

will be used to determine the titlecase positions.

This function uses only the setText(), first() and next() methods of the

provided break iterator.

Parameters

Returns

A reference to this.

ICU 3.8

Case-folds the characters in this 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.

Parameters

Returns

A reference to this.

ICU 2.0

Get a read/write pointer to the internal buffer.

The buffer is guaranteed to be large enough for at least minCapacity char16_ts,

writable, and is still owned by the UnicodeString object.

Calls to getBuffer(minCapacity) must not be nested, and

must be matched with calls to releaseBuffer(newLength).

If the string buffer was read-only or shared,

then it will be reallocated and copied.

An attempted nested call will return 0, and will not further modify the

state of the UnicodeString object.

It also returns 0 if the string is bogus.

The actual capacity of the string buffer may be larger than minCapacity.

getCapacity() returns the actual capacity.

For many operations, the full capacity should be used to avoid reallocations.

While the buffer is "open" between getBuffer(minCapacity)

and releaseBuffer(newLength), the following applies:

- The string length is set to 0.

- Any read API call on the UnicodeString object will behave like on a 0-length string.

- Any write API call on the UnicodeString object is disallowed and will have no effect.

- You can read from and write to the returned buffer.

- The previous string contents will still be in the buffer;

if you want to use it, then you need to call length() before getBuffer(minCapacity).

If the length() was greater than minCapacity, then any contents after minCapacity

may be lost.

The buffer contents is not NUL-terminated by getBuffer().

If length()

<

getCapacity() then you can terminate it by writing a NUL

at index length().

- You must call releaseBuffer(newLength) before and in order to

return to normal UnicodeString operation.

Parameters

Returns

a writable pointer to the internal string buffer,

or nullptr if an error occurs (nested calls, out of memory)

Release a read/write buffer on a UnicodeString object with an

"open" getBuffer(minCapacity).

This function must be called in a matched pair with getBuffer(minCapacity).

releaseBuffer(newLength) must be called if and only if a getBuffer(minCapacity) is "open".

It will set the string length to newLength, at most to the current capacity.

If newLength==-1 then it will set the length according to the

first NUL in the buffer, or to the capacity if there is no NUL.

After calling releaseBuffer(newLength) the UnicodeString is back to normal operation.

Parameters

Get a read-only pointer to the internal buffer.

This can be called at any time on a valid UnicodeString.

It returns 0 if the string is bogus, or

during an "open" getBuffer(minCapacity).

It can be called as many times as desired.

The pointer that it returns will remain valid until the UnicodeString object is modified,

at which time the pointer is semantically invalidated and must not be used any more.

The capacity of the buffer can be determined with getCapacity().

The part after length() may or may not be initialized and valid,

depending on the history of the UnicodeString object.

The buffer contents is (probably) not NUL-terminated.

You can check if it is with

`(s.length()

<

s.getCapacity()

&

&

buffer[s.length()]==0)`.

(See getTerminatedBuffer().)

The buffer may reside in read-only memory. Its contents must not

be modified.

Returns

a read-only pointer to the internal string buffer,

or nullptr if the string is empty or bogus

Get a read-only pointer to the internal buffer,

making sure that it is NUL-terminated.

This can be called at any time on a valid UnicodeString.

It returns 0 if the string is bogus, or

during an "open" getBuffer(minCapacity), or if the buffer cannot

be NUL-terminated (because memory allocation failed).

It can be called as many times as desired.

The pointer that it returns will remain valid until the UnicodeString object is modified,

at which time the pointer is semantically invalidated and must not be used any more.

The capacity of the buffer can be determined with getCapacity().

The part after length()+1 may or may not be initialized and valid,

depending on the history of the UnicodeString object.

The buffer contents is guaranteed to be NUL-terminated.

getTerminatedBuffer() may reallocate the buffer if a terminating NUL

is written.

For this reason, this function is not const, unlike getBuffer().

Note that a UnicodeString may also contain NUL characters as part of its contents.

The buffer may reside in read-only memory. Its contents must not

be modified.

Returns

a read-only pointer to the internal string buffer,

or 0 if the string is empty or bogus

Construct an empty UnicodeString.

ICU 2.0

Construct a UnicodeString with capacity to hold `capacity` char16_ts

Parameters

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

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

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

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

                                        
                                             UnicodeString str(u"literal");
                                             if (str == u"other literal") { ... }
                                        
                                    

nullptr_t constructor.

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

Parameters

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

                                        
                                             UnicodeString alias = UnicodeString::readOnlyAlias(u"literal");
                                             if (str == u"other literal") { ... }
                                        
                                    

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

Writable-aliasing nullptr_t constructor.

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

Parameters

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

                                        
                                             UnicodeString str(u"literal");
                                             if (str == u"other literal") { ... }
                                        
                                    

char* constructor.

Uses the default converter (and thus depends on the ICU conversion code)

unless U_CHARSET_IS_UTF8 is set to 1.

Parameters

char* constructor.

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.

ICU 2.0

Parameters

char* constructor.

ICU 2.0

Parameters

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

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

                                        
                                                 void fn(const char *s) {
                                                   UnicodeString ustr(s, -1, US_INV);
                                                   // use ustr ...
                                                 }
                                        
                                    

                                        
                                             UnicodeString str(u"literal");
                                             if (str == u"other literal") { ... }
                                        
                                    

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

Move constructor; might leave src in bogus state.

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

Parameters

'Substring' constructor from tail of source string.

Parameters

'Substring' constructor from subrange of source string.

Parameters

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

Destructor.

ICU 2.0

Create a UnicodeString from a UTF-8 string.

Illegal input is replaced with U+FFFD. Otherwise, errors result in a bogus string.

Calls u_strFromUTF8WithSub().

Parameters

Returns

A UnicodeString with equivalent UTF-16 contents.

Create a UnicodeString from a UTF-32 string.

Illegal input is replaced with U+FFFD. Otherwise, errors result in a bogus string.

Calls u_strFromUTF32WithSub().

Parameters

Returns

A UnicodeString with equivalent UTF-16 contents.

Unescape a string of characters and return a string containing

the result. 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

\

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.

This function is similar to u_unescape() but not identical to it.

The latter takes a source char*, so it does escape recognition

and also invariant conversion.

Returns

a string with backslash escapes interpreted, or an

empty string on error.

Unescape a single escape sequence and return the represented

character. See unescape() for a listing of the recognized escape

sequences. The character at offset-1 is assumed (without

checking) to be a backslash. If the escape sequence is

ill-formed, or the offset is out of range, U_SENTINEL=-1 is

returned.

Parameters

Returns

the character represented by the escape sequence at

offset, or U_SENTINEL=-1 on error.

ICU "poor man's RTTI", returns a UClassID for this class.

ICU 2.2

ICU "poor man's RTTI", returns a UClassID for the actual class.

ICU 2.2

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.