001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *     http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.commons.collections.primitives;
018    
019    /**
020     * A bi-directional iterator over <code>char</code> values.
021     *
022     * @see org.apache.commons.collections.primitives.adapters.CharListIteratorListIterator
023     * @see org.apache.commons.collections.primitives.adapters.ListIteratorCharListIterator
024     *
025     * @since Commons Primitives 1.0
026     * @version $Revision: 480460 $ $Date: 2006-11-29 09:14:21 +0100 (Wed, 29 Nov 2006) $
027     * 
028     * @author Rodney Waldhoff 
029     */
030    public interface CharListIterator extends CharIterator {
031        /**
032         * Inserts the specified element into my underlying collection
033         * (optional operation).
034         * The element is inserted immediately before the next element 
035         * that would have been returned by {@link #next}, if any,
036         * and immediately after the next element that would have been 
037         * returned by {@link #previous}, if any.
038         * <p/>
039         * The new element is inserted immediately before the implied
040         * cursor. A subsequent call to {@link #previous} will return
041         * the added element, a subsequent call to {@link #next} will
042         * be unaffected.  This call increases by one the value that
043         * would be returned by a call to {@link #nextIndex} or 
044         * {@link #previousIndex}.
045         * 
046         * @param element the value to be inserted
047         * 
048         * @throws UnsupportedOperationException when this operation is not 
049         *         supported
050         * @throws IllegalArgumentException if some aspect of the specified element 
051         *         prevents it from being added
052         */
053        void add(char element);
054    
055        /** 
056         * Returns <code>true</code> iff I have more elements
057         * when traversed in the forward direction. 
058         * (In other words, returns <code>true</code> iff 
059         * a call to {@link #next} will return an element
060         * rather than throwing an exception.
061         * 
062         * @return <code>true</code> iff I have more elements when 
063         *         traversed in the forward direction
064         */
065        boolean hasNext();
066        
067        /** 
068         * Returns <code>true</code> iff I have more elements
069         * when traversed in the reverse direction. 
070         * (In other words, returns <code>true</code> iff 
071         * a call to {@link #previous} will return an element
072         * rather than throwing an exception.
073         * 
074         * @return <code>true</code> iff I have more elements when 
075         *         traversed in the reverse direction
076         */
077        boolean hasPrevious();
078    
079        /** 
080         * Returns the next element in me when traversed in the
081         * forward direction.
082         * 
083         * @return the next element in me
084         * @throws java.util.NoSuchElementException if there is no next element
085         */          
086        char next();
087        
088        /** 
089         * Returns the index of the element that would be returned
090         * by a subsequent call to {@link #next}, or the number 
091         * of elements in my iteration if I have no next element.
092         * 
093         * @return the index of the next element in me
094         */          
095        int nextIndex();
096    
097        /** 
098         * Returns the next element in me when traversed in the
099         * reverse direction.
100         * 
101         * @return the previous element in me
102         * @throws java.util.NoSuchElementException if there is no previous element
103         */          
104        char previous();
105    
106        /** 
107         * Returns the index of the element that would be returned
108         * by a subsequent call to {@link #previous}, or 
109         * <code>-1</code> if I have no previous element.
110         * 
111         * @return the index of the previous element in me
112         */          
113        int previousIndex();
114    
115        /** 
116         * Removes from my underlying collection the last 
117         * element returned by {@link #next} or {@link #previous}
118         * (optional operation). 
119         * 
120         * @throws UnsupportedOperationException if this operation is not 
121         *         supported
122         * @throws IllegalStateException if neither {@link #next} nor
123         *         {@link #previous} has yet been called, or 
124         *         {@link #remove} or {@link #add} has already been called since 
125         *         the last call to {@link #next} or {@link #previous}.
126         */          
127        void remove();
128    
129        /** 
130         * Replaces in my underlying collection the last 
131         * element returned by {@link #next} or {@link #previous}
132         * with the specified value (optional operation). 
133         * 
134         * @param element the value to replace the last returned element with
135         * @throws UnsupportedOperationException if this operation is not 
136         *         supported
137         * @throws IllegalStateException if neither {@link #next} nor
138         *         {@link #previous} has yet been called, or 
139         *         {@link #remove} or {@link #add} has already been called since 
140         *         the last call to {@link #next} or {@link #previous}.
141         * @throws IllegalArgumentException if some aspect of the specified element 
142         *         prevents it from being added
143         */          
144        void set(char element);
145    }