001 /*
002 * Copyright 1996-2000 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 /*
027 * (C) Copyright Taligent, Inc. 1996, 1997 - All Rights Reserved
028 * (C) Copyright IBM Corp. 1996 - 1998 - All Rights Reserved
029 *
030 * The original version of this source code and documentation
031 * is copyrighted and owned by Taligent, Inc., a wholly-owned
032 * subsidiary of IBM. These materials are provided under terms
033 * of a License Agreement between Taligent and Sun. This technology
034 * is protected by multiple US and International patents.
035 *
036 * This notice and attribution to Taligent may not be removed.
037 * Taligent is a registered trademark of Taligent, Inc.
038 *
039 */
040
041 package java.text;
042
043 /**
044 * This interface defines a protocol for bidirectional iteration over text.
045 * The iterator iterates over a bounded sequence of characters. Characters
046 * are indexed with values beginning with the value returned by getBeginIndex() and
047 * continuing through the value returned by getEndIndex()-1.
048 * <p>
049 * Iterators maintain a current character index, whose valid range is from
050 * getBeginIndex() to getEndIndex(); the value getEndIndex() is included to allow
051 * handling of zero-length text ranges and for historical reasons.
052 * The current index can be retrieved by calling getIndex() and set directly
053 * by calling setIndex(), first(), and last().
054 * <p>
055 * The methods previous() and next() are used for iteration. They return DONE if
056 * they would move outside the range from getBeginIndex() to getEndIndex() -1,
057 * signaling that the iterator has reached the end of the sequence. DONE is
058 * also returned by other methods to indicate that the current index is
059 * outside this range.
060 *
061 * <P>Examples:<P>
062 *
063 * Traverse the text from start to finish
064 * <pre>
065 * public void traverseForward(CharacterIterator iter) {
066 * for(char c = iter.first(); c != CharacterIterator.DONE; c = iter.next()) {
067 * processChar(c);
068 * }
069 * }
070 * </pre>
071 *
072 * Traverse the text backwards, from end to start
073 * <pre>
074 * public void traverseBackward(CharacterIterator iter) {
075 * for(char c = iter.last(); c != CharacterIterator.DONE; c = iter.previous()) {
076 * processChar(c);
077 * }
078 * }
079 * </pre>
080 *
081 * Traverse both forward and backward from a given position in the text.
082 * Calls to notBoundary() in this example represents some
083 * additional stopping criteria.
084 * <pre>
085 * public void traverseOut(CharacterIterator iter, int pos) {
086 * for (char c = iter.setIndex(pos);
087 * c != CharacterIterator.DONE && notBoundary(c);
088 * c = iter.next()) {
089 * }
090 * int end = iter.getIndex();
091 * for (char c = iter.setIndex(pos);
092 * c != CharacterIterator.DONE && notBoundary(c);
093 * c = iter.previous()) {
094 * }
095 * int start = iter.getIndex();
096 * processSection(start, end);
097 * }
098 * </pre>
099 *
100 * @see StringCharacterIterator
101 * @see AttributedCharacterIterator
102 */
103
104 public interface CharacterIterator extends Cloneable {
105
106 /**
107 * Constant that is returned when the iterator has reached either the end
108 * or the beginning of the text. The value is '\\uFFFF', the "not a
109 * character" value which should not occur in any valid Unicode string.
110 */
111 public static final char DONE = '\uFFFF';
112
113 /**
114 * Sets the position to getBeginIndex() and returns the character at that
115 * position.
116 * @return the first character in the text, or DONE if the text is empty
117 * @see #getBeginIndex()
118 */
119 public char first();
120
121 /**
122 * Sets the position to getEndIndex()-1 (getEndIndex() if the text is empty)
123 * and returns the character at that position.
124 * @return the last character in the text, or DONE if the text is empty
125 * @see #getEndIndex()
126 */
127 public char last();
128
129 /**
130 * Gets the character at the current position (as returned by getIndex()).
131 * @return the character at the current position or DONE if the current
132 * position is off the end of the text.
133 * @see #getIndex()
134 */
135 public char current();
136
137 /**
138 * Increments the iterator's index by one and returns the character
139 * at the new index. If the resulting index is greater or equal
140 * to getEndIndex(), the current index is reset to getEndIndex() and
141 * a value of DONE is returned.
142 * @return the character at the new position or DONE if the new
143 * position is off the end of the text range.
144 */
145 public char next();
146
147 /**
148 * Decrements the iterator's index by one and returns the character
149 * at the new index. If the current index is getBeginIndex(), the index
150 * remains at getBeginIndex() and a value of DONE is returned.
151 * @return the character at the new position or DONE if the current
152 * position is equal to getBeginIndex().
153 */
154 public char previous();
155
156 /**
157 * Sets the position to the specified position in the text and returns that
158 * character.
159 * @param position the position within the text. Valid values range from
160 * getBeginIndex() to getEndIndex(). An IllegalArgumentException is thrown
161 * if an invalid value is supplied.
162 * @return the character at the specified position or DONE if the specified position is equal to getEndIndex()
163 */
164 public char setIndex(int position);
165
166 /**
167 * Returns the start index of the text.
168 * @return the index at which the text begins.
169 */
170 public int getBeginIndex();
171
172 /**
173 * Returns the end index of the text. This index is the index of the first
174 * character following the end of the text.
175 * @return the index after the last character in the text
176 */
177 public int getEndIndex();
178
179 /**
180 * Returns the current index.
181 * @return the current index.
182 */
183 public int getIndex();
184
185 /**
186 * Create a copy of this iterator
187 * @return A copy of this
188 */
189 public Object clone();
190
191 }
|