OpenJDK 27 · jdk.internal.icu.text.UTF16 · APIdia, the JavaDoc alternative

Standalone utility class providing UTF16 character conversions and indexing conversions.

Code that uses strings alone rarely need modification. By design, UTF-16 does not allow overlap, so searching for strings is a safe operation. Similarly, concatenation is always safe. Substringing is safe if the start and end are both on UTF-32 boundaries. In normal code, the values for start and end are on those boundaries, since they arose from operations like searching. If not, the nearest UTF-32 boundaries can be determined using bounds(). Examples:

The following examples illustrate use of some of these methods.

// iteration forwards: Original
for (int i = 0; i < s.length(); ++i) {
    char ch = s.charAt(i);
    doSomethingWith(ch);
}

// iteration forwards: Changes for UTF-32
int ch;
for (int i = 0; i < s.length(); i += UTF16.getCharCount(ch)) {
    ch = UTF16.charAt(s, i);
    doSomethingWith(ch);
}

// iteration backwards: Original
for (int i = s.length() - 1; i >= 0; --i) {
    char ch = s.charAt(i);
    doSomethingWith(ch);
}

// iteration backwards: Changes for UTF-32
int ch;
for (int i = s.length() - 1; i > 0; i -= UTF16.getCharCount(ch)) {
    ch = UTF16.charAt(s, i);
    doSomethingWith(ch);
}

Notes:

Naming: For clarity, High and Low surrogates are called Lead and Trail in the API, which gives a better sense of their ordering in a string. offset16 and offset32 are used to distinguish offsets to UTF-16 boundaries vs offsets to UTF-32 boundaries. int char32 is used to contain UTF-32 characters, as opposed to char16, which is a UTF-16 code unit.
Roundtripping Offsets: You can always roundtrip from a UTF-32 offset to a UTF-16 offset and back. Because of the difference in structure, you can roundtrip from a UTF-16 offset to a UTF-32 offset and back if and only if bounds(string, offset16) != TRAIL.
Exceptions: The error checking will throw an exception if indices are out of bounds. Other than that, all methods will behave reasonably, even if unmatched surrogates or out-of-bounds UTF-32 values are present. UCharacter.isLegal() can be used to check for validity if desired.
Unmatched Surrogates: If the string contains unmatched surrogates, then these are counted as one UTF-32 value. This matches their iteration behavior, which is vital. It also matches common display practice as missing glyphs (see the Unicode Standard Section 5.4, 5.5).
Optimization: The method implementations may need optimization if the compiler doesn't fold static final methods. Since surrogate pairs will form an exceeding small percentage of all the text in the world, the singleton case should always be optimized for.

Field Summary

Modifier and Type	Field and Description
public static final int	CODEPOINT_MAX_VALUE The highest Unicode code point value (scalar value) according to the Unicode Standard.
public static final int	CODEPOINT_MIN_VALUE The lowest Unicode code point value.
private static final int	LEAD_SURROGATE_BITMASK Lead surrogate bitmask
private static final int	LEAD_SURROGATE_BITS Lead surrogate bits
public static final int	LEAD_SURROGATE_MAX_VALUE Lead surrogate maximum value
public static final int	LEAD_SURROGATE_MIN_VALUE Lead surrogate minimum value
private static final int	LEAD_SURROGATE_OFFSET_ Value that all lead surrogate starts with
private static final int	LEAD_SURROGATE_SHIFT_ Shift value for lead surrogate to form a supplementary character.
public static final int	SUPPLEMENTARY_MIN_VALUE The minimum value for Supplementary code points
private static final int	SURROGATE_BITMASK Surrogate bitmask
private static final int	SURROGATE_BITS Surrogate bits
public static final int	SURROGATE_MIN_VALUE Surrogate minimum value
private static final int	TRAIL_SURROGATE_BITMASK Trail surrogate bitmask
private static final int	TRAIL_SURROGATE_BITS Trail surrogate bits
private static final int	TRAIL_SURROGATE_MASK_ Mask to retrieve the significant value from a trail surrogate.
public static final int	TRAIL_SURROGATE_MAX_VALUE Trail surrogate maximum value
public static final int	TRAIL_SURROGATE_MIN_VALUE Trail surrogate minimum value

