Home | History | Annotate | Download | only in text 
      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