public abstract class

UCharacterIterator

extends Object
implements Cloneable
java.lang.Object
   ↳ sun.text.normalizer.UCharacterIterator
Known Direct Subclasses

Class Overview

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)

Summary

Constants
int DONE Indicator that we have reached the ends of the UTF16 text.
Protected Constructors
UCharacterIterator()
Protected default constructor for the subclasses
Public Methods
Object clone()
Creates a copy of this iterator, independent from other iterators.
abstract int current()
Returns the code unit at the current index.
abstract int getIndex()
Gets the current index in text.
final static UCharacterIterator getInstance(CharacterIterator source)
Returns a UCharacterIterator object given a CharacterIterator.
final static UCharacterIterator getInstance(StringBuffer source)
Returns a UCharacterIterator object given a source StringBuffer.
final static UCharacterIterator getInstance(String source)
Returns a UCharacterIterator object given a source string.
abstract int getLength()
Returns the length of the text
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.
String getText()
Convenience method for returning the underlying text storage as as string
final int getText(char[] fillIn)
Convenience override for getText(char[], int) that provides an offset of 0.
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).
abstract int next()
Returns the UTF16 code unit at index, and increments to the next code unit (post-increment semantics).
int nextCodePoint()
Returns the code point at index, and increments to the next code point (post-increment semantics).
abstract int previous()
Decrement to the position of the previous code unit in the text, and return it (pre-decrement semantics).
abstract void setIndex(int index)
Sets the index to the specified index in the text.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int DONE

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

Constant Value: -1 (0xffffffff)

Protected Constructors

protected UCharacterIterator ()

Protected default constructor for the subclasses

Public Methods

public Object clone ()

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

Returns
  • copy of this iterator
Throws
CloneNotSupportedException

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
  • current code unit

public abstract int getIndex ()

Gets the current index in text.

Returns
  • current index in text.

public static final UCharacterIterator getInstance (CharacterIterator source)

Returns a UCharacterIterator object given a CharacterIterator.

Parameters
source a valid CharacterIterator object.
Returns
  • UCharacterIterator object
Throws
IllegalArgumentException if the argument is null

public static final UCharacterIterator getInstance (StringBuffer source)

Returns a UCharacterIterator object given a source StringBuffer.

Parameters
source an string buffer of UTF-16 code units
Returns
  • UCharacterIterator object
Throws
IllegalArgumentException if the argument is null

public static final UCharacterIterator getInstance (String source)

Returns a UCharacterIterator object given a source string.

Parameters
source a string
Returns
  • UCharacterIterator object
Throws
IllegalArgumentException if the argument is null

public abstract int getLength ()

Returns the length of the text

Returns
  • length of the text

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 an array of chars to fill with the underlying UTF-16 code units.
offset the position within the array to start putting the data.
Returns
  • the number of code units added to fillIn, as a convenience
Throws
exception if there is not enough room after offset in the array, or if offset < 0.

public String getText ()

Convenience method for returning the underlying text storage as as string

Returns
  • the underlying text storage in the iterator as a string

public final int getText (char[] fillIn)

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

Parameters
fillIn an array of chars to fill with the underlying UTF-16 code units.
Returns
  • the number of code units added to fillIn, as a convenience
Throws
exception if there is not enough room in the array.

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 the number of code units to move the current index.
Returns
  • the new index.
Throws
IndexOutOfBoundsException is thrown if an invalid index is supplied

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
  • the next UTF16 code unit, or DONE if the index is at the limit of the text.

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
  • the next codepoint in text, or DONE if the index is at the limit of the text.

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
  • the previous code unit in the text, or DONE if the new index is before the start of the text.

public abstract void setIndex (int index)

Sets the index to the specified index in the text.

Parameters
index the index within the text.
Throws
IndexOutOfBoundsException is thrown if an invalid index is supplied