001: /*
002: * $Header: /home/cvs/jakarta-commons/primitives/src/java/org/apache/commons/collections/primitives/IntList.java,v 1.3 2003/10/16 20:49:36 scolebourne Exp $
003: * ====================================================================
004: * The Apache Software License, Version 1.1
005: *
006: * Copyright (c) 2002-2003 The Apache Software Foundation. All rights
007: * reserved.
008: *
009: * Redistribution and use in source and binary forms, with or without
010: * modification, are permitted provided that the following conditions
011: * are met:
012: *
013: * 1. Redistributions of source code must retain the above copyright
014: * notice, this list of conditions and the following disclaimer.
015: *
016: * 2. Redistributions in binary form must reproduce the above copyright
017: * notice, this list of conditions and the following disclaimer in
018: * the documentation and/or other materials provided with the
019: * distribution.
020: *
021: * 3. The end-user documentation included with the redistribution, if
022: * any, must include the following acknowledgement:
023: * "This product includes software developed by the
024: * Apache Software Foundation (http://www.apache.org/)."
025: * Alternately, this acknowledgement may appear in the software itself,
026: * if and wherever such third-party acknowledgements normally appear.
027: *
028: * 4. The names "The Jakarta Project", "Commons", and "Apache Software
029: * Foundation" must not be used to endorse or promote products derived
030: * from this software without prior written permission. For written
031: * permission, please contact apache@apache.org.
032: *
033: * 5. Products derived from this software may not be called "Apache"
034: * nor may "Apache" appear in their names without prior written
035: * permission of the Apache Software Foundation.
036: *
037: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
038: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
039: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
040: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
041: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
042: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
043: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
044: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
045: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
046: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
047: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
048: * SUCH DAMAGE.
049: * ====================================================================
050: *
051: * This software consists of voluntary contributions made by many
052: * individuals on behalf of the Apache Software Foundation. For more
053: * information on the Apache Software Foundation, please see
054: * <http://www.apache.org/>.
055: *
056: */
057:
058: package org.apache.commons.collections.primitives;
059:
060: /**
061: * An ordered collection of <code>int</code> values.
062: *
063: * @see org.apache.commons.collections.primitives.adapters.IntListList
064: * @see org.apache.commons.collections.primitives.adapters.ListIntList
065: *
066: * @since Commons Primitives 1.0
067: * @version $Revision: 1.3 $ $Date: 2003/10/16 20:49:36 $
068: *
069: * @author Rodney Waldhoff
070: */
071: public interface IntList extends IntCollection {
072: /**
073: * Appends the specified element to the end of me
074: * (optional operation). Returns <code>true</code>
075: * iff I changed as a result of this call.
076: * <p/>
077: * If a collection refuses to add the specified
078: * element for any reason other than that it already contains
079: * the element, it <i>must</i> throw an exception (rather than
080: * simply returning <tt>false</tt>). This preserves the invariant
081: * that a collection always contains the specified element after
082: * this call returns.
083: *
084: * @param element the value whose presence within me is to be ensured
085: * @return <code>true</code> iff I changed as a result of this call
086: *
087: * @throws UnsupportedOperationException when this operation is not
088: * supported
089: * @throws IllegalArgumentException may be thrown if some aspect of the
090: * specified element prevents it from being added to me
091: */
092: boolean add(int element);
093:
094: /**
095: * Inserts the specified element at the specified position
096: * (optional operation). Shifts the element currently
097: * at that position (if any) and any subsequent elements to the
098: * right, increasing their indices.
099: *
100: * @param index the index at which to insert the element
101: * @param element the value to insert
102: *
103: * @throws UnsupportedOperationException when this operation is not
104: * supported
105: * @throws IllegalArgumentException if some aspect of the specified element
106: * prevents it from being added to me
107: * @throws IndexOutOfBoundsException if the specified index is out of range
108: */
109: void add(int index, int element);
110:
111: /**
112: * Inserts all of the elements in the specified collection into me,
113: * at the specified position (optional operation). Shifts the
114: * element currently at that position (if any) and any subsequent
115: * elements to the right, increasing their indices. The new elements
116: * will appear in the order that they are returned by the given
117: * collection's {@link IntCollection#iterator iterator}.
118: *
119: * @param index the index at which to insert the first element from
120: * the specified collection
121: * @param collection the {@link IntCollection IntCollection} of elements to add
122: * @return <code>true</code> iff I changed as a result of this call
123: *
124: * @throws UnsupportedOperationException when this operation is not
125: * supported
126: * @throws IndexOutOfBoundsException if the specified index is out of range
127: */
128: boolean addAll(int index, IntCollection collection);
129:
130: /**
131: * Returns <code>true</code> iff <i>that</i> is an <code>IntList</code>
132: * that contains the same elements in the same order as me.
133: * In other words, returns <code>true</code> iff <i>that</i> is
134: * an <code>IntList</code> that has the same {@link #size size} as me,
135: * and for which the elements returned by its
136: * {@link IntList#iterator iterator} are equal (<code>==</code>) to
137: * the corresponding elements within me.
138: * (This contract ensures that this method works properly across
139: * different implementations of the <code>IntList</code> interface.)
140: *
141: * @param that the object to compare to me
142: * @return <code>true</code> iff <i>that</i> is an <code>IntList</code>
143: * that contains the same elements in the same order as me
144: */
145: boolean equals(Object that);
146:
147: /**
148: * Returns the value of the element at the specified position
149: * within me.
150: *
151: * @param index the index of the element to return
152: * @return the value of the element at the specified position
153: * @throws IndexOutOfBoundsException if the specified index is out of range
154: */
155: int get(int index);
156:
157: /**
158: * Returns my hash code.
159: * <p />
160: * The hash code of an <code>IntList</code> is defined to be the
161: * result of the following calculation:
162: * <pre> int hash = 1;
163: * for(IntIterator iter = iterator(); iter.hasNext(); ) {
164: * hash = 31*hash + iter.next();
165: * }</pre>
166: * <p />
167: * This contract ensures that this method is consistent with
168: * {@link #equals equals} and with the
169: * {@link java.util.List#hashCode hashCode}
170: * method of a {@link java.util.List List} of {@link Integer}s.
171: *
172: * @return my hash code
173: */
174: int hashCode();
175:
176: /**
177: * Returns the index of the first occurrence
178: * of the specified element within me,
179: * or <code>-1</code> if I do not contain
180: * the element.
181: *
182: * @param element the element to search for
183: * @return the smallest index of an element matching the specified value,
184: * or <code>-1</code> if no such matching element can be found
185: */
186: int indexOf(int element);
187:
188: /**
189: * Returns an {@link IntIterator iterator} over all my elements,
190: * in the appropriate sequence.
191: * @return an {@link IntIterator iterator} over all my elements.
192: */
193: IntIterator iterator();
194:
195: /**
196: * Returns the index of the last occurrence
197: * of the specified element within me,
198: * or -1 if I do not contain the element.
199: *
200: * @param element the element to search for
201: * @return the largest index of an element matching the specified value,
202: * or <code>-1</code> if no such matching element can be found
203: */
204: int lastIndexOf(int element);
205:
206: /**
207: * Returns a
208: * {@link IntListIterator bidirectional iterator}
209: * over all my elements, in the appropriate sequence.
210: */
211: IntListIterator listIterator();
212:
213: /**
214: * Returns a
215: * {@link IntListIterator bidirectional iterator}
216: * over all my elements, in the appropriate sequence,
217: * starting at the specified position. The
218: * specified <i>index</i> indicates the first
219: * element that would be returned by an initial
220: * call to the
221: * {@link IntListIterator#next next}
222: * method. An initial call to the
223: * {@link IntListIterator#previous previous}
224: * method would return the element with the specified
225: * <i>index</i> minus one.
226: *
227: * @throws IndexOutOfBoundsException if the specified index is out of range
228: */
229: IntListIterator listIterator(int index);
230:
231: /**
232: * Removes the element at the specified position in
233: * (optional operation). Any subsequent elements
234: * are shifted to the left, subtracting one from their
235: * indices. Returns the element that was removed.
236: *
237: * @param index the index of the element to remove
238: * @return the value of the element that was removed
239: *
240: * @throws UnsupportedOperationException when this operation is not
241: * supported
242: * @throws IndexOutOfBoundsException if the specified index is out of range
243: */
244: int removeElementAt(int index);
245:
246: /**
247: * Replaces the element at the specified
248: * position in me with the specified element
249: * (optional operation).
250: *
251: * @param index the index of the element to change
252: * @param element the value to be stored at the specified position
253: * @return the value previously stored at the specified position
254: *
255: * @throws UnsupportedOperationException when this operation is not
256: * supported
257: * @throws IndexOutOfBoundsException if the specified index is out of range
258: */
259: int set(int index, int element);
260:
261: /**
262: * Returns a view of the elements within me
263: * between the specified <i>fromIndex</i>, inclusive, and
264: * <i>toIndex</i>, exclusive. The returned <code>IntList</code>
265: * is backed by me, so that any changes in
266: * the returned list are reflected in me, and vice-versa.
267: * The returned list supports all of the optional operations
268: * that I support.
269: * <p/>
270: * Note that when <code><i>fromIndex</i> == <i>toIndex</i></code>,
271: * the returned list is initially empty, and when
272: * <code><i>fromIndex</i> == 0 && <i>toIndex</i> == {@link #size() size()}</code>
273: * the returned list is my "improper" sublist, containing all my elements.
274: * <p/>
275: * The semantics of the returned list become undefined
276: * if I am structurally modified in any way other than
277: * via the returned list.
278: *
279: * @param fromIndex the smallest index (inclusive) in me that appears in
280: * the returned list
281: * @param toIndex the largest index (exclusive) in me that appears in the
282: * returned list
283: * @return a view of this list from <i>fromIndex</i> (inclusive) to
284: * <i>toIndex</i> (exclusive)
285: *
286: * @throws IndexOutOfBoundsException if either specified index is out of range
287: */
288: IntList subList(int fromIndex, int toIndex);
289:
290: }
|