com.ibm.icu.text

Class UTF16


public final class UTF16
extends Object

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:
Author:
Mark Davis, with help from Markus Scherer

Nested Class Summary

static class
UTF16.StringComparator
UTF16 string comparator class.

Field Summary

static int
CODEPOINT_MAX_VALUE
The highest Unicode code point value (scalar value) according to the Unicode Standard.
static int
CODEPOINT_MIN_VALUE
The lowest Unicode code point value.
static int
LEAD_SURROGATE_BOUNDARY
Value returned in bounds().
static int
LEAD_SURROGATE_MAX_VALUE
Lead surrogate maximum value
static int
LEAD_SURROGATE_MIN_VALUE
Lead surrogate minimum value
static int
SINGLE_CHAR_BOUNDARY
Value returned in bounds().
static int
SUPPLEMENTARY_MIN_VALUE
The minimum value for Supplementary code points
static int
SURROGATE_MAX_VALUE
Maximum surrogate value
static int
SURROGATE_MIN_VALUE
Surrogate minimum value
static int
TRAIL_SURROGATE_BOUNDARY
Value returned in bounds().
static int
TRAIL_SURROGATE_MAX_VALUE
Trail surrogate maximum value
static int
TRAIL_SURROGATE_MIN_VALUE
Trail surrogate minimum value

Method Summary

static StringBuffer
append(StringBuffer target, int char32)
Append a single UTF-32 value to the end of a StringBuffer.
static int
append(char[] target, int limit, int char32)
Adds a codepoint to offset16 position of the argument char array.
static StringBuffer
appendCodePoint(StringBuffer target, int cp)
Cover JDK 1.5 APIs.
static int
bounds(String source, int offset16)
Returns the type of the boundaries around the char at offset16.
static int
bounds(StringBuffer source, int offset16)
Returns the type of the boundaries around the char at offset16.
static int
bounds(source[] , int start, int limit, int offset16)
Returns the type of the boundaries around the char at offset16.
static int
charAt(String source, int offset16)
Extract a single UTF-32 value from a string.
static int
charAt(StringBuffer source, int offset16)
Extract a single UTF-32 value from a string.
static int
charAt(Replaceable source, int offset16)
Extract a single UTF-32 value from a string.
static int
charAt(source[] , int start, int limit, int offset16)
Extract a single UTF-32 value from a substring.
static int
countCodePoint(String source)
Number of codepoints in a UTF16 String
static int
countCodePoint(StringBuffer source)
Number of codepoints in a UTF16 String buffer
static int
countCodePoint(source[] , int start, int limit)
Number of codepoints in a UTF16 char array substring
static StringBuffer
delete(StringBuffer target, int offset16)
Removes the codepoint at the specified position in this target (shortening target by 1 character if the codepoint is a non-supplementary, 2 otherwise).
static int
delete(target[] , int limit, int offset16)
Removes the codepoint at the specified position in this target (shortening target by 1 character if the codepoint is a non-supplementary, 2 otherwise).
static int
findCodePointOffset(String source, int offset16)
Returns the UTF-32 offset corresponding to the first UTF-32 boundary at or after the given UTF-16 offset.
static int
findCodePointOffset(StringBuffer source, int offset16)
Returns the UTF-32 offset corresponding to the first UTF-32 boundary at the given UTF-16 offset.
static int
findCodePointOffset(source[] , int start, int limit, int offset16)
Returns the UTF-32 offset corresponding to the first UTF-32 boundary at the given UTF-16 offset.
static int
findOffsetFromCodePoint(String source, int offset32)
Returns the UTF-16 offset that corresponds to a UTF-32 offset.
static int
findOffsetFromCodePoint(StringBuffer source, int offset32)
Returns the UTF-16 offset that corresponds to a UTF-32 offset.
static int
findOffsetFromCodePoint(source[] , int start, int limit, int offset32)
Returns the UTF-16 offset that corresponds to a UTF-32 offset.
static int
getCharCount(int char32)
Determines how many chars this char32 requires.
static char
getLeadSurrogate(int char32)
Returns the lead surrogate.
static char
getTrailSurrogate(int char32)
Returns the trail surrogate.
static boolean
hasMoreCodePointsThan(String source, int number)
Check if the string contains more Unicode code points than a certain number.
static boolean
hasMoreCodePointsThan(StringBuffer source, int number)
Check if the string buffer contains more Unicode code points than a certain number.
static boolean
hasMoreCodePointsThan(source[] , int start, int limit, int number)
Check if the sub-range of char array, from argument start to limit, contains more Unicode code points than a certain number.
static int
indexOf(String source, String str)
Returns the index within the argument UTF16 format Unicode string of the first occurrence of the argument string str.
static int
indexOf(String source, String str, int fromIndex)
Returns the index within the argument UTF16 format Unicode string of the first occurrence of the argument string str.
static int
indexOf(String source, int char32)
Returns the index within the argument UTF16 format Unicode string of the first occurrence of the argument codepoint.
static int
indexOf(String source, int char32, int fromIndex)
Returns the index within the argument UTF16 format Unicode string of the first occurrence of the argument codepoint.
static StringBuffer
insert(StringBuffer target, int offset16, int char32)
Inserts char32 codepoint into target at the argument offset16.
static int
insert(target[] , int limit, int offset16, int char32)
Inserts char32 codepoint into target at the argument offset16.
static boolean
isLeadSurrogate(char char16)
Determines whether the character is a lead surrogate.
static boolean
isSurrogate(char char16)
Determines whether the code value is a surrogate.
static boolean
isTrailSurrogate(char char16)
Determines whether the character is a trail surrogate.
static int
lastIndexOf(String source, String str)
Returns the index within the argument UTF16 format Unicode string of the last occurrence of the argument string str.
static int
lastIndexOf(String source, String str, int fromIndex)
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.

