Top Description Fields Constructors Methods
jdk.internal.icu.text

public abstract Class UCharacterIterator

extends Object
implements Cloneable
Class Inheritance
All Implemented Interfaces
java.lang.Cloneable
Known Direct Subclasses
jdk.internal.icu.impl.CharacterIteratorWrapper, jdk.internal.icu.impl.ReplaceableUCharacterIterator
Imports
jdk.internal.icu.impl.CharacterIteratorWrapper, .ReplaceableUCharacterIterator, .UCharacterProperty, java.text.CharacterIterator
Abstract class that defines an API for iteration on text objects.This is an interface for forward and backward iteration and random access into a text object. Forward iteration is done with post-increment and backward iteration is done with pre-decrement semantics, while the java.text.CharacterIterator interface methods provided forward iteration with "pre-increment" and backward iteration with pre-decrement semantics. This API is more efficient for forward iteration over code points. The other major difference is that this API can do both code unit and code point iteration, java.text.CharacterIterator can only iterate over code units and is limited to BMP (0 - 0xFFFF)
Author
Ram
ICU Status
Stable since ICU 2.4.

Field Summary

Modifier and TypeField and Description
public static final int
DONE

Indicator that we have reached the ends of the UTF16 text.

Constructor Summary

AccessConstructor and Description
protected
UCharacterIterator()

Protected default constructor for the subclasses

Method Summary

Modifier and TypeMethod and Description
public Object

Returns:

copy of this iterator
clone()

Overrides java.lang.Object.clone.

Creates a copy of this iterator, independent from other iterators.

public abstract int

Returns:

current index in text.
getIndex()

Gets the current index in text.

public static final UCharacterIterator

Returns:

UCharacterIterator object
getInstance(String
a string
source)

Returns a UCharacterIterator object given a source string.

public static final UCharacterIterator

Returns:

UCharacterIterator object
getInstance(StringBuffer
an string buffer of UTF-16 code units
source)

Returns a UCharacterIterator object given a source StringBuffer.

public static final UCharacterIterator

Returns:

UCharacterIterator object
getInstance(CharacterIterator
a valid CharacterIterator object.
source)

Returns a UCharacterIterator object given a CharacterIterator.

public abstract int

Returns:

length of the text
getLength()

Returns the length of the text

public abstract int

Returns:

the number of code units added to fillIn, as a convenience
getText(char[]
an array of chars to fill with the underlying UTF-16 code units.
fillIn, int
the position within the array to start putting the data.
offset)

Fills the buffer with the underlying text storage of the iterator If the buffer capacity is not enough a exception is thrown.

public final int

Returns:

the number of code units added to fillIn, as a convenience
getText(char[]
an array of chars to fill with the underlying UTF-16 code units.
fillIn)

Convenience override for getText(char[], int) that provides an offset of 0.

public String

Returns:

the underlying text storage in the iterator as a string
getText()

Convenience method for returning the underlying text storage as a string

public int

Returns:

the new index
moveCodePointIndex(int
the number of code units to move the current index.
delta)

Moves the current position by the number of code points specified, either forward or backward depending on the sign of delta (positive or negative respectively).

public abstract int

Returns:

the next UTF16 code unit, or DONE if the index is at the limit of the text.
next()

Returns the UTF16 code unit at index, and increments to the next code unit (post-increment semantics).

public int

Returns:

the next codepoint in text, or DONE if the index is at the limit of the text.
nextCodePoint()

Returns the code point at index, and increments to the next code point (post-increment semantics).

public abstract int

Returns:

the previous code unit in the text, or DONE if the new index is before the start of the text.
previous()

Decrement to the position of the previous code unit in the text, and return it (pre-decrement semantics).

public int

Returns:

the previous code point in the text, or DONE if the new index is before the start of the text.
previousCodePoint()

Retreat to the start of the previous code point in the text, and return it (pre-decrement semantics).

public abstract void
setIndex(int
the index within the text.
index)

Sets the index to the specified index in the text.

public void
setToStart()

Sets the current index to the start.

Inherited from java.lang.Object:
equalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

DONEback to summary
public static final int DONE

Indicator that we have reached the ends of the UTF16 text. Moved from UForwardCharacterIterator.java

ICU Status
Stable since ICU 2.4.

Constructor Detail

UCharacterIteratorback to summary
protected UCharacterIterator()

Protected default constructor for the subclasses

ICU Status
Stable since ICU 2.4.

Method Detail

cloneback to summary
public Object clone() throws CloneNotSupportedException

Overrides java.lang.Object.clone.

Creates a copy of this iterator, independent from other iterators. If it is not possible to clone the iterator, returns null.

Returns:Object

copy of this iterator

Exceptions
CloneNotSupportedException:

Doc from java.lang.Object.clone.

if the object's class does not support the Cloneable interface. Subclasses that override the clone method can also throw this exception to indicate that an instance cannot be cloned.

ICU Status
Stable since ICU 2.4.
getIndexback to summary
public abstract int getIndex()

Gets the current index in text.

Returns:int

current index in text.

ICU Status
Stable since ICU 2.4.
getInstanceback to summary
public static final UCharacterIterator getInstance(String source)

Returns a UCharacterIterator object given a source string.

Parameters
source:String

