1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one or more
3  * contributor license agreements.  See the NOTICE file distributed with
4  * this work for additional information regarding copyright ownership.
5  * The ASF licenses this file to You under the Apache License, Version 2.0
6  * (the "License"); you may not use this file except in compliance with
7  * the License.  You may obtain a copy of the License at
8  *
9  *     http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 
18 package java.text;
19 
20 /**
21  * An interface for the bidirectional iteration over a group of characters. The
22  * iteration starts at the begin index in the group of characters and continues
23  * to one index before the end index.
24  */
25 public interface CharacterIterator extends Cloneable {
26 
27     /**
28      * A constant which indicates that there is no character at the current
29      * index.
30      */
31     public static final char DONE = '\uffff';
32 
33     /**
34      * Returns a new {@code CharacterIterator} with the same properties.
35      *
36      * @return a shallow copy of this character iterator.
37      *
38      * @see java.lang.Cloneable
39      */
clone()40     public Object clone();
41 
42     /**
43      * Returns the character at the current index.
44      *
45      * @return the current character, or {@code DONE} if the current index is
46      *         past the beginning or end of the sequence.
47      */
current()48     public char current();
49 
50     /**
51      * Sets the current position to the begin index and returns the character at
52      * the new position.
53      *
54      * @return the character at the begin index.
55      */
first()56     public char first();
57 
58     /**
59      * Returns the begin index.
60      *
61      * @return the index of the first character of the iteration.
62      */
getBeginIndex()63     public int getBeginIndex();
64 
65     /**
66      * Returns the end index.
67      *
68      * @return the index one past the last character of the iteration.
69      */
getEndIndex()70     public int getEndIndex();
71 
72     /**
73      * Returns the current index.
74      *
75      * @return the current index.
76      */
getIndex()77     public int getIndex();
78 
79     /**
80      * Sets the current position to the end index - 1 and returns the character
81      * at the new position.
82      *
83      * @return the character before the end index.
84      */
last()85     public char last();
86 
87     /**
88      * Increments the current index and returns the character at the new index.
89      *
90      * @return the character at the next index, or {@code DONE} if the next
91      *         index would be past the end.
92      */
next()93     public char next();
94 
95     /**
96      * Decrements the current index and returns the character at the new index.
97      *
98      * @return the character at the previous index, or {@code DONE} if the
99      *         previous index would be past the beginning.
100      */
previous()101     public char previous();
102 
103     /**
104      * Sets the current index to a new position and returns the character at the
105      * new index.
106      *
107      * @param location
108      *            the new index that this character iterator is set to.
109      * @return the character at the new index, or {@code DONE} if the index is
110      *         past the end.
111      * @throws IllegalArgumentException
112      *         if {@code location} is less than the begin index or greater than
113      *         the end index.
114      */
setIndex(int location)115     public char setIndex(int location);
116 }
117