Java Doc for UTF16.java in  » Internationalization-Localization » icu4j » com » ibm » icu » text » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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

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

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

Returns the index within the argument UTF16 format Unicode string of the last occurrence of the argument codepoint, where the result is less than or equals to fromIndex.

This method is implemented based on codepoints, hence a single surrogate character will not match a supplementary character.

source is searched backwards starting at the last character starting at the specified index.

Examples:
UTF16.lastIndexOf("abc", 'c', 2) returns 2
UTF16.lastIndexOf("abc", 'c', 1) returns -1
UTF16.lastIndexOf("abc\ud800\udc00", 0x10000, 5) returns 3
UTF16.lastIndexOf("abc\ud800\udc00", 0x10000, 3) returns 3
UTF16.lastIndexOf("abc\ud800\udc00", 0xd800) returns -1

Returns the index within the argument UTF16 format Unicode string of the last occurrence of the argument string str, where the result is less than or equals to fromIndex.

This method is implemented based on codepoints, hence a "lead surrogate character + trail surrogate character" is treated as one entity. Hence if the str starts with trail surrogate character at index 0, a source with a leading a surrogate character before str found at in source will not have a valid match.

• SINGLE_CHAR_BOUNDARY : a single char; the bounds are[offset16, offset16+1]
• LEAD_SURROGATE_BOUNDARY : a surrogate pair starting atoffset16;the bounds are[offset16, offset16 + 2]
• TRAIL_SURROGATE_BOUNDARY : a surrogate pair starting atoffset16 - 1; the bounds are[offset16 - 1, offset16 + 1]

• SINGLE_CHAR_BOUNDARY : a single char; the bounds are[offset16, offset16 + 1]
• LEAD_SURROGATE_BOUNDARY : a surrogate pair starting atoffset16; the bounds are[offset16, offset16 + 2]
• TRAIL_SURROGATE_BOUNDARY : a surrogate pair starting atoffset16 - 1; the bounds are[offset16 - 1, offset16 + 1]

• SINGLE_CHAR_BOUNDARY : a single char; the bounds are
• LEAD_SURROGATE_BOUNDARY : a surrogate pair starting atoffset16; the bounds are [offset16, offset16 + 2]
• TRAIL_SURROGATE_BOUNDARY : a surrogate pair starting atoffset16 - 1; the bounds are [offset16 - 1, offset16 + 1]

To find the UTF-32 length of a string, use:

 len32 = countCodePoint(source, source.length());
 

Parameters:
  source - text to analyse
Parameters:
  offset16 - UTF-16 offset < source text length. UTF-32 offset
exception:
  IndexOutOfBoundsException - if offset16 is out of bounds.

To find the UTF-32 length of a string, use:

 len32 = countCodePoint(source);
 

Parameters:
  source - text to analyse
Parameters:
  offset16 - UTF-16 offset < source text length. UTF-32 offset
exception:
  IndexOutOfBoundsException - if offset16 is out of bounds.

To find the UTF-32 length of a substring, use:

 len32 = countCodePoint(source, start, limit);
 

Parameters:
  source - text to analyse
Parameters:
  start - offset of the substring
Parameters:
  limit - offset of the substring
Parameters:
  offset16 - UTF-16 relative to start UTF-32 offset relative to start
exception:
  IndexOutOfBoundsException - if offset16 is not within therange of start and limit.

If no such character occurs in this string, then -1 is returned.

Examples:
UTF16.indexOf("abc", 'a') returns 0
UTF16.indexOf("abc\ud800\udc00", 0x10000) returns 3
UTF16.indexOf("abc\ud800\udc00", 0xd800) returns -1

If no such string str occurs in this source, then -1 is returned.

Examples:
UTF16.indexOf("abc", "ab") returns 0
UTF16.indexOf("abc\ud800\udc00", "\ud800\udc00") returns 3
UTF16.indexOf("abc\ud800\udc00", "\ud800") returns -1

If no such character occurs in this string, then -1 is returned.

Examples:
UTF16.indexOf("abc", 'a', 1) returns -1
UTF16.indexOf("abc\ud800\udc00", 0x10000, 1) returns 3
UTF16.indexOf("abc\ud800\udc00", 0xd800, 1) returns -1

If no such string str occurs in this source, then -1 is returned.

Examples:
UTF16.indexOf("abc", "ab", 0) returns 0
UTF16.indexOf("abc\ud800\udc00", "\ud800\udc00", 0) returns 3
UTF16.indexOf("abc\ud800\udc00", "\ud800\udc00", 2) returns 3
UTF16.indexOf("abc\ud800\udc00", "\ud800", 0) returns -1

