Top Description Constructors Methods
com.ibm.icu.text

public abstract Class UCharacterIterator

extends Object
implements Cloneable, UForwardCharacterIterator
Class Inheritance
All Implemented Interfaces
com.ibm.icu.text.UForwardCharacterIterator, java.lang.Cloneable
Known Direct Subclasses
com.ibm.icu.impl.CharacterIteratorWrapper, com.ibm.icu.impl.UCharArrayIterator, com.ibm.icu.impl.ReplaceableUCharacterIterator
Imports
java.text.CharacterIterator, com.ibm.icu.impl.CharacterIteratorWrapper, .ReplaceableUCharacterIterator, .UCharArrayIterator, .UCharacterIteratorWrapper
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.

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 code unit
current()

Returns the code unit at the current index.

public int

Returns:

current codepoint
currentCodePoint()

Returns the codepoint at the current index.

public CharacterIterator

Returns:

java.text.CharacterIterator object
getCharacterIterator()

Returns a java.text.CharacterIterator object for the underlying text of this iterator.

public abstract int

Returns:

current index in text.
getIndex()

Gets the current index in text.

public static final UCharacterIterator

Returns:

UCharacterIterator object
getInstance(Replaceable
a valid source as a Replaceable object
source)

Returns a UCharacterIterator object given a Replaceable object.

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(char[]
an array of UTF-16 code units
source)

Returns a UCharacterIterator object given a source character array.

public static final UCharacterIterator

Returns:

UCharacterIterator object
getInstance(char[]
an array of UTF-16 code units
source, int start, int limit)

Returns a UCharacterIterator object given a source character array.

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 as 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 int

Returns:

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

Moves the current position by the number of code units 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()

Redeclares com.ibm.icu.text.UForwardCharacterIterator.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()

Implements com.ibm.icu.text.UForwardCharacterIterator.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
setToLimit()

Sets the current index to the limit.

public void
setToStart()

Sets the current index to the start.

Inherited from java.lang.Object:
equalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

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

Annotations
@Override
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.
currentback to summary
public abstract int current()

Returns the code unit at the current index. If index is out of range, returns DONE. Index is not changed.

Returns:int

current code unit

ICU Status
Stable since ICU 2.4.
currentCodePointback to summary
public int currentCodePoint()

Returns the codepoint at the current index. If the current index is invalid, DONE is returned. If the current index points to a lead surrogate, and there is a following trail surrogate, then the code point is returned. Otherwise, the code unit at index is returned. Index is not changed.

Returns:int

current codepoint

ICU Status
Stable since ICU 2.4.
getCharacterIteratorback to summary
public CharacterIterator getCharacterIterator()

Returns a java.text.CharacterIterator object for the underlying text of this iterator. The returned iterator is independent of this iterator.

Returns:CharacterIterator

java.text.CharacterIterator object

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(Replaceable source)

Returns a UCharacterIterator object given a Replaceable object.

Parameters
source:Replaceable

a valid source as a Replaceable object

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(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(char[] source)

Returns a UCharacterIterator object given a source character array.

Parameters
source:char[]

an array 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(char[] source, int start, int limit)

Returns a UCharacterIterator object given a source character array.

Parameters
source:char[]

an array 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(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 as 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.
moveIndexback to summary
public int moveIndex(int delta)

Moves the current position by the number of code units specified, either forward or backward depending on the sign of delta (positive or negative respectively). 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 index is supplied
ICU Status
Stable since ICU 2.4.
nextback to summary
public abstract int next()

Redeclares com.ibm.icu.text.UForwardCharacterIterator.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.

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

Implements com.ibm.icu.text.UForwardCharacterIterator.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.

Annotations
@Override
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.
setToLimitback to summary
public void setToLimit()

Sets the current index to the limit.

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.