IntList


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  package org.apache.commons.collections.primitives;
18  
19  /**
20   * An ordered collection of <code>int</code> values.
21   *
22   * @see org.apache.commons.collections.primitives.adapters.IntListList
23   * @see org.apache.commons.collections.primitives.adapters.ListIntList
24   *
25   * @since Commons Primitives 1.0
26   * @version $Revision: 480460 $ $Date: 2006-11-29 00:14:21 -0800 (Wed, 29 Nov 2006) $
27   * 
28   * @author Rodney Waldhoff 
29   */
30  public interface IntList extends IntCollection {
31      /** 
32       * Appends the specified element to the end of me
33       * (optional operation).  Returns <code>true</code>
34       * iff I changed as a result of this call.
35       * <p/>
36       * If a collection refuses to add the specified
37       * element for any reason other than that it already contains
38       * the element, it <i>must</i> throw an exception (rather than
39       * simply returning <tt>false</tt>).  This preserves the invariant
40       * that a collection always contains the specified element after 
41       * this call returns. 
42       * 
43       * @param element the value whose presence within me is to be ensured
44       * @return <code>true</code> iff I changed as a result of this call
45       * 
46       * @throws UnsupportedOperationException when this operation is not 
47       *         supported
48       * @throws IllegalArgumentException may be thrown if some aspect of the 
49       *         specified element prevents it from being added to me
50       */
51      boolean add(int element);
52         
53      /** 
54       * Inserts the specified element at the specified position 
55       * (optional operation). Shifts the element currently 
56       * at that position (if any) and any subsequent elements to the 
57       * right, increasing their indices.
58       * 
59       * @param index the index at which to insert the element
60       * @param element the value to insert
61       * 
62       * @throws UnsupportedOperationException when this operation is not 
63       *         supported
64       * @throws IllegalArgumentException if some aspect of the specified element 
65       *         prevents it from being added to me
66       * @throws IndexOutOfBoundsException if the specified index is out of range
67       */
68      void add(int index, int element);
69            
70      /** 
71       * Inserts all of the elements in the specified collection into me,
72       * at the specified position (optional operation).  Shifts the 
73       * element currently at that position (if any) and any subsequent 
74       * elements to the right, increasing their indices.  The new elements 
75       * will appear in the order that they are returned by the given 
76       * collection's {@link IntCollection#iterator iterator}.
77       * 
78       * @param index the index at which to insert the first element from 
79       *        the specified collection
80       * @param collection the {@link IntCollection IntCollection} of elements to add 
81       * @return <code>true</code> iff I changed as a result of this call
82       * 
83       * @throws UnsupportedOperationException when this operation is not 
84       *         supported
85       * @throws IndexOutOfBoundsException if the specified index is out of range
86       */
87      boolean addAll(int index, IntCollection collection);
88      
89      /**
90       * Returns <code>true</code> iff <i>that</i> is an <code>IntList</code>
91       * that contains the same elements in the same order as me.
92       * In other words, returns <code>true</code> iff <i>that</i> is
93       * an <code>IntList</code> that has the same {@link #size() size} as me,
94       * and for which the elements returned by its 
95       * {@link IntList#iterator iterator} are equal (<code>==</code>) to
96       * the corresponding elements within me.
97       * (This contract ensures that this method works properly across 
98       * different implementations of the <code>IntList</code> interface.)
99       * 
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 }
250
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags