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
18package 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 */
25public 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     */
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     */
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     */
56    public char first();
57
58    /**
59     * Returns the begin index.
60     *
61     * @return the index of the first character of the iteration.
62     */
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     */
70    public int getEndIndex();
71
72    /**
73     * Returns the current index.
74     *
75     * @return the current index.
76     */
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     */
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     */
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     */
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     */
115    public char setIndex(int location);
116}
117