static int
lastIndexOf(String source, int char32)
Returns the index within the argument UTF16 format Unicode string of the last occurrence of the argument codepoint.
static int
lastIndexOf(String source, int char32, int fromIndex)
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
Note this method is provided as support to jdk 1.3, which does not support supplementary characters to its fullest.

static int
moveCodePointOffset(String source, int offset16, int shift32)
Shifts offset16 by the argument number of codepoints
static int
moveCodePointOffset(StringBuffer source, int offset16, int shift32)
Shifts offset16 by the argument number of codepoints
static int
moveCodePointOffset(source[] , int start, int limit, int offset16, int shift32)
Shifts offset16 by the argument number of codepoints within a subarray.
static String
newString(int[] codePoints, int offset, int count)
Cover JDK 1.5 API.
static String
replace(String source, String oldStr, String newStr)
Returns a new UTF16 format Unicode string resulting from replacing all occurrences of oldStr in source with newStr.
static String
replace(String source, int oldChar32, int newChar32)
Returns a new UTF16 format Unicode string resulting from replacing all occurrences of oldChar32 in source with newChar32.
static StringBuffer
reverse(StringBuffer source)
Reverses a UTF16 format Unicode string and replaces source's content with it.
static void
setCharAt(StringBuffer target, int offset16, int char32)
Set a code point into a UTF16 position.
static int
setCharAt(target[] , int limit, int offset16, int char32)
Set a code point into a UTF16 position in a char array.
static String
valueOf(String source, int offset16)
Convenience method corresponding to String.valueOf(codepoint at offset16).
static String
valueOf(StringBuffer source, int offset16)
Convenience method corresponding to StringBuffer.valueOf(codepoint at offset16).
static String
valueOf(int char32)
Convenience method corresponding to String.valueOf(char).
static String
valueOf(source[] , int start, int limit, int offset16)
Convenience method.

Field Details

CODEPOINT_MAX_VALUE

public static final int CODEPOINT_MAX_VALUE
The highest Unicode code point value (scalar value) according to the Unicode Standard.
Field Value:
1114111

