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 */ 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