Coverage Report

Coverage Report - org.apache.commons.collections.primitives.LongList

Classes in this File

 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 package org.apache.commons.collections.primitives;
 
 /**
  * An ordered collection of <code>long</code> values.
  *
  * @see org.apache.commons.collections.primitives.adapters.LongListList
  * @see org.apache.commons.collections.primitives.adapters.ListLongList
  *
  * @since Commons Primitives 1.0
  * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $
  * 
  * @author Rodney Waldhoff 
  */
 public interface LongList extends LongCollection {
     /** 
      * Appends the specified element to the end of me
      * (optional operation).  Returns <code>true</code>
      * iff I changed as a result of this call.
      * <p/>
      * If a collection refuses to add the specified
      * element for any reason other than that it already contains
      * the element, it <i>must</i> throw an exception (rather than
      * simply returning <tt>false</tt>).  This preserves the invariant
      * that a collection always contains the specified element after 
      * this call returns. 
      * 
      * @param element the value whose presence within me is to be ensured
      * @return <code>true</code> iff I changed as a result of this call
      * 
      * @throws UnsupportedOperationException when this operation is not 
      *         supported
      * @throws IllegalArgumentException may be thrown if some aspect of the 
      *         specified element prevents it from being added to me
      */
     boolean add(long element);
        
     /** 
      * Inserts the specified element at the specified position 
      * (optional operation). Shifts the element currently 
      * at that position (if any) and any subsequent elements to the 
      * right, increasing their indices.
      * 
      * @param index the index at which to insert the element
      * @param element the value to insert
      * 
      * @throws UnsupportedOperationException when this operation is not 
      *         supported
      * @throws IllegalArgumentException if some aspect of the specified element 
      *         prevents it from being added to me
      * @throws IndexOutOfBoundsException if the specified index is out of range
      */
     void add(int index, long element);
           
     /** 
      * Inserts all of the elements in the specified collection into me,
      * at the specified position (optional operation).  Shifts the 
      * element currently at that position (if any) and any subsequent 
      * elements to the right, increasing their indices.  The new elements 
      * will appear in the order that they are returned by the given 
      * collection's {@link LongCollection#iterator iterator}.
      * 
      * @param index the index at which to insert the first element from 
      *        the specified collection
      * @param collection the {@link LongCollection LongCollection} of elements to add 
      * @return <code>true</code> iff I changed as a result of this call
      * 
      * @throws UnsupportedOperationException when this operation is not 
      *         supported
      * @throws IndexOutOfBoundsException if the specified index is out of range
      */
     boolean addAll(int index, LongCollection collection);
     
     /**
      * Returns <code>true</code> iff <i>that</i> is an <code>LongList</code>
      * that contains the same elements in the same order as me.
      * In other words, returns <code>true</code> iff <i>that</i> is
      * a <code>LongList</code> that has the same {@link #size() size} as me,
      * and for which the elements returned by its 
      * {@link LongList#iterator iterator} are equal (<code>==</code>) to
      * the corresponding elements within me.
      * (This contract ensures that this method works properly across 
      * different implementations of the <code>LongList</code> interface.)
      * 
      * @param that the object to compare to me
      * @return <code>true</code> iff <i>that</i> is an <code>LongList</code>
      *         that contains the same elements in the same order as me
      */
     boolean equals(Object that);
     
     /** 
      * Returns the value of the element at the specified position 
      * within me. 
      * 
      * @param index the index of the element to return
      * @return the value of the element at the specified position
      * @throws IndexOutOfBoundsException if the specified index is out of range
      */
     long get(int index);
         
     /**
      * Returns my hash code.
      * <p />
      * The hash code of an <code>LongList</code> is defined to be the
      * result of the following calculation:
      * <pre> int hash = 1;
      * for(LongIterator iter = iterator(); iter.hasNext(); ) {
      *   long value = iter.next();
      *   hash = 31*hash + (int)(value ^ (value >>> 32));
      * }</pre>
      * <p />
      * This contract ensures that this method is consistent with 
      * {@link #equals equals} and with the 
      * {@link java.util.List#hashCode hashCode}
      * method of a {@link java.util.List List} of {@link Long}s. 
      * 
      * @return my hash code
      */
     int hashCode();
 
     /** 
      * Returns the index of the first occurrence 
      * of the specified element within me, 
      * or <code>-1</code> if I do not contain 
      * the element. 
      * 
      * @param element the element to search for
      * @return the smallest index of an element matching the specified value,
      *         or <code>-1</code> if no such matching element can be found 
      */
     int indexOf(long element);
      
     /** 
      * Returns an {@link LongIterator iterator} over all my elements,
      * in the appropriate sequence.
      * @return an {@link LongIterator iterator} over all my elements.
      */
     LongIterator iterator();
 
     /** 
      * Returns the index of the last occurrence 
      * of the specified element within me, 
      * or -1 if I do not contain the element. 
      * 
      * @param element the element to search for
      * @return the largest index of an element matching the specified value,
      *         or <code>-1</code> if no such matching element can be found 
      */
     int lastIndexOf(long element);
     
     /** 
      * Returns a 
      * {@link LongListIterator bidirectional iterator}
      * over all my elements, in the appropriate sequence.
      */
     LongListIterator listIterator();
     
     /** 
      * Returns a 
      * {@link LongListIterator bidirectional iterator}
      * over all my elements, in the appropriate sequence, 
      * starting at the specified position. The 
      * specified <i>index</i> indicates the first 
      * element that would be returned by an initial 
      * call to the 
      * {@link LongListIterator#next next} 
      * method. An initial call to the 
      * {@link LongListIterator#previous previous}
      * method would return the element with the specified 
      * <i>index</i> minus one.
      * 
      * @throws IndexOutOfBoundsException if the specified index is out of range
      */
     LongListIterator listIterator(int index);
     
     /** 
      * Removes the element at the specified position in 
      * (optional operation).  Any subsequent elements 
      * are shifted to the left, subtracting one from their 
      * indices.  Returns the element that was removed.
      * 
      * @param index the index of the element to remove
      * @return the value of the element that was removed
      * 
      * @throws UnsupportedOperationException when this operation is not 
      *         supported
      * @throws IndexOutOfBoundsException if the specified index is out of range
      */
     long removeElementAt(int index);
    
     /** 
      * Replaces the element at the specified 
      * position in me with the specified element
      * (optional operation). 
      * 
      * @param index the index of the element to change
      * @param element the value to be stored at the specified position
      * @return the value previously stored at the specified position
      * 
      * @throws UnsupportedOperationException when this operation is not 
      *         supported
      * @throws IndexOutOfBoundsException if the specified index is out of range
      */
     long set(int index, long element);
     
     /** 
      * Returns a view of the elements within me 
      * between the specified <i>fromIndex</i>, inclusive, and 
      * <i>toIndex</i>, exclusive.  The returned <code>LongList</code>
      * is backed by me, so that any changes in 
      * the returned list are reflected in me, and vice-versa.
      * The returned list supports all of the optional operations
      * that I support.
      * <p/>
      * Note that when <code><i>fromIndex</i> == <i>toIndex</i></code>,
      * the returned list is initially empty, and when 
      * <code><i>fromIndex</i> == 0 && <i>toIndex</i> == {@link #size() size()}</code>
      * the returned list is my "improper" sublist, containing all my elements.
      * <p/>
      * The semantics of the returned list become undefined
      * if I am structurally modified in any way other than 
      * via the returned list.
      * 
      * @param fromIndex the smallest index (inclusive) in me that appears in 
      *        the returned list
      * @param toIndex the largest index (exclusive) in me that appears in the 
      *        returned list
      * @return a view of this list from <i>fromIndex</i> (inclusive) to 
      *         <i>toIndex</i> (exclusive)
      * 
      * @throws IndexOutOfBoundsException if either specified index is out of range
      */
     LongList subList(int fromIndex, int toIndex);
 
 }

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>long</code> values.
21		*
22		* @see org.apache.commons.collections.primitives.adapters.LongListList
23		* @see org.apache.commons.collections.primitives.adapters.ListLongList
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 LongList extends LongCollection {
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(long 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, long 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 LongCollection#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 LongCollection LongCollection} 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, LongCollection collection);
88
89		/**
90		* Returns <code>true</code> iff <i>that</i> is an <code>LongList</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		* a <code>LongList</code> that has the same {@link #size() size} as me,
94		* and for which the elements returned by its
95		* {@link LongList#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>LongList</code> interface.)
99		*
100		* @param that the object to compare to me
101		* @return <code>true</code> iff <i>that</i> is an <code>LongList</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		long get(int index);
115
116		/**
117		* Returns my hash code.
118		* <p />
119		* The hash code of an <code>LongList</code> is defined to be the
120		* result of the following calculation:
121		* <pre> int hash = 1;
122		* for(LongIterator iter = iterator(); iter.hasNext(); ) {
123		* long value = iter.next();
124		* hash = 31*hash + (int)(value ^ (value >>> 32));
125		* }</pre>
126		* <p />
127		* This contract ensures that this method is consistent with
128		* {@link #equals equals} and with the
129		* {@link java.util.List#hashCode hashCode}
130		* method of a {@link java.util.List List} of {@link Long}s.
131		*
132		* @return my hash code
133		*/
134		int hashCode();
135
136		/**
137		* Returns the index of the first occurrence
138		* of the specified element within me,
139		* or <code>-1</code> if I do not contain
140		* the element.
141		*
142		* @param element the element to search for
143		* @return the smallest index of an element matching the specified value,
144		* or <code>-1</code> if no such matching element can be found
145		*/
146		int indexOf(long element);
147
148		/**
149		* Returns an {@link LongIterator iterator} over all my elements,
150		* in the appropriate sequence.
151		* @return an {@link LongIterator iterator} over all my elements.
152		*/
153		LongIterator iterator();
154
155		/**
156		* Returns the index of the last occurrence
157		* of the specified element within me,
158		* or -1 if I do not contain the element.
159		*
160		* @param element the element to search for
161		* @return the largest index of an element matching the specified value,
162		* or <code>-1</code> if no such matching element can be found
163		*/
164		int lastIndexOf(long element);
165
166		/**
167		* Returns a
168		* {@link LongListIterator bidirectional iterator}
169		* over all my elements, in the appropriate sequence.
170		*/
171		LongListIterator listIterator();
172
173		/**
174		* Returns a
175		* {@link LongListIterator bidirectional iterator}
176		* over all my elements, in the appropriate sequence,
177		* starting at the specified position. The
178		* specified <i>index</i> indicates the first
179		* element that would be returned by an initial
180		* call to the
181		* {@link LongListIterator#next next}
182		* method. An initial call to the
183		* {@link LongListIterator#previous previous}
184		* method would return the element with the specified
185		* <i>index</i> minus one.
186		*
187		* @throws IndexOutOfBoundsException if the specified index is out of range
188		*/
189		LongListIterator listIterator(int index);
190
191		/**
192		* Removes the element at the specified position in
193		* (optional operation). Any subsequent elements
194		* are shifted to the left, subtracting one from their
195		* indices. Returns the element that was removed.
196		*
197		* @param index the index of the element to remove
198		* @return the value of the element that was removed
199		*
200		* @throws UnsupportedOperationException when this operation is not
201		* supported
202		* @throws IndexOutOfBoundsException if the specified index is out of range
203		*/
204		long removeElementAt(int index);
205
206		/**
207		* Replaces the element at the specified
208		* position in me with the specified element
209		* (optional operation).
210		*
211		* @param index the index of the element to change
212		* @param element the value to be stored at the specified position
213		* @return the value previously stored at the specified position
214		*
215		* @throws UnsupportedOperationException when this operation is not
216		* supported
217		* @throws IndexOutOfBoundsException if the specified index is out of range
218		*/
219		long set(int index, long element);
220
221		/**
222		* Returns a view of the elements within me
223		* between the specified <i>fromIndex</i>, inclusive, and
224		* <i>toIndex</i>, exclusive. The returned <code>LongList</code>
225		* is backed by me, so that any changes in
226		* the returned list are reflected in me, and vice-versa.
227		* The returned list supports all of the optional operations
228		* that I support.
229		* <p/>
230		* Note that when <code><i>fromIndex</i> == <i>toIndex</i></code>,
231		* the returned list is initially empty, and when
232		* <code><i>fromIndex</i> == 0 && <i>toIndex</i> == {@link #size() size()}</code>
233		* the returned list is my "improper" sublist, containing all my elements.
234		* <p/>
235		* The semantics of the returned list become undefined
236		* if I am structurally modified in any way other than
237		* via the returned list.
238		*
239		* @param fromIndex the smallest index (inclusive) in me that appears in
240		* the returned list
241		* @param toIndex the largest index (exclusive) in me that appears in the
242		* returned list
243		* @return a view of this list from <i>fromIndex</i> (inclusive) to
244		* <i>toIndex</i> (exclusive)
245		*
246		* @throws IndexOutOfBoundsException if either specified index is out of range
247		*/
248		LongList subList(int fromIndex, int toIndex);
249
250		}