a string

Returns:UCharacterIterator

UCharacterIterator object

Exceptions
IllegalArgumentException:
if the argument is null
ICU Status
Stable since ICU 2.4.
getInstanceback to summary
public static final UCharacterIterator getInstance(StringBuffer source)

Returns a UCharacterIterator object given a source StringBuffer.

Parameters
source:StringBuffer

an string buffer of UTF-16 code units

Returns:UCharacterIterator

UCharacterIterator object

Exceptions
IllegalArgumentException:
if the argument is null
ICU Status
Stable since ICU 2.4.
getInstanceback to summary
public static final UCharacterIterator getInstance(CharacterIterator source)

Returns a UCharacterIterator object given a CharacterIterator.

Parameters
source:CharacterIterator

a valid CharacterIterator object.

Returns:UCharacterIterator

UCharacterIterator object

Exceptions
IllegalArgumentException:
if the argument is null
ICU Status
Stable since ICU 2.4.
getLengthback to summary
public abstract int getLength()

Returns the length of the text

Returns:int

length of the text

ICU Status
Stable since ICU 2.4.
getTextback to summary
public abstract int getText(char[] fillIn, int offset)

Fills the buffer with the underlying text storage of the iterator If the buffer capacity is not enough a exception is thrown. The capacity of the fill in buffer should at least be equal to length of text in the iterator obtained by calling getLength(). Usage: 

UChacterIterator iter = new UCharacterIterator.getInstance(text);
        char[] buf = new char[iter.getLength()];
        iter.getText(buf);

        OR
        char[] buf= new char[1];
        int len = 0;
        for(;;){
            try{
                len = iter.getText(buf);
                break;
            }catch(IndexOutOfBoundsException e){
                buf = new char[iter.getLength()];
            }
        }
Parameters
fillIn:char[]

an array of chars to fill with the underlying UTF-16 code units.

offset:int

the position within the array to start putting the data.

Returns:int

the number of code units added to fillIn, as a convenience

Exceptions
IndexOutOfBoundsException:
exception if there is not enough room after offset in the array, or if offset < 0.
ICU Status
Stable since ICU 2.4.
getTextback to summary
public final int getText(char[] fillIn)

Convenience override for getText(char[], int) that provides an offset of 0.

Parameters
fillIn:char[]

an array of chars to fill with the underlying UTF-16 code units.

Returns:int

the number of code units added to fillIn, as a convenience

Exceptions
IndexOutOfBoundsException:
exception if there is not enough room in the array.
ICU Status
Stable since ICU 2.4.
getTextback to summary
public String getText()

Convenience method for returning the underlying text storage as a string

Returns:String

the underlying text storage in the iterator as a string

ICU Status
Stable since ICU 2.4.
moveCodePointIndexback to summary
public int moveCodePointIndex(int delta)

Moves the current position by the number of code points specified, either forward or backward depending on the sign of delta (positive or negative respectively). If the current index is at a trail surrogate then the first adjustment is by code unit, and the remaining adjustments are by code points. If the resulting index would be less than zero, the index is set to zero, and if the resulting index would be greater than limit, the index is set to limit.

Parameters
delta:int

the number of code units to move the current index.

Returns:int

the new index

Exceptions
IndexOutOfBoundsException:
is thrown if an invalid delta is supplied
ICU Status
Stable since ICU 2.4.
nextback to summary
public abstract int next()

Returns the UTF16 code unit at index, and increments to the next code unit (post-increment semantics). If index is out of range, DONE is returned, and the iterator is reset to the limit of the text.

Returns:int

the next UTF16 code unit, or DONE if the index is at the limit of the text.

ICU Status
Stable since ICU 2.4.
nextCodePointback to summary
public int nextCodePoint()

Returns the code point at index, and increments to the next code point (post-increment semantics). If index does not point to a valid surrogate pair, the behavior is the same as next(). Otherwise the iterator is incremented past the surrogate pair, and the code point represented by the pair is returned.

Returns:int

the next codepoint in text, or DONE if the index is at the limit of the text.

ICU Status
Stable since ICU 2.4.
previousback to summary
public abstract int previous()

Decrement to the position of the previous code unit in the text, and return it (pre-decrement semantics). If the resulting index is less than 0, the index is reset to 0 and DONE is returned.

Returns:int

the previous code unit in the text, or DONE if the new index is before the start of the text.

ICU Status
Stable since ICU 2.4.
previousCodePointback to summary
public int previousCodePoint()

Retreat to the start of the previous code point in the text, and return it (pre-decrement semantics). If the index is not preceded by a valid surrogate pair, the behavior is the same as previous(). Otherwise the iterator is decremented to the start of the surrogate pair, and the code point represented by the pair is returned.

Returns:int

the previous code point in the text, or DONE if the new index is before the start of the text.

ICU Status
Stable since ICU 2.4.
setIndexback to summary
public abstract void setIndex(int index)

Sets the index to the specified index in the text.

Parameters
index:int

the index within the text.

Exceptions
IndexOutOfBoundsException:
is thrown if an invalid index is supplied
ICU Status
Stable since ICU 2.4.
setToStartback to summary
public void setToStart()

Sets the current index to the start.

ICU Status
Stable since ICU 2.4.