List.java revision f6c387128427e121477c1b32ad35cdcaa5101ba3
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 18package java.util; 19 20 21/** 22 * A {@code List} is a collection which maintains an ordering for its elements. Every 23 * element in the {@code List} has an index. Each element can thus be accessed by its 24 * index, with the first index being zero. Normally, {@code List}s allow duplicate 25 * elements, as compared to Sets, where elements have to be unique. 26 * 27 * @since Android 1.0 28 */ 29public interface List<E> extends Collection<E> { 30 /** 31 * Inserts the specified object into this {@code List} at the specified location. 32 * The object is inserted before the current element at the specified 33 * location. If the location is equal to the size of this {@code List}, the object 34 * is added at the end. If the location is smaller than the size of this 35 * {@code List}, then all elements beyond the specified location are moved by one 36 * position towards the end of the {@code List}. 37 * 38 * @param location 39 * the index at which to insert. 40 * @param object 41 * the object to add. 42 * @exception UnsupportedOperationException 43 * when adding to this {@code List} is not supported. 44 * @exception ClassCastException 45 * when the class of the object is inappropriate for this 46 * {@code List}. 47 * @exception IllegalArgumentException 48 * when the object cannot be added to this {@code List}. 49 * @exception IndexOutOfBoundsException 50 * when {@code location < 0 || location > size()} 51 * @since Android 1.0 52 */ 53 public void add(int location, E object); 54 55 /** 56 * Adds the specified object at the end of this {@code List}. 57 * 58 * @param object 59 * the object to add. 60 * @return always true. 61 * @exception UnsupportedOperationException 62 * when adding to this {@code List} is not supported. 63 * @exception ClassCastException 64 * when the class of the object is inappropriate for this 65 * {@code List}. 66 * @exception IllegalArgumentException 67 * when the object cannot be added to this {@code List}. 68 * @since Android 1.0 69 */ 70 public boolean add(E object); 71 72 /** 73 * Inserts the objects in the specified collection at the specified location 74 * in this {@code List}. The objects are added in the order they are returned from 75 * the collection's iterator. 76 * 77 * @param location 78 * the index at which to insert. 79 * @param collection 80 * the collection of objects to be inserted. 81 * @return true if this {@code List} has been modified through the insertion, false 82 * otherwise (i.e. if the passed collection was empty). 83 * @exception UnsupportedOperationException 84 * when adding to this {@code List} is not supported. 85 * @exception ClassCastException 86 * when the class of an object is inappropriate for this 87 * {@code List}. 88 * @exception IllegalArgumentException 89 * when an object cannot be added to this {@code List}. 90 * @exception IndexOutOfBoundsException 91 * when {@code location < 0 || > size()} 92 * @since Android 1.0 93 */ 94 public boolean addAll(int location, Collection<? extends E> collection); 95 96 /** 97 * Adds the objects in the specified collection to the end of this {@code List}. The 98 * objects are added in the order in which they are returned from the 99 * collection's iterator. 100 * 101 * @param collection 102 * the collection of objects. 103 * @return {@code true} if this {@code List} is modified, {@code false} otherwise 104 * (i.e. if the passed collection was empty). 105 * @exception UnsupportedOperationException 106 * when adding to this {@code List} is not supported. 107 * @exception ClassCastException 108 * when the class of an object is inappropriate for this 109 * {@code List}. 110 * @exception IllegalArgumentException 111 * when an object cannot be added to this {@code List}. 112 * @since Android 1.0 113 */ 114 public boolean addAll(Collection<? extends E> collection); 115 116 /** 117 * Removes all elements from this {@code List}, leaving it empty. 118 * 119 * @exception UnsupportedOperationException 120 * when removing from this {@code List} is not supported. 121 * @see #isEmpty 122 * @see #size 123 * @since Android 1.0 124 */ 125 public void clear(); 126 127 /** 128 * Tests whether this {@code List} contains the specified object. 129 * 130 * @param object 131 * the object to search for. 132 * @return {@code true} if object is an element of this {@code List}, {@code false} 133 * otherwise 134 * @since Android 1.0 135 */ 136 public boolean contains(Object object); 137 138 /** 139 * Tests whether this {@code List} contains all objects contained in the 140 * specified collection. 141 * 142 * @param collection 143 * the collection of objects 144 * @return {@code true} if all objects in the specified collection are 145 * elements of this {@code List}, {@code false} otherwise. 146 * @since Android 1.0 147 */ 148 public boolean containsAll(Collection<?> collection); 149 150 /** 151 * Compares the given object with the {@code List}, and returns true if they 152 * represent the <em>same</em> object using a class specific comparison. For 153 * {@code List}s, this means that they contain the same elements in exactly the same 154 * order. 155 * 156 * @param object 157 * the object to compare with this object. 158 * @return boolean {@code true} if the object is the same as this object, 159 * and {@code false} if it is different from this object. 160 * @see #hashCode 161 * @since Android 1.0 162 */ 163 public boolean equals(Object object); 164 165 /** 166 * Returns the element at the specified location in this {@code List}. 167 * 168 * @param location 169 * the index of the element to return. 170 * @return the element at the specified location. 171 * @exception IndexOutOfBoundsException 172 * when {@code location < 0 || >= size()} 173 * @since Android 1.0 174 */ 175 public E get(int location); 176 177 /** 178 * Returns the hash code for this {@code List}. It is calculated by taking each 179 * element' hashcode and its position in the {@code List} into account. 180 * 181 * @return the hash code of the {@code List}. 182 * @since Android 1.0 183 */ 184 public int hashCode(); 185 186 /** 187 * Searches this {@code List} for the specified object and returns the index of the 188 * first occurrence. 189 * 190 * @param object 191 * the object to search for. 192 * @return the index of the first occurrence of the object or -1 if the 193 * object was not found. 194 * @since Android 1.0 195 */ 196 public int indexOf(Object object); 197 198 /** 199 * Returns whether this {@code List} contains no elements. 200 * 201 * @return {@code true} if this {@code List} has no elements, {@code false} 202 * otherwise. 203 * @see #size 204 * @since Android 1.0 205 */ 206 public boolean isEmpty(); 207 208 /** 209 * Returns an iterator on the elements of this {@code List}. The elements are 210 * iterated in the same order as they occur in the {@code List}. 211 * 212 * @return an iterator on the elements of this {@code List}. 213 * @see Iterator 214 * @since Android 1.0 215 */ 216 public Iterator<E> iterator(); 217 218 /** 219 * Searches this {@code List} for the specified object and returns the index of the 220 * last occurrence. 221 * 222 * @param object 223 * the object to search for. 224 * @return the index of the last occurrence of the object, or -1 if the 225 * object was not found. 226 * @since Android 1.0 227 */ 228 public int lastIndexOf(Object object); 229 230 /** 231 * Returns a {@code List} iterator on the elements of this {@code List}. The elements are 232 * iterated in the same order that they occur in the {@code List}. 233 * 234 * @return a {@code List} iterator on the elements of this {@code List} 235 * 236 * @see ListIterator 237 * @since Android 1.0 238 */ 239 public ListIterator<E> listIterator(); 240 241 /** 242 * Returns a list iterator on the elements of this {@code List}. The elements are 243 * iterated in the same order as they occur in the {@code List}. The iteration 244 * starts at the specified location. 245 * 246 * @param location 247 * the index at which to start the iteration. 248 * @return a list iterator on the elements of this {@code List}. 249 * @exception IndexOutOfBoundsException 250 * when {@code location < 0 || location > size()} 251 * @see ListIterator 252 * @since Android 1.0 253 */ 254 public ListIterator<E> listIterator(int location); 255 256 /** 257 * Removes the object at the specified location from this {@code List}. 258 * 259 * @param location 260 * the index of the object to remove. 261 * @return the removed object. 262 * @exception UnsupportedOperationException 263 * when removing from this {@code List} is not supported. 264 * @exception IndexOutOfBoundsException 265 * when {@code location < 0 || >= size()} 266 * @since Android 1.0 267 */ 268 public E remove(int location); 269 270 /** 271 * Removes the first occurrence of the specified object from this {@code List}. 272 * 273 * @param object 274 * the object to remove. 275 * @return true if this {@code List} was modified by this operation, false 276 * otherwise. 277 * @exception UnsupportedOperationException 278 * when removing from this {@code List} is not supported. 279 * @since Android 1.0 280 */ 281 public boolean remove(Object object); 282 283 /** 284 * Removes all occurrences in this {@code List} of each object in the specified 285 * collection. 286 * 287 * @param collection 288 * the collection of objects to remove. 289 * @return {@code true} if this {@code List} is modified, {@code false} otherwise. 290 * @exception UnsupportedOperationException 291 * when removing from this {@code List} is not supported. 292 * @since Android 1.0 293 */ 294 public boolean removeAll(Collection<?> collection); 295 296 /** 297 * Removes all objects from this {@code List} that are not contained in the 298 * specified collection. 299 * 300 * @param collection 301 * the collection of objects to retain. 302 * @return {@code true} if this {@code List} is modified, {@code false} otherwise. 303 * @exception UnsupportedOperationException 304 * when removing from this {@code List} is not supported. 305 * @since Android 1.0 306 */ 307 public boolean retainAll(Collection<?> collection); 308 309 /** 310 * Replaces the element at the specified location in this {@code List} with the 311 * specified object. This operation does not change the size of the {@code List}. 312 * 313 * @param location 314 * the index at which to put the specified object. 315 * @param object 316 * the object to insert. 317 * @return the previous element at the index. 318 * @exception UnsupportedOperationException 319 * when replacing elements in this {@code List} is not supported. 320 * @exception ClassCastException 321 * when the class of an object is inappropriate for this 322 * {@code List}. 323 * @exception IllegalArgumentException 324 * when an object cannot be added to this {@code List}. 325 * @exception IndexOutOfBoundsException 326 * when {@code location < 0 || >= size()} 327 * @since Android 1.0 328 */ 329 public E set(int location, E object); 330 331 /** 332 * Returns the number of elements in this {@code List}. 333 * 334 * @return the number of elements in this {@code List}. 335 * @since Android 1.0 336 */ 337 public int size(); 338 339 /** 340 * Returns a {@code List} of the specified portion of this {@code List} from the given start 341 * index to the end index minus one. The returned {@code List} is backed by this 342 * {@code List} so changes to it are reflected by the other. 343 * 344 * @param start 345 * the index at which to start the sublist. 346 * @param end 347 * the index one past the end of the sublist. 348 * @return a list of a portion of this {@code List}. 349 * @exception IndexOutOfBoundsException 350 * when {@code start < 0, start > end} or {@code end > 351 * size()} 352 * @since Android 1.0 353 */ 354 public List<E> subList(int start, int end); 355 356 /** 357 * Returns an array containing all elements contained in this {@code List}. 358 * 359 * @return an array of the elements from this {@code List}. 360 * @since Android 1.0 361 */ 362 public Object[] toArray(); 363 364 /** 365 * Returns an array containing all elements contained in this {@code List}. If the 366 * specified array is large enough to hold the elements, the specified array 367 * is used, otherwise an array of the same type is created. If the specified 368 * array is used and is larger than this {@code List}, the array element following 369 * the collection elements is set to null. 370 * 371 * @param array 372 * the array. 373 * @return an array of the elements from this {@code List}. 374 * @exception ArrayStoreException 375 * when the type of an element in this {@code List} cannot be stored 376 * in the type of the specified array. 377 * @since Android 1.0 378 */ 379 public <T> T[] toArray(T[] array); 380} 381