Constructor Summary

Access	Constructor and Description
private	UTF16() Prevent instance from being created.

Method Summary

Modifier and Type	Method and Description
private static int	_charAt(String source, int offset16, char single)
private static int	_charAt(CharSequence source, int offset16, char single)
public static StringBuffer	Returns: the updated StringBuffer append(StringBuffer the buffer to append to target, int value to append. char32) Append a single UTF-32 value to the end of a StringBuffer.
public static int	Returns: UTF-32 value for the UTF-32 value that contains the char at offset16. The boundaries of that codepoint are the same as in `bounds32()`. charAt(String array of UTF-16 chars source, int UTF-16 offset to the start of the character. offset16) Extract a single UTF-32 value from a string.
public static int	Returns: UTF-32 value for the UTF-32 value that contains the char at offset16. The boundaries of that codepoint are the same as in `bounds32()`. charAt(CharSequence array of UTF-16 chars source, int UTF-16 offset to the start of the character. offset16) Extract a single UTF-32 value from a string.
public static int	Returns: UTF-32 value for the UTF-32 value that contains the char at offset16. The boundaries of that codepoint are the same as in `bounds32()`. charAt(char[] Array of UTF-16 chars source, int Offset to substring in the source array for analyzing start, int Offset to substring in the source array for analyzing limit, int UTF-16 offset relative to start offset16) Extract a single UTF-32 value from a substring.
public static int	Returns: 2 if is in supplementary space, otherwise 1. getCharCount(int the input codepoint. char32) Determines how many chars this char32 requires.
public static char	Returns: lead surrogate if the getCharCount(ch) is 2; and 0 otherwise (note: 0 is not a valid lead surrogate). getLeadSurrogate(int the input character. char32) Returns the lead surrogate.
public static char	Returns: the trail surrogate if the getCharCount(ch) is 2; otherwise the character itself getTrailSurrogate(int the input character. char32) Returns the trail surrogate.
public static boolean	Returns: true If the input code point is a lead surrogate isLeadSurrogate(int The input character. (In ICU 2.1-69 the type of this parameter was `char`.) codePoint) Determines whether the code point is a lead surrogate.
public static boolean	Returns: true If the input code point is a surrogate. isSurrogate(int The input character. (In ICU 2.1-69 the type of this parameter was `char`.) codePoint) Determines whether the code point is a surrogate.
public static boolean	Returns: true If the input code point is a trail surrogate. isTrailSurrogate(int The input character. (In ICU 2.1-69 the type of this parameter was `char`.) codePoint) Determines whether the code point is a trail surrogate.
public static int	Returns: new shifted offset16 relative to start moveCodePointOffset(char[] char array source, int position of the subarray to be performed on start, int position of the subarray to be performed on limit, int UTF16 position to shift relative to start offset16, int number of codepoints to shift shift32) Shifts offset16 by the argument number of codepoints within a subarray.
private static String	Returns: string representation of the code point toString(int code point ch) Converts argument code point and returns a String object representing the code point's value in UTF16 format.
public static String	Returns: string value of char32 in UTF16 format valueOf(int the input character. char32) Convenience method corresponding to String.valueOf(char).

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

CODEPOINT_MAX_VALUE	back to summary
public static final int CODEPOINT_MAX_VALUE The highest Unicode code point value (scalar value) according to the Unicode Standard. ICU Status Stable since ICU 2.1.

CODEPOINT_MAX_VALUE

back to summary

public static final int CODEPOINT_MAX_VALUE

The highest Unicode code point value (scalar value) according to the Unicode Standard.

ICU Status: Stable since ICU 2.1.

CODEPOINT_MIN_VALUE	back to summary
public static final int CODEPOINT_MIN_VALUE The lowest Unicode code point value. ICU Status Stable since ICU 2.1.

CODEPOINT_MIN_VALUE

back to summary

public static final int CODEPOINT_MIN_VALUE

The lowest Unicode code point value.

