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 03:14:21 -0500 (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 }