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 * An ordered collection of <code>int</code> values.
021 *
022 * @see org.apache.commons.collections.primitives.adapters.IntListList
023 * @see org.apache.commons.collections.primitives.adapters.ListIntList
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 IntList extends IntCollection {
031    /** 
032     * Appends the specified element to the end of me
033     * (optional operation).  Returns <code>true</code>
034     * iff I changed as a result of this call.
035     * <p/>
036     * If a collection refuses to add the specified
037     * element for any reason other than that it already contains
038     * the element, it <i>must</i> throw an exception (rather than
039     * simply returning <tt>false</tt>).  This preserves the invariant
040     * that a collection always contains the specified element after 
041     * this call returns. 
042     * 
043     * @param element the value whose presence within me is to be ensured
044     * @return <code>true</code> iff I changed as a result of this call
045     * 
046     * @throws UnsupportedOperationException when this operation is not 
047     *         supported
048     * @throws IllegalArgumentException may be thrown if some aspect of the 
049     *         specified element prevents it from being added to me
050     */
051    boolean add(int element);
052       
053    /** 
054     * Inserts the specified element at the specified position 
055     * (optional operation). Shifts the element currently 
056     * at that position (if any) and any subsequent elements to the 
057     * right, increasing their indices.
058     * 
059     * @param index the index at which to insert the element
060     * @param element the value to insert
061     * 
062     * @throws UnsupportedOperationException when this operation is not 
063     *         supported
064     * @throws IllegalArgumentException if some aspect of the specified element 
065     *         prevents it from being added to me
066     * @throws IndexOutOfBoundsException if the specified index is out of range
067     */
068    void add(int index, int element);
069          
070    /** 
071     * Inserts all of the elements in the specified collection into me,
072     * at the specified position (optional operation).  Shifts the 
073     * element currently at that position (if any) and any subsequent 
074     * elements to the right, increasing their indices.  The new elements 
075     * will appear in the order that they are returned by the given 
076     * collection's {@link IntCollection#iterator iterator}.
077     * 
078     * @param index the index at which to insert the first element from 
079     *        the specified collection
080     * @param collection the {@link IntCollection IntCollection} of elements to add 
081     * @return <code>true</code> iff I changed as a result of this call
082     * 
083     * @throws UnsupportedOperationException when this operation is not 
084     *         supported
085     * @throws IndexOutOfBoundsException if the specified index is out of range
086     */
087    boolean addAll(int index, IntCollection collection);
088    
089    /**
090     * Returns <code>true</code> iff <i>that</i> is an <code>IntList</code>
091     * that contains the same elements in the same order as me.
092     * In other words, returns <code>true</code> iff <i>that</i> is
093     * an <code>IntList</code> that has the same {@link #size() size} as me,
094     * and for which the elements returned by its 
095     * {@link IntList#iterator iterator} are equal (<code>==</code>) to
096     * the corresponding elements within me.
097     * (This contract ensures that this method works properly across 
098     * different implementations of the <code>IntList</code> interface.)
099     * 
100     * @param that the object to compare to me
101     * @return <code>true</code> iff <i>that</i> is an <code>IntList</code>
102     *         that contains the same elements in the same order as me
103     */
104    boolean equals(Object that);
105    
106    /** 
107     * Returns the value of the element at the specified position 
108     * within me. 
109     * 
110     * @param index the index of the element to return
111     * @return the value of the element at the specified position
112     * @throws IndexOutOfBoundsException if the specified index is out of range
113     */
114    int get(int index);
115        
116    /**
117     * Returns my hash code.
118     * <p />
119     * The hash code of an <code>IntList</code> is defined to be the
120     * result of the following calculation:
121     * <pre> int hash = 1;
122     * for(IntIterator iter = iterator(); iter.hasNext(); ) {
123     *   hash = 31*hash + iter.next();
124     * }</pre>
125     * <p />
126     * This contract ensures that this method is consistent with 
127     * {@link #equals equals} and with the 
128     * {@link java.util.List#hashCode hashCode}
129     * method of a {@link java.util.List List} of {@link Integer}s. 
130     * 
131     * @return my hash code
132     */
133    int hashCode();
134
135    /** 
136     * Returns the index of the first occurrence 
137     * of the specified element within me, 
138     * or <code>-1</code> if I do not contain 
139     * the element. 
140     * 
141     * @param element the element to search for
142     * @return the smallest index of an element matching the specified value,
143     *         or <code>-1</code> if no such matching element can be found 
144     */
145    int indexOf(int element);
146     
147    /** 
148     * Returns an {@link IntIterator iterator} over all my elements,
149     * in the appropriate sequence.
150     * @return an {@link IntIterator iterator} over all my elements.
151     */
152    IntIterator iterator();
153
154    /** 
155     * Returns the index of the last occurrence 
156     * of the specified element within me, 
157     * or -1 if I do not contain the element. 
158     * 
159     * @param element the element to search for
160     * @return the largest index of an element matching the specified value,
161     *         or <code>-1</code> if no such matching element can be found 
162     */
163    int lastIndexOf(int element);
164    
165    /** 
166     * Returns a 
167     * {@link IntListIterator bidirectional iterator}
168     * over all my elements, in the appropriate sequence.
169     */
170    IntListIterator listIterator();
171    
172    /** 
173     * Returns a 
174     * {@link IntListIterator bidirectional iterator}
175     * over all my elements, in the appropriate sequence, 
176     * starting at the specified position. The 
177     * specified <i>index</i> indicates the first 
178     * element that would be returned by an initial 
179     * call to the 
180     * {@link IntListIterator#next next} 
181     * method. An initial call to the 
182     * {@link IntListIterator#previous previous}
183     * method would return the element with the specified 
184     * <i>index</i> minus one.
185     * 
186     * @throws IndexOutOfBoundsException if the specified index is out of range
187     */
188    IntListIterator listIterator(int index);
189    
190    /** 
191     * Removes the element at the specified position in 
192     * (optional operation).  Any subsequent elements 
193     * are shifted to the left, subtracting one from their 
194     * indices.  Returns the element that was removed.
195     * 
196     * @param index the index of the element to remove
197     * @return the value of the element that was removed
198     * 
199     * @throws UnsupportedOperationException when this operation is not 
200     *         supported
201     * @throws IndexOutOfBoundsException if the specified index is out of range
202     */
203    int removeElementAt(int index);
204   
205    /** 
206     * Replaces the element at the specified 
207     * position in me with the specified element
208     * (optional operation). 
209     * 
210     * @param index the index of the element to change
211     * @param element the value to be stored at the specified position
212     * @return the value previously stored at the specified position
213     * 
214     * @throws UnsupportedOperationException when this operation is not 
215     *         supported
216     * @throws IndexOutOfBoundsException if the specified index is out of range
217     */
218    int set(int index, int element);
219    
220    /** 
221     * Returns a view of the elements within me 
222     * between the specified <i>fromIndex</i>, inclusive, and 
223     * <i>toIndex</i>, exclusive.  The returned <code>IntList</code>
224     * is backed by me, so that any changes in 
225     * the returned list are reflected in me, and vice-versa.
226     * The returned list supports all of the optional operations
227     * that I support.
228     * <p/>
229     * Note that when <code><i>fromIndex</i> == <i>toIndex</i></code>,
230     * the returned list is initially empty, and when 
231     * <code><i>fromIndex</i> == 0 && <i>toIndex</i> == {@link #size() size()}</code>
232     * the returned list is my "improper" sublist, containing all my elements.
233     * <p/>
234     * The semantics of the returned list become undefined
235     * if I am structurally modified in any way other than 
236     * via the returned list.
237     * 
238     * @param fromIndex the smallest index (inclusive) in me that appears in 
239     *        the returned list
240     * @param toIndex the largest index (exclusive) in me that appears in the 
241     *        returned list
242     * @return a view of this list from <i>fromIndex</i> (inclusive) to 
243     *         <i>toIndex</i> (exclusive)
244     * 
245     * @throws IndexOutOfBoundsException if either specified index is out of range
246     */
247    IntList subList(int fromIndex, int toIndex);
248
249}