ICU Status: Stable since ICU 2.1.

LEAD_SURROGATE_BITMASK	back to summary
private static final int LEAD_SURROGATE_BITMASK Lead surrogate bitmask

LEAD_SURROGATE_BITS	back to summary
private static final int LEAD_SURROGATE_BITS Lead surrogate bits

LEAD_SURROGATE_MAX_VALUE	back to summary
public static final int LEAD_SURROGATE_MAX_VALUE Lead surrogate maximum value ICU Status Stable since ICU 2.1.

LEAD_SURROGATE_MAX_VALUE

back to summary

public static final int LEAD_SURROGATE_MAX_VALUE

Lead surrogate maximum value

ICU Status: Stable since ICU 2.1.

LEAD_SURROGATE_MIN_VALUE	back to summary
public static final int LEAD_SURROGATE_MIN_VALUE Lead surrogate minimum value ICU Status Stable since ICU 2.1.

LEAD_SURROGATE_MIN_VALUE

back to summary

public static final int LEAD_SURROGATE_MIN_VALUE

Lead surrogate minimum value

ICU Status: Stable since ICU 2.1.

LEAD_SURROGATE_OFFSET_	back to summary
private static final int LEAD_SURROGATE_OFFSET_ Value that all lead surrogate starts with

LEAD_SURROGATE_SHIFT_	back to summary
private static final int LEAD_SURROGATE_SHIFT_ Shift value for lead surrogate to form a supplementary character.

SUPPLEMENTARY_MIN_VALUE	back to summary
public static final int SUPPLEMENTARY_MIN_VALUE The minimum value for Supplementary code points ICU Status Stable since ICU 2.1.

SUPPLEMENTARY_MIN_VALUE

back to summary

public static final int SUPPLEMENTARY_MIN_VALUE

The minimum value for Supplementary code points

ICU Status: Stable since ICU 2.1.

SURROGATE_BITMASK	back to summary
private static final int SURROGATE_BITMASK Surrogate bitmask

SURROGATE_BITS	back to summary
private static final int SURROGATE_BITS Surrogate bits

SURROGATE_MIN_VALUE	back to summary
public static final int SURROGATE_MIN_VALUE Surrogate minimum value ICU Status Stable since ICU 2.1.

SURROGATE_MIN_VALUE

back to summary

public static final int SURROGATE_MIN_VALUE

Surrogate minimum value

ICU Status: Stable since ICU 2.1.

TRAIL_SURROGATE_BITMASK	back to summary
private static final int TRAIL_SURROGATE_BITMASK Trail surrogate bitmask

TRAIL_SURROGATE_BITS	back to summary
private static final int TRAIL_SURROGATE_BITS Trail surrogate bits

TRAIL_SURROGATE_MASK_	back to summary
private static final int TRAIL_SURROGATE_MASK_ Mask to retrieve the significant value from a trail surrogate.

TRAIL_SURROGATE_MAX_VALUE	back to summary
public static final int TRAIL_SURROGATE_MAX_VALUE Trail surrogate maximum value ICU Status Stable since ICU 2.1.

TRAIL_SURROGATE_MAX_VALUE

back to summary

public static final int TRAIL_SURROGATE_MAX_VALUE

Trail surrogate maximum value

ICU Status: Stable since ICU 2.1.

TRAIL_SURROGATE_MIN_VALUE	back to summary
public static final int TRAIL_SURROGATE_MIN_VALUE Trail surrogate minimum value ICU Status Stable since ICU 2.1.

TRAIL_SURROGATE_MIN_VALUE

back to summary

public static final int TRAIL_SURROGATE_MIN_VALUE

Trail surrogate minimum value

ICU Status: Stable since ICU 2.1.

Constructor Detail

UTF16	back to summary
private UTF16() Prevent instance from being created.

Method Detail

_charAt	back to summary
private static int _charAt(String source, int offset16, char single)

_charAt	back to summary
private static int _charAt(CharSequence source, int offset16, char single)

append back to summary