CODEPOINT_MIN_VALUE

public static final int CODEPOINT_MIN_VALUE
The lowest Unicode code point value.
Field Value:
0

LEAD_SURROGATE_BOUNDARY

public static final int LEAD_SURROGATE_BOUNDARY
Value returned in bounds(). These values are chosen specifically so that it actually represents the position of the character [offset16 - (value >> 2), offset16 + (value & 3)]
Field Value:
2

LEAD_SURROGATE_MAX_VALUE

public static final int LEAD_SURROGATE_MAX_VALUE
Lead surrogate maximum value
Field Value:
56319

LEAD_SURROGATE_MIN_VALUE

public static final int LEAD_SURROGATE_MIN_VALUE
Lead surrogate minimum value
Field Value:
55296

SINGLE_CHAR_BOUNDARY

public static final int SINGLE_CHAR_BOUNDARY
Value returned in bounds(). These values are chosen specifically so that it actually represents the position of the character [offset16 - (value >> 2), offset16 + (value & 3)]
Field Value:
1

SUPPLEMENTARY_MIN_VALUE

public static final int SUPPLEMENTARY_MIN_VALUE
The minimum value for Supplementary code points
Field Value:
65536

SURROGATE_MAX_VALUE

public static final int SURROGATE_MAX_VALUE
Maximum surrogate value
Field Value:
57343

SURROGATE_MIN_VALUE

public static final int SURROGATE_MIN_VALUE
Surrogate minimum value
Field Value:
55296

TRAIL_SURROGATE_BOUNDARY

public static final int TRAIL_SURROGATE_BOUNDARY
Value returned in bounds(). These values are chosen specifically so that it actually represents the position of the character [offset16 - (value >> 2), offset16 + (value & 3)]
Field Value:
5

TRAIL_SURROGATE_MAX_VALUE

public static final int TRAIL_SURROGATE_MAX_VALUE
Trail surrogate maximum value
Field Value:
57343

TRAIL_SURROGATE_MIN_VALUE

public static final int TRAIL_SURROGATE_MIN_VALUE
Trail surrogate minimum value
Field Value:
56320

Method Details

append

public static StringBuffer append(StringBuffer target,
                                  int char32)
Parameters:
target - the buffer to append to
char32 - value to append.
Returns:
the updated StringBuffer

append

public static int append(char[] target,
                         int limit,
                         int char32)
Adds a codepoint to offset16 position of the argument char array.
Parameters:
target - char array to be append with the new code point
limit - UTF16 offset which the codepoint will be appended.
char32 - code point to be appended
Returns:
offset after char32 in the array.

appendCodePoint

public static StringBuffer appendCodePoint(StringBuffer target,
                                           int cp)
Cover JDK 1.5 APIs. Append the code point to the buffer and return the buffer as a convenience.
Parameters:
target - the buffer to append to
cp - the code point to append
Returns:
the updated StringBuffer

bounds

public static int bounds(String source,
                         int offset16)
Returns the type of the boundaries around the char at offset16. Used for random access.
Parameters:
source - text to analyse
offset16 - UTF-16 offset
Returns:
  • SINGLE_CHAR_BOUNDARY : a single char; the bounds are [offset16, offset16+1]
  • LEAD_SURROGATE_BOUNDARY : a surrogate pair starting at offset16; the bounds are [offset16, offset16 + 2]
  • TRAIL_SURROGATE_BOUNDARY : a surrogate pair starting at offset16 - 1; the bounds are [offset16 - 1, offset16 + 1]
For bit-twiddlers, the return values for these are chosen so that the boundaries can be gotten by: [offset16 - (value >> 2), offset16 + (value & 3)].

bounds

public static int bounds(StringBuffer source,
                         int offset16)
