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 startIndex and continuing through the value returned by endIndex()-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 startIndex and endIndex, 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(iter.getText.subString(start,end));
 }
Typically, subclasses will supply a constructor that takes a text storage object (such as a String, StringBuffer, or char[]), start and end offsets, and a reset method that takes the same.

See Also:
StringCharacterIterator

Variable Index

o DONE
Constant that is returned when the iterator has reached the end of the text.

Method Index

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

Variables

o DONE 
  public final static char DONE
Constant that is returned when the iterator has reached the end 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.

Methods

o first 
  public abstract char first()
Set the position to startIndex() and return the character at that position.

Returns:
the first character in the text
See Also:
startIndex
o last 
  public abstract char last()
Set the position to endIndex()-1, return the character at that position.

Returns:
the last character in the text
See Also:
endIndex
o 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
o 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 endIndex(), the current index is reset to endIndex() 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.
o 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 startIndex(), the current index is reset to startIndex() 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.
o 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 startIndex() to endIndex() - 1. An IllegalArgumentException is thrown if an invalid value is supplied.
Returns:
the character at the specified position.
o startIndex 
  public abstract int startIndex()
Return the start index of the text.

Returns:
the index at which the text begins.
o endIndex 
  public abstract int endIndex()
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.
o getIndex 
  public abstract int getIndex()
Return the current index.

Returns:
the current index.
o getText 
  public abstract String getText()
Return the text

o clone 
  public abstract Object clone()
Create a copy of this boundary

Returns:
A copy of this
Overrides:
clone in class Object 
All Packages  Class Hierarchy  This Package  Previous  Next  Index