append	back to summary
public static StringBuffer append(StringBuffer target, int char32) Append a single UTF-32 value to the end of a StringBuffer. If a validity check is required, use `isLegal()` on char32 before calling. Parameters target:StringBuffer the buffer to append to char32:int value to append. Returns:StringBuffer the updated StringBuffer Exceptions IllegalArgumentException: thrown when char32 does not lie within the range of the Unicode codepoints ICU Status Stable since ICU 2.1.

public static StringBuffer append(StringBuffer target, int char32)

Append a single UTF-32 value to the end of a StringBuffer. If a validity check is required, use isLegal() on char32 before calling.

Parameters

target:StringBuffer: the buffer to append to
char32:int: value to append.

Returns:StringBuffer

the updated StringBuffer

Exceptions

IllegalArgumentException:: thrown when char32 does not lie within the range of the Unicode codepoints

ICU Status

Stable since ICU 2.1.

charAt back to summary

charAt	back to summary
public static int charAt(String source, int offset16) Extract a single UTF-32 value from a string. Used when iterating forwards or backwards (with `UTF16.getCharCount()`, as well as random access. If a validity check is required, use `UCharacter.isLegal()` on the return value. If the char retrieved is part of a surrogate pair, its supplementary character will be returned. If a complete supplementary character is not found the incomplete character will be returned Parameters source:String array of UTF-16 chars offset16:int UTF-16 offset to the start of the character. Returns:int UTF-32 value for the UTF-32 value that contains the char at offset16. The boundaries of that codepoint are the same as in `bounds32()`. Exceptions IndexOutOfBoundsException: thrown if offset16 is out of bounds. ICU Status Stable since ICU 2.1.

public static int charAt(String source, int offset16)

Extract a single UTF-32 value from a string. Used when iterating forwards or backwards (with UTF16.getCharCount(), as well as random access. If a validity check is required, use UCharacter.isLegal() on the return value. If the char retrieved is part of a surrogate pair, its supplementary character will be returned. If a complete supplementary character is not found the incomplete character will be returned

Parameters

source:String: array of UTF-16 chars
offset16:int: UTF-16 offset to the start of the character.

Returns:int

UTF-32 value for the UTF-32 value that contains the char at offset16. The boundaries of that codepoint are the same as in bounds32().

Exceptions

IndexOutOfBoundsException:: thrown if offset16 is out of bounds.

ICU Status

Stable since ICU 2.1.

charAt back to summary

charAt	back to summary
public static int charAt(CharSequence source, int offset16) Extract a single UTF-32 value from a string. Used when iterating forwards or backwards (with `UTF16.getCharCount()`, as well as random access. If a validity check is required, use `UCharacter.isLegal()` on the return value. If the char retrieved is part of a surrogate pair, its supplementary character will be returned. If a complete supplementary character is not found the incomplete character will be returned Parameters source:CharSequence array of UTF-16 chars offset16:int UTF-16 offset to the start of the character. Returns:int UTF-32 value for the UTF-32 value that contains the char at offset16. The boundaries of that codepoint are the same as in `bounds32()`. Exceptions IndexOutOfBoundsException: thrown if offset16 is out of bounds. ICU Status Stable since ICU 2.1.

public static int charAt(CharSequence source, int offset16)

Parameters

source:CharSequence: array of UTF-16 chars
offset16:int: UTF-16 offset to the start of the character.

Returns:int

UTF-32 value for the UTF-32 value that contains the char at offset16. The boundaries of that codepoint are the same as in bounds32().

Exceptions

IndexOutOfBoundsException:: thrown if offset16 is out of bounds.

ICU Status

Stable since ICU 2.1.

charAt back to summary

charAt	back to summary
public static int charAt(char[] source, int start, int limit, int offset16) Extract a single UTF-32 value from a substring. Used when iterating forwards or backwards (with `UTF16.getCharCount()`, as well as random access. If a validity check is required, use `UCharacter.isLegal()` on the return value. If the char retrieved is part of a surrogate pair, its supplementary character will be returned. If a complete supplementary character is not found the incomplete character will be returned Parameters source:char[] Array of UTF-16 chars start:int Offset to substring in the source array for analyzing limit:int Offset to substring in the source array for analyzing offset16:int UTF-16 offset relative to start Returns:int UTF-32 value for the UTF-32 value that contains the char at offset16. The boundaries of that codepoint are the same as in `bounds32()`. Exceptions IndexOutOfBoundsException: Thrown if offset16 is not within the range of start and limit. ICU Status Stable since ICU 2.1.

public static int charAt(char[] source, int start, int limit, int offset16)

Extract a single UTF-32 value from a substring. Used when iterating forwards or backwards (with UTF16.getCharCount(), as well as random access. If a validity check is required, use UCharacter.isLegal() on the return value. If the char retrieved is part of a surrogate pair, its supplementary character will be returned. If a complete supplementary character is not found the incomplete character will be returned

Parameters

source:char[]: Array of UTF-16 chars
start:int: Offset to substring in the source array for analyzing
limit:int: Offset to substring in the source array for analyzing
offset16:int: UTF-16 offset relative to start

Returns:int

UTF-32 value for the UTF-32 value that contains the char at offset16. The boundaries of that codepoint are the same as in bounds32().

Exceptions

IndexOutOfBoundsException:: Thrown if offset16 is not within the range of start and limit.

ICU Status

Stable since ICU 2.1.

getCharCount back to summary

getCharCount	back to summary
public static int getCharCount(int char32) Determines how many chars this char32 requires. If a validity check is required, use `isLegal()` on char32 before calling. Parameters char32:int the input codepoint. Returns:int 2 if is in supplementary space, otherwise 1. ICU Status Stable since ICU 2.1.

public static int getCharCount(int char32)

Determines how many chars this char32 requires. If a validity check is required, use isLegal() on char32 before calling.

Parameters

char32:int: the input codepoint.

Returns:int

2 if is in supplementary space, otherwise 1.

ICU Status

Stable since ICU 2.1.

getLeadSurrogate back to summary

getLeadSurrogate	back to summary
public static char getLeadSurrogate(int char32) Returns the lead surrogate. If a validity check is required, use `isLegal()` on char32 before calling. Parameters char32:int the input character. Returns:char lead surrogate if the getCharCount(ch) is 2; and 0 otherwise (note: 0 is not a valid lead surrogate). ICU Status Stable since ICU 2.1.

public static char getLeadSurrogate(int char32)

Returns the lead surrogate. If a validity check is required, use isLegal() on char32 before calling.

Parameters

char32:int: the input character.

Returns:char

lead surrogate if the getCharCount(ch) is 2;
and 0 otherwise (note: 0 is not a valid lead surrogate).

ICU Status

Stable since ICU 2.1.

getTrailSurrogate back to summary

getTrailSurrogate	back to summary
public static char getTrailSurrogate(int char32) Returns the trail surrogate. If a validity check is required, use `isLegal()` on char32 before calling. Parameters char32:int the input character. Returns:char the trail surrogate if the getCharCount(ch) is 2; otherwise the character itself ICU Status Stable since ICU 2.1.

public static char getTrailSurrogate(int char32)

Returns the trail surrogate. If a validity check is required, use isLegal() on char32 before calling.

Parameters

char32:int: the input character.

Returns:char

the trail surrogate if the getCharCount(ch) is 2;
otherwise the character itself

ICU Status

Stable since ICU 2.1.

isLeadSurrogate back to summary

isLeadSurrogate	back to summary
public static boolean isLeadSurrogate(int codePoint) Determines whether the code point is a lead surrogate. Parameters codePoint:int The input character. (In ICU 2.1-69 the type of this parameter was `char`.) Returns:boolean true If the input code point is a lead surrogate ICU Status Stable since ICU 70.

public static boolean isLeadSurrogate(int codePoint)

Determines whether the code point is a lead surrogate.

Parameters

codePoint:int: The input character. (In ICU 2.1-69 the type of this parameter was char.)

Returns:boolean

true If the input code point is a lead surrogate

ICU Status

Stable since ICU 70.

isSurrogate back to summary

isSurrogate	back to summary
public static boolean isSurrogate(int codePoint) Determines whether the code point is a surrogate. Parameters codePoint:int The input character. (In ICU 2.1-69 the type of this parameter was `char`.) Returns:boolean true If the input code point is a surrogate. ICU Status Stable since ICU 70.

public static boolean isSurrogate(int codePoint)

Determines whether the code point is a surrogate.

Parameters

codePoint:int: The input character. (In ICU 2.1-69 the type of this parameter was char.)

Returns:boolean

true If the input code point is a surrogate.

ICU Status

Stable since ICU 70.

isTrailSurrogate back to summary

isTrailSurrogate	back to summary
public static boolean isTrailSurrogate(int codePoint) Determines whether the code point is a trail surrogate. Parameters codePoint:int The input character. (In ICU 2.1-69 the type of this parameter was `char`.) Returns:boolean true If the input code point is a trail surrogate. ICU Status Stable since ICU 70.

public static boolean isTrailSurrogate(int codePoint)

Determines whether the code point is a trail surrogate.

Parameters

codePoint:int: The input character. (In ICU 2.1-69 the type of this parameter was char.)

Returns:boolean

true If the input code point is a trail surrogate.

ICU Status

Stable since ICU 70.

moveCodePointOffset	back to summary
public static int moveCodePointOffset(char[] source, int start, int limit, int offset16, int shift32) Shifts offset16 by the argument number of codepoints within a subarray. Parameters source:char[] char array start:int position of the subarray to be performed on limit:int position of the subarray to be performed on offset16:int UTF16 position to shift relative to start shift32:int number of codepoints to shift Returns:int new shifted offset16 relative to start Exceptions IndexOutOfBoundsException: if the new offset16 is out of bounds with respect to the subarray or the subarray bounds are out of range. ICU Status Stable since ICU 2.1.

moveCodePointOffset

back to summary

public static int moveCodePointOffset(char[] source, int start, int limit, int offset16, int shift32)

Shifts offset16 by the argument number of codepoints within a subarray.

Parameters

source:char[]: char array
start:int: position of the subarray to be performed on
limit:int: position of the subarray to be performed on
offset16:int: UTF16 position to shift relative to start
shift32:int: number of codepoints to shift

Returns:int

new shifted offset16 relative to start

Exceptions

IndexOutOfBoundsException:: if the new offset16 is out of bounds with respect to the subarray or the subarray bounds are out of range.

ICU Status

Stable since ICU 2.1.

toString	back to summary
private static String toString(int ch) Converts argument code point and returns a String object representing the code point's value in UTF16 format. This method does not check for the validity of the codepoint, the results are not guaranteed if a invalid codepoint is passed as argument. The result is a string whose length is 1 for non-supplementary code points, 2 otherwise. Parameters ch:int code point Returns:String string representation of the code point

toString

back to summary

private static String toString(int ch)

Converts argument code point and returns a String object representing the code point's value in UTF16 format.

This method does not check for the validity of the codepoint, the results are not guaranteed if a invalid codepoint is passed as argument.

The result is a string whose length is 1 for non-supplementary code points, 2 otherwise.

Parameters

ch:int: code point

Returns:String

string representation of the code point

valueOf back to summary

valueOf	back to summary
public static String valueOf(int char32) Convenience method corresponding to String.valueOf(char). Returns a one or two char string containing the UTF-32 value in UTF16 format. If a validity check is required, use `isLegal()` on char32 before calling. Parameters char32:int the input character. Returns:String string value of char32 in UTF16 format Exceptions IllegalArgumentException: thrown if char32 is a invalid codepoint. ICU Status Stable since ICU 2.1.

public static String valueOf(int char32)

Convenience method corresponding to String.valueOf(char). Returns a one or two char string containing the UTF-32 value in UTF16 format. If a validity check is required, use isLegal() on char32 before calling.

Parameters

char32:int: the input character.

Returns:String

string value of char32 in UTF16 format

Exceptions

IllegalArgumentException:: thrown if char32 is a invalid codepoint.

ICU Status

Stable since ICU 2.1.

public final Class UTF16

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail