All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface java.text.CharacterIterator

public interface CharacterIterator
extends Cloneable

This interface defines a protocol for bidirectional iteration over text. The iterator iterates over a bounded sequence of characters. Characters are indexed with values beginning with the value returned by getBeginIndex and continuing through the value returned by getEndIndex()-1. The index of the current character can be retrieved by calling getIndex. Calling setIndex will move the iterator to a new position within the sequence of characters. If at any time the iterator's current index moves outside the range of getBeginIndex and getEndIndex, previous() and next() will return DONE, signaling that the iterator has reached the end of the sequence.

Examples:

Traverse the text from start to finish

 public void traverseForward(CharacterIterator iter) {
     for(char c = iter.first(); c != CharacterIterator.DONE; c = iter.next()) {
         processChar(c);
     }
 }

Traverse the text backwards, from end to start

 public void traverseBackward(CharacterIterator iter) {
     for(char c = iter.last(); c != CharacterIterator.DONE; c = iter.prev()) {
         processChar(c);
     }
 }

Traverse both forward and backward from a given position in the text. Calls to notBoundary() in this example represents some additional stopping criteria.

 public void traverseOut(CharacterIterator iter, int pos) {
     for (char c = iter.setIndex(pos);
          c != CharacterIterator.DONE && notBoundary(c);
          c = iter.next()) {}
 int end = iter.getIndex();
 for (char c = iter.setIndex(pos);
     c != CharacterIterator.DONE && notBoundary(c);
     c = iter.prev()) {}
 int start = iter.getIndex();
 processSection(start,end);
 }

See Also:: StringCharacterIterator

DONE: Constant that is returned when the iterator has reached either the end or the beginning of the text.

clone(): Create a copy of this iterator
current(): Get the character at the current position (as returned by getIndex()).
first(): Set the position to getBeginIndex() and return the character at that position.
getBeginIndex(): Return the start index of the text.
getEndIndex(): Return the end index of the text.
getIndex(): Return the current index.
last(): Set the position to getEndIndex()-1, return the character at that position.
next(): Increment the iterator's index by one and return the character at the new index.
previous(): Decrement the iterator's index by one and return the character at the new index.
setIndex(int): Set the position to the specified position in the text and return that character.

DONE

 public static final char DONE

Constant that is returned when the iterator has reached either the end or the beginning of the text. The unicode 2.0 standard states that '\\uFFFF' is an invalid unicode value and should not occur in any valid unicode string.

first

 public abstract char first()

Set the position to getBeginIndex() and return the character at that position.

Returns:: the first character in the text
See Also:: getBeginIndex

last

 public abstract char last()

Set the position to getEndIndex()-1, return the character at that position.

Returns:: the last character in the text
See Also:: getEndIndex

current

 public abstract char current()

Get the character at the current position (as returned by getIndex()).

Returns:: the character at the current position or DONE if the current position is off the end of the text.
See Also:: getIndex

next

 public abstract char next()

Increment the iterator's index by one and return the character at the new index. If the resulting index is greater or equal to getEndIndex(), the current index is reset to getEndIndex() and a value of DONE is returned.

Returns:: the character at the new position or DONE if the current position is off the end of the text.

previous

 public abstract char previous()

Decrement the iterator's index by one and return the character at the new index. If the resulting index is less than getBeginIndex(), the current index is reset to getBeginIndex() and a value of DONE is returned.

Returns:: the character at the new position or DONE if the current position is off the end of the text.

setIndex

 public abstract char setIndex(int position)

Set the position to the specified position in the text and return that character.

Parameters:: position - the position within the text. Valid values range from getBeginIndex() to getEndIndex() - 1. An IllegalArgumentException is thrown if an invalid value is supplied.
Returns:: the character at the specified position.

getBeginIndex

 public abstract int getBeginIndex()

Return the start index of the text.

Returns:: the index at which the text begins.

getEndIndex

 public abstract int getEndIndex()

Return the end index of the text. This index is the index of the first character following the end of the text.

Returns:: the index at which the text end.

getIndex

 public abstract int getIndex()

Return the current index.

Returns:: the current index.

clone

 public abstract Object clone()

Create a copy of this iterator

Returns:: A copy of this
Overrides:: clone in class Object

All Packages  Class Hierarchy  This Package  Previous  Next  Index

Submit a bug or feature