45 * This interface defines a protocol for bidirectional iteration over text. 46 * The iterator iterates over a bounded sequence of characters. Characters 47 * are indexed with values beginning with the value returned by getBeginIndex() and 48 * continuing through the value returned by getEndIndex()-1. 49 * <p> 50 * Iterators maintain a current character index, whose valid range is from 51 * getBeginIndex() to getEndIndex(); the value getEndIndex() is included to allow 52 * handling of zero-length text ranges and for historical reasons. 53 * The current index can be retrieved by calling getIndex() and set directly 54 * by calling setIndex(), first(), and last(). 55 * <p> 56 * The methods previous() and next() are used for iteration. They return DONE if 57 * they would move outside the range from getBeginIndex() to getEndIndex() -1, 58 * signaling that the iterator has reached the end of the sequence. DONE is 59 * also returned by other methods to indicate that the current index is 60 * outside this range. 61 * 62 * <P>Examples:<P> 63 * 64 * Traverse the text from start to finish 65 * <pre> 66 * public void traverseForward(CharacterIterator iter) { 67 * for(char c = iter.first(); c != CharacterIterator.DONE; c = iter.next()) { 68 * processChar(c); 69 * } 70 * } 71 * </pre> 72 * 73 * Traverse the text backwards, from end to start 74 * <pre> 75 * public void traverseBackward(CharacterIterator iter) { 76 * for(char c = iter.last(); c != CharacterIterator.DONE; c = iter.previous()) { 77 * processChar(c); 78 * } 79 * } 80 * </pre> 81 * 82 * Traverse both forward and backward from a given position in the text. 83 * Calls to notBoundary() in this example represents some 84 * additional stopping criteria. 85 * <pre> 86 * public void traverseOut(CharacterIterator iter, int pos) { 87 * for (char c = iter.setIndex(pos); 88 * c != CharacterIterator.DONE && notBoundary(c); 89 * c = iter.next()) { 90 * } 91 * int end = iter.getIndex(); 92 * for (char c = iter.setIndex(pos); 93 * c != CharacterIterator.DONE && notBoundary(c); 94 * c = iter.previous()) { 95 * } 96 * int start = iter.getIndex(); 97 * processSection(start, end); 98 * } 99 * </pre> 100 * 101 * @see StringCharacterIterator 102 * @see AttributedCharacterIterator 103 */ 104 105 public interface CharacterIterator extends Cloneable 106 { 107 108 /** 109 * Constant that is returned when the iterator has reached either the end 110 * or the beginning of the text. The value is '\\uFFFF', the "not a 111 * character" value which should not occur in any valid Unicode string. 112 */ 113 public static final char DONE = '\uFFFF'; 114 115 /** 116 * Sets the position to getBeginIndex() and returns the character at that 117 * position. 118 * @return the first character in the text, or DONE if the text is empty 119 * @see #getBeginIndex() | 45 * This interface defines a protocol for bidirectional iteration over text. 46 * The iterator iterates over a bounded sequence of characters. Characters 47 * are indexed with values beginning with the value returned by getBeginIndex() and 48 * continuing through the value returned by getEndIndex()-1. 49 * <p> 50 * Iterators maintain a current character index, whose valid range is from 51 * getBeginIndex() to getEndIndex(); the value getEndIndex() is included to allow 52 * handling of zero-length text ranges and for historical reasons. 53 * The current index can be retrieved by calling getIndex() and set directly 54 * by calling setIndex(), first(), and last(). 55 * <p> 56 * The methods previous() and next() are used for iteration. They return DONE if 57 * they would move outside the range from getBeginIndex() to getEndIndex() -1, 58 * signaling that the iterator has reached the end of the sequence. DONE is 59 * also returned by other methods to indicate that the current index is 60 * outside this range. 61 * 62 * <P>Examples:<P> 63 * 64 * Traverse the text from start to finish 65 * <pre>{@code 66 * public void traverseForward(CharacterIterator iter) { 67 * for(char c = iter.first(); c != CharacterIterator.DONE; c = iter.next()) { 68 * processChar(c); 69 * } 70 * } 71 * }</pre> 72 * 73 * Traverse the text backwards, from end to start 74 * <pre>{@code 75 * public void traverseBackward(CharacterIterator iter) { 76 * for(char c = iter.last(); c != CharacterIterator.DONE; c = iter.previous()) { 77 * processChar(c); 78 * } 79 * } 80 * }</pre> 81 * 82 * Traverse both forward and backward from a given position in the text. 83 * Calls to notBoundary() in this example represents some 84 * additional stopping criteria. 85 * <pre>{@code 86 * public void traverseOut(CharacterIterator iter, int pos) { 87 * for (char c = iter.setIndex(pos); 88 * c != CharacterIterator.DONE && notBoundary(c); 89 * c = iter.next()) { 90 * } 91 * int end = iter.getIndex(); 92 * for (char c = iter.setIndex(pos); 93 * c != CharacterIterator.DONE && notBoundary(c); 94 * c = iter.previous()) { 95 * } 96 * int start = iter.getIndex(); 97 * processSection(start, end); 98 * } 99 * }</pre> 100 * 101 * @see StringCharacterIterator 102 * @see AttributedCharacterIterator 103 */ 104 105 public interface CharacterIterator extends Cloneable 106 { 107 108 /** 109 * Constant that is returned when the iterator has reached either the end 110 * or the beginning of the text. The value is '\\uFFFF', the "not a 111 * character" value which should not occur in any valid Unicode string. 112 */ 113 public static final char DONE = '\uFFFF'; 114 115 /** 116 * Sets the position to getBeginIndex() and returns the character at that 117 * position. 118 * @return the first character in the text, or DONE if the text is empty 119 * @see #getBeginIndex() |