    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 - Version 1.1.8 of Java Platform API Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1995-1999 Sun Microsystems, Inc. 901 San Antonio Road,
Palo Alto, California, 94303, U.S.A. All Rights Reserved.