KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > text > CharacterIterator


1 /*
2  * @(#)CharacterIterator.java 1.19 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 /*
9  * (C) Copyright Taligent, Inc. 1996, 1997 - All Rights Reserved
10  * (C) Copyright IBM Corp. 1996 - 1998 - All Rights Reserved
11  *
12  * The original version of this source code and documentation
13  * is copyrighted and owned by Taligent, Inc., a wholly-owned
14  * subsidiary of IBM. These materials are provided under terms
15  * of a License Agreement between Taligent and Sun. This technology
16  * is protected by multiple US and International patents.
17  *
18  * This notice and attribution to Taligent may not be removed.
19  * Taligent is a registered trademark of Taligent, Inc.
20  *
21  */
22
23 package java.text;
24
25
26 /**
27  * This interface defines a protocol for bidirectional iteration over text.
28  * The iterator iterates over a bounded sequence of characters. Characters
29  * are indexed with values beginning with the value returned by getBeginIndex() and
30  * continuing through the value returned by getEndIndex()-1.
31  * <p>
32  * Iterators maintain a current character index, whose valid range is from
33  * getBeginIndex() to getEndIndex(); the value getEndIndex() is included to allow
34  * handling of zero-length text ranges and for historical reasons.
35  * The current index can be retrieved by calling getIndex() and set directly
36  * by calling setIndex(), first(), and last().
37  * <p>
38  * The methods previous() and next() are used for iteration. They return DONE if
39  * they would move outside the range from getBeginIndex() to getEndIndex() -1,
40  * signaling that the iterator has reached the end of the sequence. DONE is
41  * also returned by other methods to indicate that the current index is
42  * outside this range.
43  *
44  * <P>Examples:<P>
45  *
46  * Traverse the text from start to finish
47  * <pre>
48  * public void traverseForward(CharacterIterator iter) {
49  * for(char c = iter.first(); c != CharacterIterator.DONE; c = iter.next()) {
50  * processChar(c);
51  * }
52  * }
53  * </pre>
54  *
55  * Traverse the text backwards, from end to start
56  * <pre>
57  * public void traverseBackward(CharacterIterator iter) {
58  * for(char c = iter.last(); c != CharacterIterator.DONE; c = iter.previous()) {
59  * processChar(c);
60  * }
61  * }
62  * </pre>
63  *
64  * Traverse both forward and backward from a given position in the text.
65  * Calls to notBoundary() in this example represents some
66  * additional stopping criteria.
67  * <pre>
68  * public void traverseOut(CharacterIterator iter, int pos) {
69  * for (char c = iter.setIndex(pos);
70  * c != CharacterIterator.DONE && notBoundary(c);
71  * c = iter.next()) {
72  * }
73  * int end = iter.getIndex();
74  * for (char c = iter.setIndex(pos);
75  * c != CharacterIterator.DONE && notBoundary(c);
76  * c = iter.previous()) {
77  * }
78  * int start = iter.getIndex();
79  * processSection(start, end);
80  * }
81  * </pre>
82  *
83  * @see StringCharacterIterator
84  * @see AttributedCharacterIterator
85  */
86
87 public interface CharacterIterator extends Cloneable JavaDoc
88 {
89
90     /**
91      * Constant that is returned when the iterator has reached either the end
92      * or the beginning of the text. The value is '\\uFFFF', the "not a
93      * character" value which should not occur in any valid Unicode string.
94      */
95     public static final char DONE = '\uFFFF';
96
97     /**
98      * Sets the position to getBeginIndex() and returns the character at that
99      * position.
100      * @return the first character in the text, or DONE if the text is empty
101      * @see #getBeginIndex()
102      */
103     public char first();
104
105     /**
106      * Sets the position to getEndIndex()-1 (getEndIndex() if the text is empty)
107      * and returns the character at that position.
108      * @return the last character in the text, or DONE if the text is empty
109      * @see #getEndIndex()
110      */
111     public char last();
112
113     /**
114      * Gets the character at the current position (as returned by getIndex()).
115      * @return the character at the current position or DONE if the current
116      * position is off the end of the text.
117      * @see #getIndex()
118      */
119     public char current();
120
121     /**
122      * Increments the iterator's index by one and returns the character
123      * at the new index. If the resulting index is greater or equal
124      * to getEndIndex(), the current index is reset to getEndIndex() and
125      * a value of DONE is returned.
126      * @return the character at the new position or DONE if the new
127      * position is off the end of the text range.
128      */
129     public char next();
130
131     /**
132      * Decrements the iterator's index by one and returns the character
133      * at the new index. If the current index is getBeginIndex(), the index
134      * remains at getBeginIndex() and a value of DONE is returned.
135      * @return the character at the new position or DONE if the current
136      * position is equal to getBeginIndex().
137      */
138     public char previous();
139
140     /**
141      * Sets the position to the specified position in the text and returns that
142      * character.
143      * @param position the position within the text. Valid values range from
144      * getBeginIndex() to getEndIndex(). An IllegalArgumentException is thrown
145      * if an invalid value is supplied.
146      * @return the character at the specified position or DONE if the specified position is equal to getEndIndex()
147      */
148     public char setIndex(int position);
149
150     /**
151      * Returns the start index of the text.
152      * @return the index at which the text begins.
153      */
154     public int getBeginIndex();
155
156     /**
157      * Returns the end index of the text. This index is the index of the first
158      * character following the end of the text.
159      * @return the index after the last character in the text
160      */
161     public int getEndIndex();
162
163     /**
164      * Returns the current index.
165      * @return the current index.
166      */
167     public int getIndex();
168
169     /**
170      * Create a copy of this iterator
171      * @return A copy of this
172      */
173     public Object JavaDoc clone();
174
175 }
176
Popular Tags