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 */
017package org.apache.commons.collections.primitives;
018
019/**
020 * A bi-directional iterator over <code>int</code> values.
021 *
022 * @see org.apache.commons.collections.primitives.adapters.IntListIteratorListIterator
023 * @see org.apache.commons.collections.primitives.adapters.ListIteratorIntListIterator
024 *
025 * @since Commons Primitives 1.0
026 * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $
027 * 
028 * @author Rodney Waldhoff 
029 */
030public interface IntListIterator extends IntIterator {
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(int 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    int 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    int 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(int element);
145}