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 * @since 1.1 102 * @see StringCharacterIterator 103 * @see AttributedCharacterIterator 104 */ 105 106 public interface CharacterIterator extends Cloneable 107 { 108 109 /** 110 * Constant that is returned when the iterator has reached either the end 111 * or the beginning of the text. The value is '\\uFFFF', the "not a 112 * character" value which should not occur in any valid Unicode string. 113 */ 114 public static final char DONE = '\uFFFF'; 115 116 /** 117 * Sets the position to getBeginIndex() and returns the character at that 118 * position. 119 * @return the first character in the text, or DONE if the text is empty 120 * @see #getBeginIndex() 121 */ first()122 public char first(); 123 124 /** 125 * Sets the position to getEndIndex()-1 (getEndIndex() if the text is empty) 126 * and returns the character at that position. 127 * @return the last character in the text, or DONE if the text is empty 128 * @see #getEndIndex() 129 */ last()130 public char last(); 131 132 /** 133 * Gets the character at the current position (as returned by getIndex()). 134 * @return the character at the current position or DONE if the current 135 * position is off the end of the text. 136 * @see #getIndex() 137 */ current()138 public char current(); 139 140 /** 141 * Increments the iterator's index by one and returns the character 142 * at the new index. If the resulting index is greater or equal 143 * to getEndIndex(), the current index is reset to getEndIndex() and 144 * a value of DONE is returned. 145 * @return the character at the new position or DONE if the new 146 * position is off the end of the text range. 147 */ next()148 public char next(); 149 150 /** 151 * Decrements the iterator's index by one and returns the character 152 * at the new index. If the current index is getBeginIndex(), the index 153 * remains at getBeginIndex() and a value of DONE is returned. 154 * @return the character at the new position or DONE if the current 155 * position is equal to getBeginIndex(). 156 */ previous()157 public char previous(); 158 159 /** 160 * Sets the position to the specified position in the text and returns that 161 * character. 162 * @param position the position within the text. Valid values range from 163 * getBeginIndex() to getEndIndex(). An IllegalArgumentException is thrown 164 * if an invalid value is supplied. 165 * @return the character at the specified position or DONE if the specified position is equal to getEndIndex() 166 */ setIndex(int position)167 public char setIndex(int position); 168 169 /** 170 * Returns the start index of the text. 171 * @return the index at which the text begins. 172 */ getBeginIndex()173 public int getBeginIndex(); 174 175 /** 176 * Returns the end index of the text. This index is the index of the first 177 * character following the end of the text. 178 * @return the index after the last character in the text 179 */ getEndIndex()180 public int getEndIndex(); 181 182 /** 183 * Returns the current index. 184 * @return the current index. 185 */ getIndex()186 public int getIndex(); 187 188 /** 189 * Create a copy of this iterator 190 * @return A copy of this 191 */ clone()192 public Object clone(); 193 194 } 195