Interface java.text.CharacterIterator





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