Returns the type of the boundaries around the char at offset16. Used for random access.
Parameters:
source - string buffer to analyse
offset16 - UTF16 offset
Returns:
  • SINGLE_CHAR_BOUNDARY : a single char; the bounds are [offset16, offset16 + 1]
  • LEAD_SURROGATE_BOUNDARY : a surrogate pair starting at offset16; the bounds are [offset16, offset16 + 2]
  • TRAIL_SURROGATE_BOUNDARY : a surrogate pair starting at offset16 - 1; the bounds are [offset16 - 1, offset16 + 1]
For bit-twiddlers, the return values for these are chosen so that the boundaries can be gotten by: [offset16 - (value >> 2), offset16 + (value & 3)].

bounds

public static int bounds(source[] ,
                         int start,
                         int limit,
                         int offset16)
Returns the type of the boundaries around the char at offset16. Used for random access. Note that the boundaries are determined with respect to the subarray, hence the char array {0xD800, 0xDC00} has the result SINGLE_CHAR_BOUNDARY for start = offset16 = 0 and limit = 1.
Parameters:
start - offset to substring in the source array for analyzing
limit - offset to substring in the source array for analyzing
offset16 - UTF16 offset relative to start
Returns:
  • SINGLE_CHAR_BOUNDARY : a single char; the bounds are
  • LEAD_SURROGATE_BOUNDARY : a surrogate pair starting at offset16; the bounds are [offset16, offset16 + 2]
  • TRAIL_SURROGATE_BOUNDARY : a surrogate pair starting at offset16 - 1; the bounds are [offset16 - 1, offset16 + 1]
For bit-twiddlers, the boundary values for these are chosen so that the boundaries can be gotten by: [offset16 - (boundvalue >> 2), offset16 + (boundvalue & 3)].

charAt

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 - array of UTF-16 chars
offset16 - UTF-16 offset to the start of the character.
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

