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>boolean</code> values.
021     *
022     * @see org.apache.commons.collections.primitives.adapters.BooleanListIteratorListIterator
023     * @see org.apache.commons.collections.primitives.adapters.BooleanIteratorBooleanListIterator
024     *
025     * @since Commons Primitives 1.1
026     * @version $Revision: 480460 $ $Date: 2006-11-29 09:14:21 +0100 (Wed, 29 Nov 2006) $
027     */
028    public interface BooleanListIterator extends BooleanIterator {
029        /**
030         * Inserts the specified element into my underlying collection
031         * (optional operation).
032         * The element is inserted immediately before the next element 
033         * that would have been returned by {@link #next}, if any,
034         * and immediately after the next element that would have been 
035         * returned by {@link #previous}, if any.
036         * <p/>
037         * The new element is inserted immediately before the implied
038         * cursor. A subsequent call to {@link #previous} will return
039         * the added element, a subsequent call to {@link #next} will
040         * be unaffected.  This call increases by one the value that
041         * would be returned by a call to {@link #nextIndex} or 
042         * {@link #previousIndex}.
043         * 
044         * @param element the value to be inserted
045         * 
046         * @throws UnsupportedOperationException when this operation is not 
047         *         supported
048         * @throws IllegalArgumentException if some aspect of the specified element 
049         *         prevents it from being added
050         */
051        void add(boolean element);
052    
053        /** 
054         * Returns <code>true</code> iff I have more elements when traversed in
055         * the forward direction. (In other words, returns <code>true</code> iff
056         * a call to {@link #next} will return an element rather than throwing
057         * an exception.
058         * 
059         * @return <code>true</code> iff I have more elements when 
060         *         traversed in the forward direction
061         */
062        boolean hasNext();
063        
064        /** 
065         * Returns <code>true</code> iff I have more elements when traversed
066         * in the reverse direction. (In other words, returns <code>true</code>
067         * iff a call to {@link #previous} will return an element rather than
068         * throwing an exception.
069         * 
070         * @return <code>true</code> iff I have more elements when traversed
071         *         in the reverse direction
072         */
073        boolean hasPrevious();
074    
075        /** 
076         * Returns the next element in me when traversed in the
077         * forward direction.
078         * 
079         * @return the next element in me
080         * @throws java.util.NoSuchElementException if there is no next element
081         */          
082        boolean next();
083        
084        /** 
085         * Returns the index of the element that would be returned
086         * by a subsequent call to {@link #next}, or the number 
087         * of elements in my iteration if I have no next element.
088         * 
089         * @return the index of the next element in me
090         */          
091        int nextIndex();
092    
093        /** 
094         * Returns the next element in me when traversed in the
095         * reverse direction.
096         * 
097         * @return the previous element in me
098         * @throws java.util.NoSuchElementException if there is no previous element
099         */          
100        boolean previous();
101    
102        /** 
103         * Returns the index of the element that would be returned
104         * by a subsequent call to {@link #previous}, or 
105         * <code>-1</code> if I have no previous element.
106         * 
107         * @return the index of the previous element in me
108         */          
109        int previousIndex();
110    
111        /** 
112         * Removes from my underlying collection the last 
113         * element returned by {@link #next} or {@link #previous}
114         * (optional operation). 
115         * 
116         * @throws UnsupportedOperationException if this operation is not 
117         *         supported
118         * @throws IllegalStateException if neither {@link #next} nor
119         *         {@link #previous} has yet been called, or 
120         *         {@link #remove} or {@link #add} has already been called since 
121         *         the last call to {@link #next} or {@link #previous}.
122         */          
123        void remove();
124    
125        /** 
126         * Replaces in my underlying collection the last 
127         * element returned by {@link #next} or {@link #previous}
128         * with the specified value (optional operation). 
129         * 
130         * @param element the value to replace the last returned element with
131         * @throws UnsupportedOperationException if this operation is not 
132         *         supported
133         * @throws IllegalStateException if neither {@link #next} nor
134         *         {@link #previous} has yet been called, or 
135         *         {@link #remove} or {@link #add} has already been called since 
136         *         the last call to {@link #next} or {@link #previous}.
137         * @throws IllegalArgumentException if some aspect of the specified element 
138         *         prevents it from being added
139         */          
140        void set(boolean element);
141    }