1 /* 2 * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 /* 27 * (C) Copyright Taligent, Inc. 1996, 1997 - All Rights Reserved 28 * (C) Copyright IBM Corp. 1996 - 1998 - All Rights Reserved 29 * 30 * The original version of this source code and documentation 31 * is copyrighted and owned by Taligent, Inc., a wholly-owned 32 * subsidiary of IBM. These materials are provided under terms 33 * of a License Agreement between Taligent and Sun. This technology 34 * is protected by multiple US and International patents. 35 * 36 * This notice and attribution to Taligent may not be removed. 37 * Taligent is a registered trademark of Taligent, Inc. 38 * 39 */ 40 41 package java.text; 42 43 44 /** 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() 120 */ first()121 public char first(); 122 123 /** 124 * Sets the position to getEndIndex()-1 (getEndIndex() if the text is empty) 125 * and returns the character at that position. 126 * @return the last character in the text, or DONE if the text is empty 127 * @see #getEndIndex() 128 */ last()129 public char last(); 130 131 /** 132 * Gets the character at the current position (as returned by getIndex()). 133 * @return the character at the current position or DONE if the current 134 * position is off the end of the text. 135 * @see #getIndex() 136 */ current()137 public char current(); 138 139 /** 140 * Increments the iterator's index by one and returns the character 141 * at the new index. If the resulting index is greater or equal 142 * to getEndIndex(), the current index is reset to getEndIndex() and 143 * a value of DONE is returned. 144 * @return the character at the new position or DONE if the new 145 * position is off the end of the text range. 146 */ next()147 public char next(); 148 149 /** 150 * Decrements the iterator's index by one and returns the character 151 * at the new index. If the current index is getBeginIndex(), the index 152 * remains at getBeginIndex() and a value of DONE is returned. 153 * @return the character at the new position or DONE if the current 154 * position is equal to getBeginIndex(). 155 */ previous()156 public char previous(); 157 158 /** 159 * Sets the position to the specified position in the text and returns that 160 * character. 161 * @param position the position within the text. Valid values range from 162 * getBeginIndex() to getEndIndex(). An IllegalArgumentException is thrown 163 * if an invalid value is supplied. 164 * @return the character at the specified position or DONE if the specified position is equal to getEndIndex() 165 */ setIndex(int position)166 public char setIndex(int position); 167 168 /** 169 * Returns the start index of the text. 170 * @return the index at which the text begins. 171 */ getBeginIndex()172 public int getBeginIndex(); 173 174 /** 175 * Returns the end index of the text. This index is the index of the first 176 * character following the end of the text. 177 * @return the index after the last character in the text 178 */ getEndIndex()179 public int getEndIndex(); 180 181 /** 182 * Returns the current index. 183 * @return the current index. 184 */ getIndex()185 public int getIndex(); 186 187 /** 188 * Create a copy of this iterator 189 * @return A copy of this 190 */ clone()191 public Object clone(); 192 193 } 194