001 /*
002 * Copyright 2001-2010 Stephen Colebourne
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.joda.primitives.list;
017
018 import org.joda.primitives.collection.DoubleCollection;
019 import org.joda.primitives.iterator.DoubleIterator;
020 import org.joda.primitives.listiterator.DoubleListIterator;
021
022 /**
023 * Defines a list of primitive <code>double</code> values.
024 * <p>
025 * This interface extends {@link java.util.List List} allowing seamless integration
026 * with other APIs.
027 * All List methods can be used, using the primitive wrapper class {@link Double}.
028 * However, it will be <em>much</em> more efficient to use the methods defined here.
029 *
030 * @author Stephen Colebourne
031 * @author Jason Tiscione
032 * @version CODE GENERATED
033 * @since 1.0
034 */
035 public interface DoubleList extends PrimitiveList<Double>, DoubleCollection {
036 // This file is CODE GENERATED. Do not change manually.
037
038 // Mandatory operations
039 //-----------------------------------------------------------------------
040 /**
041 * Gets an iterator over this list capable of accessing the primitive values.
042 *
043 * @return an iterator over this list, not null
044 */
045 DoubleIterator iterator();
046 // This method is specified here, despite being in {@code DoubleCollection},
047 // due to compiler bug 6487370.
048
049 /**
050 * Gets the primitive value at the specified index.
051 *
052 * @param index the index to get from
053 * @return value at the index
054 * @throws IndexOutOfBoundsException if the index is invalid
055 */
056 double getDouble(int index);
057
058 /**
059 * Gets the first primitive value.
060 *
061 * @return value at index zero
062 * @throws IndexOutOfBoundsException if the size is zero
063 */
064 double firstDouble();
065
066 /**
067 * Gets the last primitive value.
068 *
069 * @return value at index <code>size() - 1</code>
070 * @throws IndexOutOfBoundsException if the size is zero
071 */
072 double lastDouble();
073
074 /**
075 * Gets a list iterator over this list capable of accessing the primitive values.
076 *
077 * @return an iterator over this list, not null
078 */
079 DoubleListIterator listIterator();
080
081 /**
082 * Gets a list iterator over this list from a start index capable of accessing the primitive values.
083 *
084 * @param index the index to start from
085 * @return an iterator over this list, not null
086 * @throws IndexOutOfBoundsException if the index is invalid
087 */
088 DoubleListIterator listIterator(int index);
089
090 /**
091 * Gets the first index of the specified primitive value.
092 *
093 * @param value the value to search for
094 * @return the zero-based index, or <code>-1</code> if not found
095 */
096 int indexOf(double value);
097
098 /**
099 * Gets the first index of the specified primitive value from an index.
100 * <p>
101 * This method follows the conventions of <code>String</code> in that a
102 * negative index is treated as zero, and an index greater than the list
103 * size will simply return <code>-1</code>.
104 *
105 * @param value the value to search for
106 * @param fromIndexInclusive the index to start searching from, inclusive
107 * @return the zero-based index, or <code>-1</code> if not found
108 */
109 int indexOf(double value, int fromIndexInclusive);
110
111 /**
112 * Gets the last index of the specified primitive value.
113 *
114 * @param value the value to search for
115 * @return the zero-based index, or <code>-1</code> if not found
116 */
117 int lastIndexOf(double value);
118
119 /**
120 * Gets the first index of the specified primitive value from an index.
121 * <p>
122 * This method follows the conventions of <code>String</code> in that an
123 * index greater than the list size will start searching at the list size,
124 * and a negative index simply returns <code>-1</code>.
125 *
126 * @param value the value to search for
127 * @param fromIndexInclusive the index to start searching from, inclusive
128 * @return the zero-based index, or <code>-1</code> if not found
129 */
130 int lastIndexOf(double value, int fromIndexInclusive);
131
132 /**
133 * Gets a range of elements as an array.
134 *
135 * @param fromIndexInclusive the index to start from, inclusive
136 * @param toIndexExclusive the index to end at, exclusive
137 * @return a new array containing a copy of the range of elements, not null
138 * @throws IndexOutOfBoundsException if either index is invalid
139 */
140 double[] toDoubleArray(int fromIndexInclusive, int toIndexExclusive);
141
142 /**
143 * Gets a range view of part of this list.
144 * <p>
145 * This method allows operations to work on a range within the greater list.
146 * Changes made to the either object will affect the other.
147 *
148 * @param fromIndexInclusive the index to start from, inclusive
149 * @param toIndexExclusive the index to end at, exclusive
150 * @return a new DoubleList for the subList, not null
151 * @throws IndexOutOfBoundsException if either index is invalid
152 */
153 DoubleList subList(int fromIndexInclusive, int toIndexExclusive);
154
155 // Optional operations
156 //-----------------------------------------------------------------------
157 /**
158 * Adds a primitive value to this list at an index (optional operation).
159 * <p>
160 * This method is optional, throwing an UnsupportedOperationException if the
161 * collection cannot be added to.
162 *
163 * @param index the index to add at
164 * @param value the value to add to this collection
165 * @return <code>true</code> if this list was modified by this method call
166 * @throws IndexOutOfBoundsException if the index is invalid
167 * @throws IllegalArgumentException if value is rejected by this collection
168 * @throws UnsupportedOperationException if not supported by this collection
169 */
170 boolean add(int index, double value);
171
172 /**
173 * Adds an array of primitive values to this list at an index (optional operation).
174 * <p>
175 * This method is optional, throwing an UnsupportedOperationException if the
176 * collection cannot be added to.
177 *
178 * @param index the index to add at
179 * @param values the values to add to this collection, null treated as empty array
180 * @return <code>true</code> if this list was modified by this method call
181 * @throws IndexOutOfBoundsException if the index is invalid
182 * @throws IllegalArgumentException if value is rejected by this collection
183 * @throws UnsupportedOperationException if not supported by this collection
184 */
185 boolean addAll(int index, double[] values);
186
187 /**
188 * Removes a primitive value by index from the list (optional operation).
189 * <p>
190 * This method is optional, throwing an UnsupportedOperationException if the
191 * collection cannot be added to.
192 * <p>
193 * This method is deprecated to serve as a warning to developers.
194 * Using it can be confusing as it removes by index rather than by primitive.
195 * The method will still function correctly as the method is defined in the List interface.
196 * Use {@link #removeDoubleAt} instead.
197 *
198 * @deprecated use double removeDoubleAt(int)
199 * @param index the index to remove from
200 * @return the primitive value previously at this index
201 * @throws IndexOutOfBoundsException if the index is invalid
202 * @throws UnsupportedOperationException if not supported by this collection
203 */
204 @Deprecated
205 Double remove(int index);
206
207 /**
208 * Removes a primitive value by index from the list (optional operation).
209 * <p>
210 * This method is optional, throwing an UnsupportedOperationException if the
211 * collection cannot be added to.
212 *
213 * @param index the index to remove from
214 * @return the primitive value previously at this index
215 * @throws IndexOutOfBoundsException if the index is invalid
216 * @throws UnsupportedOperationException if not supported by this collection
217 */
218 double removeDoubleAt(int index);
219
220 /**
221 * Sets the primitive value at a specified index (optional operation).
222 * <p>
223 * This method is optional, throwing an UnsupportedOperationException if the
224 * collection cannot be changed.
225 *
226 * @param index the index to set
227 * @param value the value to store
228 * @return the previous value at the index
229 * @throws IndexOutOfBoundsException if the index is invalid
230 * @throws IllegalArgumentException if value is rejected by this collection
231 * @throws UnsupportedOperationException if not supported by this collection
232 */
233 double set(int index, double value);
234
235 }