001: /*
002: * $Header: /home/cvs/jakarta-commons/primitives/src/java/org/apache/commons/collections/primitives/LongList.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>long</code> values.
062: *
063: * @see org.apache.commons.collections.primitives.adapters.LongListList
064: * @see org.apache.commons.collections.primitives.adapters.ListLongList
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 LongList extends LongCollection {
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(long 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, long 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 LongCollection#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 LongCollection LongCollection} 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, LongCollection collection);
129:
130: /**
131: * Returns <code>true</code> iff <i>that</i> is an <code>LongList</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>LongList</code> that has the same {@link #size size} as me,
135: * and for which the elements returned by its
136: * {@link LongList#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>LongList</code> interface.)
140: *
141: * @param that the object to compare to me
142: * @return <code>true</code> iff <i>that</i> is an <code>LongList</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: long get(int index);
156:
157: /**
158: * Returns my hash code.
159: * <p />
160: * The hash code of an <code>LongList</code> is defined to be the
161: * result of the following calculation:
162: * <pre> int hash = 1;
163: * for(LongIterator iter = iterator(); iter.hasNext(); ) {
164: * long value = iter.next();
165: * hash = 31*hash + (int)(value ^ (value >>> 32));
166: * }</pre>
167: * <p />
168: * This contract ensures that this method is consistent with
169: * {@link #equals equals} and with the
170: * {@link java.util.List#hashCode hashCode}
171: * method of a {@link java.util.List List} of {@link Long}s.
172: *
173: * @return my hash code
174: */
175: int hashCode();
176:
177: /**
178: * Returns the index of the first occurrence
179: * of the specified element within me,
180: * or <code>-1</code> if I do not contain
181: * the element.
182: *
183: * @param element the element to search for
184: * @return the smallest index of an element matching the specified value,
185: * or <code>-1</code> if no such matching element can be found
186: */
187: int indexOf(long element);
188:
189: /**
190: * Returns an {@link LongIterator iterator} over all my elements,
191: * in the appropriate sequence.
192: * @return an {@link LongIterator iterator} over all my elements.
193: */
194: LongIterator iterator();
195:
196: /**
197: * Returns the index of the last occurrence
198: * of the specified element within me,
199: * or -1 if I do not contain the element.
200: *
201: * @param element the element to search for
202: * @return the largest index of an element matching the specified value,
203: * or <code>-1</code> if no such matching element can be found
204: */
205: int lastIndexOf(long element);
206:
207: /**
208: * Returns a
209: * {@link LongListIterator bidirectional iterator}
210: * over all my elements, in the appropriate sequence.
211: */
212: LongListIterator listIterator();
213:
214: /**
215: * Returns a
216: * {@link LongListIterator bidirectional iterator}
217: * over all my elements, in the appropriate sequence,
218: * starting at the specified position. The
219: * specified <i>index</i> indicates the first
220: * element that would be returned by an initial
221: * call to the
222: * {@link LongListIterator#next next}
223: * method. An initial call to the
224: * {@link LongListIterator#previous previous}
225: * method would return the element with the specified
226: * <i>index</i> minus one.
227: *
228: * @throws IndexOutOfBoundsException if the specified index is out of range
229: */
230: LongListIterator listIterator(int index);
231:
232: /**
233: * Removes the element at the specified position in
234: * (optional operation). Any subsequent elements
235: * are shifted to the left, subtracting one from their
236: * indices. Returns the element that was removed.
237: *
238: * @param index the index of the element to remove
239: * @return the value of the element that was removed
240: *
241: * @throws UnsupportedOperationException when this operation is not
242: * supported
243: * @throws IndexOutOfBoundsException if the specified index is out of range
244: */
245: long removeElementAt(int index);
246:
247: /**
248: * Replaces the element at the specified
249: * position in me with the specified element
250: * (optional operation).
251: *
252: * @param index the index of the element to change
253: * @param element the value to be stored at the specified position
254: * @return the value previously stored at the specified position
255: *
256: * @throws UnsupportedOperationException when this operation is not
257: * supported
258: * @throws IndexOutOfBoundsException if the specified index is out of range
259: */
260: long set(int index, long element);
261:
262: /**
263: * Returns a view of the elements within me
264: * between the specified <i>fromIndex</i>, inclusive, and
265: * <i>toIndex</i>, exclusive. The returned <code>LongList</code>
266: * is backed by me, so that any changes in
267: * the returned list are reflected in me, and vice-versa.
268: * The returned list supports all of the optional operations
269: * that I support.
270: * <p/>
271: * Note that when <code><i>fromIndex</i> == <i>toIndex</i></code>,
272: * the returned list is initially empty, and when
273: * <code><i>fromIndex</i> == 0 && <i>toIndex</i> == {@link #size() size()}</code>
274: * the returned list is my "improper" sublist, containing all my elements.
275: * <p/>
276: * The semantics of the returned list become undefined
277: * if I am structurally modified in any way other than
278: * via the returned list.
279: *
280: * @param fromIndex the smallest index (inclusive) in me that appears in
281: * the returned list
282: * @param toIndex the largest index (exclusive) in me that appears in the
283: * returned list
284: * @return a view of this list from <i>fromIndex</i> (inclusive) to
285: * <i>toIndex</i> (exclusive)
286: *
287: * @throws IndexOutOfBoundsException if either specified index is out of range
288: */
289: LongList subList(int fromIndex, int toIndex);
290:
291: }
|