public static int charAt(StringBuffer 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 - UTF-16 chars string buffer
offset16 - UTF-16 offset to the start of the character.
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

public static int charAt(Replaceable 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 - UTF-16 chars string buffer
offset16 - UTF-16 offset to the start of the character.
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

public static int charAt(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:
start - offset to substring in the source array for analyzing
limit - offset to substring in the source array for analyzing
offset16 - UTF-16 offset relative to start
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().

countCodePoint

public static int countCodePoint(String source)
Number of codepoints in a UTF16 String
Parameters:
source - UTF16 string
Returns:
number of codepoint in string

countCodePoint

public static int countCodePoint(StringBuffer source)
Number of codepoints in a UTF16 String buffer
Parameters:
source - UTF16 string buffer
Returns:
number of codepoint in string

countCodePoint

public static int countCodePoint(source[] ,
                                 int start,
                                 int limit)
Number of codepoints in a UTF16 char array substring
Parameters:
start - offset of the substring
limit - offset of the substring
Returns:
number of codepoint in the substring

delete

public static StringBuffer delete(StringBuffer target,
                                  int offset16)
Removes the codepoint at the specified position in this target (shortening target by 1 character if the codepoint is a non-supplementary, 2 otherwise).
Parameters:
target - string buffer to remove codepoint from
offset16 - offset which the codepoint will be removed
Returns:
a reference to target

delete

public static int delete(target[] ,
                         int limit,
                         int offset16)
Removes the codepoint at the specified position in this target (shortening target by 1 character if the codepoint is a non-supplementary, 2 otherwise).
Parameters:
limit - end index of the char array, limit <= target.length
offset16 - offset which the codepoint will be removed
Returns:
a new limit size

findCodePointOffset

public static int findCodePointOffset(String source,
                                      int offset16)
Returns the UTF-32 offset corresponding to the first UTF-32 boundary at or after the given UTF-16 offset. Used for random access. See the class description for notes on roundtripping.
Note: If the UTF-16 offset is into the middle of a surrogate pair, then the UTF-32 offset of the lead of the pair is returned.

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

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

Parameters:
source - text to analyse
offset16 - UTF-16 offset <32source text length.
Returns:
UTF-32 offset

findCodePointOffset

public static int findCodePointOffset(StringBuffer source,
                                      int offset16)
Returns the UTF-32 offset corresponding to the first UTF-32 boundary at the given UTF-16 offset. Used for random access. See the class description for notes on roundtripping.
Note: If the UTF-16 offset is into the middle of a surrogate pair, then the UTF-32 offset of the lead of the pair is returned.

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

     len32 = countCodePoint(source);
   

Parameters:
source - text to analyse
offset16 - UTF-16 offset <32source text length.
Returns:
UTF-32 offset

findCodePointOffset

public static int findCodePointOffset(source[] ,
                                      int start,
                                      int limit,
                                      int offset16)
Returns the UTF-32 offset corresponding to the first UTF-32 boundary at the given UTF-16 offset. Used for random access. See the class description for notes on roundtripping.
Note: If the UTF-16 offset is into the middle of a surrogate pair, then the UTF-32 offset of the lead of the pair is returned.

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

     len32 = countCodePoint(source, start, limit);
   

Parameters:
start - offset of the substring
limit - offset of the substring
offset16 - UTF-16 relative to start
Returns:
UTF-32 offset relative to start

findOffsetFromCodePoint

public static int findOffsetFromCodePoint(String source,
                                          int offset32)
Parameters:
source - the UTF-16 string
offset32 - UTF-32 offset
Returns:
UTF-16 offset

findOffsetFromCodePoint

public static int findOffsetFromCodePoint(StringBuffer source,
                                          int offset32)
Parameters:
source - the UTF-16 string buffer
offset32 - UTF-32 offset
Returns:
UTF-16 offset

findOffsetFromCodePoint

public static int findOffsetFromCodePoint(source[] ,
                                          int start,
                                          int limit,
                                          int offset32)
Parameters:
start - offset of the substring to be analysed
limit - offset of the substring to be analysed
offset32 - UTF-32 offset relative to start
Returns:
UTF-16 offset relative to start

getCharCount

public static int getCharCount(int char32)
Parameters:
char32 - the input codepoint.
Returns:
2 if is in supplementary space, otherwise 1.

getLeadSurrogate

public static char getLeadSurrogate(int char32)
Parameters:
char32 - the input character.
Returns:
lead surrogate if the getCharCount(ch) is 2;
and 0 otherwise (note: 0 is not a valid lead surrogate).

getTrailSurrogate

public static char getTrailSurrogate(int char32)
Parameters:
char32 - the input character.
Returns:
the trail surrogate if the getCharCount(ch) is 2;
otherwise the character itself

hasMoreCodePointsThan

public static boolean hasMoreCodePointsThan(String source,
                                            int number)
Check if the string contains more Unicode code points than a certain number. This is more efficient than counting all code points in the entire string and comparing that number with a threshold. This function may not need to scan the string at all if the length is within a certain range, and never needs to count more than 'number + 1' code points. Logically equivalent to (countCodePoint(s) > number). A Unicode code point may occupy either one or two code units.
Parameters:
source - The input string.
number - The number of code points in the string is compared against the 'number' parameter.
Returns:
boolean value for whether the string contains more Unicode code points than 'number'.

hasMoreCodePointsThan

public static boolean hasMoreCodePointsThan(StringBuffer source,
                                            int number)
Check if the string buffer contains more Unicode code points than a certain number. This is more efficient than counting all code points in the entire string buffer and comparing that number with a threshold. This function may not need to scan the string buffer at all if the length is within a certain range, and never needs to count more than 'number + 1' code points. Logically equivalent to (countCodePoint(s) > number). A Unicode code point may occupy either one or two code units.
Parameters:
source - The input string buffer.
number - The number of code points in the string buffer is compared against the 'number' parameter.
Returns:
boolean value for whether the string buffer contains more Unicode code points than 'number'.

hasMoreCodePointsThan

public static boolean hasMoreCodePointsThan(source[] ,
                                            int start,
                                            int limit,
                                            int number)
Check if the sub-range of char array, from argument start to limit, contains more Unicode code points than a certain number. This is more efficient than counting all code points in the entire char array range and comparing that number with a threshold. This function may not need to scan the char array at all if start and limit is within a certain range, and never needs to count more than 'number + 1' code points. Logically equivalent to (countCodePoint(source, start, limit) > number). A Unicode code point may occupy either one or two code units.
Parameters:
start - offset to substring in the source array for analyzing
limit - offset to substring in the source array for analyzing
number - The number of code points in the string is compared against the 'number' parameter.
Returns:
boolean value for whether the string contains more Unicode code points than 'number'.

indexOf

public static int indexOf(String source,
                          String str)
Returns the index within the argument UTF16 format Unicode string of the first occurrence of the argument string str. This method is implemented based on codepoints, hence a "lead surrogate character + trail surrogate character" is treated as one entity.e 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. See example below.

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
Note this method is provided as support to jdk 1.3, which does not support supplementary characters to its fullest.

Parameters:
source - UTF16 format Unicode string that will be searched
str - UTF16 format Unicode string to search for
Returns:
the index of the first occurrence of the codepoint in the argument Unicode string, or -1 if the codepoint does not occur.

indexOf

public static int indexOf(String source,
                          String str,
                          int fromIndex)
Returns the index within the argument UTF16 format Unicode string of the first occurrence of the argument string str. This method is implemented based on codepoints, hence a "lead surrogate character + trail surrogate character" is treated as one entity.e 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. See example below.

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
Note this method is provided as support to jdk 1.3, which does not support supplementary characters to its fullest.

Parameters:
source - UTF16 format Unicode string that will be searched
str - UTF16 format Unicode string to search for
fromIndex - the index to start the search from.
Returns:
the index of the first occurrence of the codepoint in the argument Unicode string, or -1 if the codepoint does not occur.

indexOf

public static int indexOf(String source,
                          int char32)
Returns the index within the argument UTF16 format Unicode string of the first occurrence of the argument codepoint. I.e., the smallest index i such that UTF16.charAt(source, i) == char32 is true.

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
Note this method is provided as support to jdk 1.3, which does not support supplementary characters to its fullest.

Parameters:
source - UTF16 format Unicode string that will be searched
char32 - codepoint to search for
Returns:
the index of the first occurrence of the codepoint in the argument Unicode string, or -1 if the codepoint does not occur.

indexOf

public static int indexOf(String source,
                          int char32,
                          int fromIndex)
Returns the index within the argument UTF16 format Unicode string of the first occurrence of the argument codepoint. I.e., the smallest index i such that:
(UTF16.charAt(source, i) == char32 && i >= fromIndex) is true.

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
Note this method is provided as support to jdk 1.3, which does not support supplementary characters to its fullest.

Parameters:
source - UTF16 format Unicode string that will be searched
char32 - codepoint to search for
fromIndex - the index to start the search from.
Returns:
the index of the first occurrence of the codepoint in the argument Unicode string at or after fromIndex, or -1 if the codepoint does not occur.

insert

public static StringBuffer insert(StringBuffer target,
                                  int offset16,
                                  int char32)
Inserts char32 codepoint into target at the argument offset16. If the offset16 is in the middle of a supplementary codepoint, char32 will be inserted after the supplementary codepoint. The length of target increases by one if codepoint is non-supplementary, 2 otherwise.

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
offset16 - offset which char32 will be inserted in
char32 - codepoint to be inserted
Returns:
a reference to target

insert

public static int insert(target[] ,
                         int limit,
                         int offset16,
                         int char32)
Inserts char32 codepoint into target at the argument offset16. If the offset16 is in the middle of a supplementary codepoint, char32 will be inserted after the supplementary codepoint. Limit increases by one if codepoint is non-supplementary, 2 otherwise.

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:
limit - end index of the char array, limit <= target.length
offset16 - offset which char32 will be inserted in
char32 - codepoint to be inserted
Returns:
new limit size

isLeadSurrogate

public static boolean isLeadSurrogate(char char16)
Determines whether the character is a lead surrogate.
Parameters:
char16 - the input character.
Returns:
true iff the input character is a lead surrogate

isSurrogate

public static boolean isSurrogate(char char16)
Determines whether the code value is a surrogate.
Parameters:
char16 - the input character.
Returns:
true iff the input character is a surrogate.

isTrailSurrogate

public static boolean isTrailSurrogate(char char16)
Determines whether the character is a trail surrogate.
Parameters:
char16 - the input character.
Returns:
true iff the input character is a trail surrogate.

lastIndexOf

public static int lastIndexOf(String source,
                              String str)
Returns the index within the argument UTF16 format Unicode string of the last occurrence of the argument string str. This method is implemented based on codepoints, hence a "lead surrogate character + trail surrogate character" is treated as one entity.e 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. See example below.

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. Note this method is provided as support to jdk 1.3, which does not support supplementary characters to its fullest.

Parameters:
source - UTF16 format Unicode string that will be searched
str - UTF16 format Unicode string to search for
Returns:
the index of the last occurrence of the codepoint in source, or -1 if the codepoint does not occur.

lastIndexOf

public static int lastIndexOf(String source,
                              String str,
                              int fromIndex)
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. See example below.

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. Note this method is provided as support to jdk 1.3, which does not support supplementary characters to its fullest.

Parameters:
source - UTF16 format Unicode string that will be searched
str - UTF16 format Unicode string to search for
fromIndex - the index to start the search from. There is no restriction on the value of fromIndex. If it is greater than or equal to the length of this string, it has the same effect as if it were equal to one less than the length of this string: this entire string may be searched. If it is negative, it has the same effect as if it were -1: -1 is returned.
Returns:
the index of the last occurrence of the codepoint in source, or -1 if the codepoint does not occur.

lastIndexOf

public static int lastIndexOf(String source,
                              int char32)
Returns the index within the argument UTF16 format Unicode string of the last occurrence of the argument codepoint. I.e., the index returned is the largest value i such that: UTF16.charAt(source, i) == char32 is true.

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. Note this method is provided as support to jdk 1.3, which does not support supplementary characters to its fullest.

Parameters:
source - UTF16 format Unicode string that will be searched
char32 - codepoint to search for
Returns:
the index of the last occurrence of the codepoint in source, or -1 if the codepoint does not occur.

lastIndexOf

public static int lastIndexOf(String source,
                              int char32,
                              int fromIndex)
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
Note this method is provided as support to jdk 1.3, which does not support supplementary characters to its fullest.

Parameters:
source - UTF16 format Unicode string that will be searched
char32 - codepoint to search for
fromIndex - the index to start the search from. There is no restriction on the value of fromIndex. If it is greater than or equal to the length of this string, it has the same effect as if it were equal to one less than the length of this string: this entire string may be searched. If it is negative, it has the same effect as if it were -1: -1 is returned.
Returns:
the index of the last occurrence of the codepoint in source, or -1 if the codepoint does not occur.

moveCodePointOffset

public static int moveCodePointOffset(String source,
                                      int offset16,
                                      int shift32)
Shifts offset16 by the argument number of codepoints
Parameters:
source - string
offset16 - UTF16 position to shift
shift32 - number of codepoints to shift
Returns:
new shifted offset16

moveCodePointOffset

public static int moveCodePointOffset(StringBuffer source,
                                      int offset16,
                                      int shift32)
Shifts offset16 by the argument number of codepoints
Parameters:
source - string buffer
offset16 - UTF16 position to shift
shift32 - number of codepoints to shift
Returns:
new shifted offset16

moveCodePointOffset

public static int moveCodePointOffset(source[] ,
                                      int start,
                                      int limit,
                                      int offset16,
                                      int shift32)
Shifts offset16 by the argument number of codepoints within a subarray.
Parameters:
start - position of the subarray to be performed on
limit - position of the subarray to be performed on
offset16 - UTF16 position to shift relative to start
shift32 - number of codepoints to shift
Returns:
new shifted offset16 relative to start

newString

public static String newString(int[] codePoints,
                               int offset,
                               int count)
Cover JDK 1.5 API. Create a String from an array of codePoints.
Parameters:
codePoints - the code array
offset - the start of the text in the code point array
count - the number of code points
Returns:
a String representing the code points between offset and count

replace

public static String replace(String source,
                             String oldStr,
                             String newStr)
Returns a new UTF16 format Unicode string resulting from replacing all occurrences of oldStr in source with newStr. If the string oldStr does not occur in the UTF16 format Unicode string source, then source will be returned. Otherwise, a new String object is created that represents a codepoint sequence identical to the codepoint sequence represented by source, except that every occurrence of oldStr is replaced by an occurrence of newStr.

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"
Note this method is provided as support to jdk 1.3, which does not support supplementary characters to its fullest.

Parameters:
source - UTF16 format Unicode string which the replacements will be based on.
oldStr - non-zero-length string to be replaced.
newStr - the new string to replace oldStr
Returns:
new String derived from source by replacing every occurrence of oldStr with newStr. When no oldStr is found in source, then source will be returned.

replace

public static String replace(String source,
                             int oldChar32,
                             int newChar32)
Returns a new UTF16 format Unicode string resulting from replacing all occurrences of oldChar32 in source with newChar32. If the character oldChar32 does not occur in the UTF16 format Unicode string source, then source will be returned. Otherwise, a new String object is created that represents a codepoint sequence identical to the codepoint sequence represented by source, except that every occurrence of oldChar32 is replaced by an occurrence of newChar32.

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"
Note this method is provided as support to jdk 1.3, which does not support supplementary characters to its fullest.

Parameters:
source - UTF16 format Unicode string which the codepoint replacements will be based on.
oldChar32 - non-zero old codepoint to be replaced.
newChar32 - the new codepoint to replace oldChar32
Returns:
new String derived from source by replacing every occurrence of oldChar32 with newChar32, unless when no oldChar32 is found in source then source will be returned.

reverse

public static StringBuffer reverse(StringBuffer source)
Reverses a UTF16 format Unicode string and replaces source's content with it. This method will reverse surrogate characters correctly, instead of blindly reversing every character.

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 format Unicode string to be reversed
Returns:
a modified source with reversed UTF16 format Unicode string.

setCharAt

public static void setCharAt(StringBuffer target,
                             int offset16,
                             int char32)
Set a code point into a UTF16 position. Adjusts target according if we are replacing a non-supplementary codepoint with a supplementary and vice versa.
Parameters:
target - stringbuffer
offset16 - UTF16 position to insert into
char32 - code point

setCharAt

public static int setCharAt(target[] ,
                            int limit,
                            int offset16,
                            int char32)
Set a code point into a UTF16 position in a char array. Adjusts target according if we are replacing a non-supplementary codepoint with a supplementary and vice versa.
Parameters:
limit - numbers of valid chars in target, different from target.length. limit counts the number of chars in target that represents a string, not the size of array target.
offset16 - UTF16 position to insert into
char32 - code point
Returns:
new number of chars in target that represents a string

valueOf

public static String valueOf(String source,
                             int offset16)
Parameters:
source - the input string.
offset16 - the UTF16 index to the codepoint in source
Returns:
string value of char32 in UTF16 format

valueOf

public static String valueOf(StringBuffer source,
                             int offset16)
Parameters:
source - the input string buffer.
offset16 - the UTF16 index to the codepoint in source
Returns:
string value of char32 in UTF16 format

valueOf

public static String valueOf(int char32)
Parameters:
char32 - the input character.
Returns:
string value of char32 in UTF16 format

valueOf

public static String valueOf(source[] ,
                             int start,
                             int limit,
                             int offset16)
Parameters:
start - start index of the subarray
limit - end index of the subarray
offset16 - the UTF16 index to the codepoint in source relative to start
Returns:
string value of char32 in UTF16 format

Copyright (c) 2006 IBM Corporation and others.