The overall effect is exactly as if the argument were converted to a string by the method valueOf(char) and the characters in that string were then inserted into target at the position indicated by offset16.

The offset argument must be greater than or equal to 0, and less than or equal to the length of source.
Parameters:
  target - string buffer to insert to
Parameters:
  offset16 - offset which char32 will be inserted in
Parameters:
  char32 - codepoint to be inserted a reference to target
exception:
  IndexOutOfBoundsException - thrown if offset16 is invalid.

The overall effect is exactly as if the argument were converted to a string by the method valueOf(char) and the characters in that string were then inserted into target at the position indicated by offset16.

The offset argument must be greater than or equal to 0, and less than or equal to the limit.
Parameters:
  target - char array to insert to
Parameters:
  limit - end index of the char array, limit <= target.length
Parameters:
  offset16 - offset which char32 will be inserted in
Parameters:
  char32 - codepoint to be inserted new limit size
exception:
  IndexOutOfBoundsException - thrown if offset16 is invalid.

Examples:
UTF16.lastIndexOf("abc", 'a') returns 0
UTF16.lastIndexOf("abc\ud800\udc00", 0x10000) returns 3
UTF16.lastIndexOf("abc\ud800\udc00", 0xd800) returns -1

source is searched backwards starting at the last character.

Examples:
UTF16.lastIndexOf("abc", "a") returns 0
UTF16.lastIndexOf("abc\ud800\udc00", "\ud800\udc00") returns 3
UTF16.lastIndexOf("abc\ud800\udc00", "\ud800") returns -1

source is searched backwards starting at the last character.

Returns the index within the argument UTF16 format Unicode string of the last occurrence of the argument codepoint, where the result is less than or equals to fromIndex.

This method is implemented based on codepoints, hence a single surrogate character will not match a supplementary character.

source is searched backwards starting at the last character starting at the specified index.

Examples:
UTF16.lastIndexOf("abc", 'c', 2) returns 2
UTF16.lastIndexOf("abc", 'c', 1) returns -1
UTF16.lastIndexOf("abc\ud800\udc00", 0x10000, 5) returns 3
UTF16.lastIndexOf("abc\ud800\udc00", 0x10000, 3) returns 3
UTF16.lastIndexOf("abc\ud800\udc00", 0xd800) returns -1

Returns the index within the argument UTF16 format Unicode string of the last occurrence of the argument string str, where the result is less than or equals to fromIndex.

This method is implemented based on codepoints, hence a "lead surrogate character + trail surrogate character" is treated as one entity. Hence if the str starts with trail surrogate character at index 0, a source with a leading a surrogate character before str found at in source will not have a valid match. Vice versa for lead surrogates that ends str.

Examples:
UTF16.lastIndexOf("abc", "c", 2) returns 2
UTF16.lastIndexOf("abc", "c", 1) returns -1
UTF16.lastIndexOf("abc\ud800\udc00", "\ud800\udc00", 5) returns 3
UTF16.lastIndexOf("abc\ud800\udc00", "\ud800\udc00", 3) returns 3
UTF16.lastIndexOf("abc\ud800\udc00", "\ud800", 4) returns -1

source is searched backwards starting at the last character.

Examples:
UTF16.replace("mesquite in your cellar", 'e', 'o');
returns "mosquito in your collar"
UTF16.replace("JonL", 'q', 'x');
returns "JonL" (no change)
UTF16.replace("Supplementary character \ud800\udc00", 0x10000, '!');
returns "Supplementary character !"
UTF16.replace("Supplementary character \ud800\udc00", 0xd800, '!');
returns "Supplementary character \ud800\udc00"

Examples:
UTF16.replace("mesquite in your cellar", "e", "o");
returns "mosquito in your collar"
UTF16.replace("mesquite in your cellar", "mesquite", "cat");
returns "cat in your cellar"
UTF16.replace("JonL", "q", "x");
returns "JonL" (no change)
UTF16.replace("Supplementary character \ud800\udc00", "\ud800\udc00", '!');
returns "Supplementary character !"
UTF16.replace("Supplementary character \ud800\udc00", "\ud800", '!');
returns "Supplementary character \ud800\udc00"

Examples:
UTF16.reverse(new StringBuffer( "Supplementary characters \ud800\udc00\ud801\udc01"))
returns "\ud801\udc01\ud800\udc00 sretcarahc yratnemelppuS".
Parameters:
  source - the source StringBuffer that contains UTF16 formatUnicode string to be reversed a modified source with reversed UTF16 format Unicode string.