001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *     http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.commons.collections.primitives;
018    
019    /**
020     * An ordered collection of <code>float</code> values.
021     *
022     * @see org.apache.commons.collections.primitives.adapters.FloatListList
023     * @see org.apache.commons.collections.primitives.adapters.ListFloatList
024     *
025     * @since Commons Primitives 1.0
026     * @version $Revision: 480460 $ $Date: 2006-11-29 09:14:21 +0100 (Wed, 29 Nov 2006) $
027     * 
028     * @author Rodney Waldhoff 
029     */
030    public interface FloatList extends FloatCollection {
031        /** 
032         * Appends the specified element to the end of me
033         * (optional operation).  Returns <code>true</code>
034         * iff I changed as a result of this call.
035         * <p/>
036         * If a collection refuses to add the specified
037         * element for any reason other than that it already contains
038         * the element, it <i>must</i> throw an exception (rather than
039         * simply returning <tt>false</tt>).  This preserves the invariant
040         * that a collection always contains the specified element after 
041         * this call returns. 
042         * 
043         * @param element the value whose presence within me is to be ensured
044         * @return <code>true</code> iff I changed as a result of this call
045         * 
046         * @throws UnsupportedOperationException when this operation is not 
047         *         supported
048         * @throws IllegalArgumentException may be thrown if some aspect of the 
049         *         specified element prevents it from being added to me
050         */
051        boolean add(float element);
052           
053        /** 
054         * Inserts the specified element at the specified position 
055         * (optional operation). Shifts the element currently 
056         * at that position (if any) and any subsequent elements to the 
057         * right, increasing their indices.
058         * 
059         * @param index the index at which to insert the element
060         * @param element the value to insert
061         * 
062         * @throws UnsupportedOperationException when this operation is not 
063         *         supported
064         * @throws IllegalArgumentException if some aspect of the specified element 
065         *         prevents it from being added to me
066         * @throws IndexOutOfBoundsException if the specified index is out of range
067         */
068        void add(int index, float element);
069              
070        /** 
071         * Inserts all of the elements in the specified collection into me,
072         * at the specified position (optional operation).  Shifts the 
073         * element currently at that position (if any) and any subsequent 
074         * elements to the right, increasing their indices.  The new elements 
075         * will appear in the order that they are returned by the given 
076         * collection's {@link FloatCollection#iterator iterator}.
077         * 
078         * @param index the index at which to insert the first element from 
079         *        the specified collection
080         * @param collection the {@link FloatCollection FloatCollection} of elements to add 
081         * @return <code>true</code> iff I changed as a result of this call
082         * 
083         * @throws UnsupportedOperationException when this operation is not 
084         *         supported
085         * @throws IndexOutOfBoundsException if the specified index is out of range
086         */
087        boolean addAll(int index, FloatCollection collection);
088        
089        /**
090         * Returns <code>true</code> iff <i>that</i> is an <code>FloatList</code>
091         * that contains the same elements in the same order as me.
092         * In other words, returns <code>true</code> iff <i>that</i> is
093         * a <code>FloatList</code> that has the same {@link #size() size} as me,
094         * and for which the elements returned by its 
095         * {@link FloatList#iterator iterator} are equal (<code>==</code>) to
096         * the corresponding elements within me.
097         * (This contract ensures that this method works properly across 
098         * different implementations of the <code>FloatList</code> interface.)
099         * 
100         * @param that the object to compare to me
101         * @return <code>true</code> iff <i>that</i> is an <code>FloatList</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        float get(int index);
115            
116        /**
117         * Returns my hash code.
118         * <p />
119         * The hash code of an <code>FloatList</code> is defined to be the
120         * result of the following calculation:
121         * <pre> int hash = 1;
122         * for(FloatIterator iter = iterator(); iter.hasNext(); ) {
123         *   float 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 Float}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(float element);
147         
148        /** 
149         * Returns an {@link FloatIterator iterator} over all my elements,
150         * in the appropriate sequence.
151         * @return an {@link FloatIterator iterator} over all my elements.
152         */
153        FloatIterator 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(float element);
165        
166        /** 
167         * Returns a 
168         * {@link FloatListIterator bidirectional iterator}
169         * over all my elements, in the appropriate sequence.
170         */
171        FloatListIterator listIterator();
172        
173        /** 
174         * Returns a 
175         * {@link FloatListIterator 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 FloatListIterator#next next} 
182         * method. An initial call to the 
183         * {@link FloatListIterator#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        FloatListIterator 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        float 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        float set(int index, float 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>FloatList</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        FloatList subList(int fromIndex, int toIndex);
249    
250    }