1 /* 2 * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.util; 27 28 import java.util.function.UnaryOperator; 29 30 /** 31 * An ordered collection (also known as a <i>sequence</i>). The user of this 32 * interface has precise control over where in the list each element is 33 * inserted. The user can access elements by their integer index (position in 34 * the list), and search for elements in the list.<p> 35 * 36 * Unlike sets, lists typically allow duplicate elements. More formally, 37 * lists typically allow pairs of elements {@code e1} and {@code e2} 38 * such that {@code e1.equals(e2)}, and they typically allow multiple 39 * null elements if they allow null elements at all. It is not inconceivable 40 * that someone might wish to implement a list that prohibits duplicates, by 41 * throwing runtime exceptions when the user attempts to insert them, but we 42 * expect this usage to be rare.<p> 43 * 44 * The {@code List} interface places additional stipulations, beyond those 45 * specified in the {@code Collection} interface, on the contracts of the 46 * {@code iterator}, {@code add}, {@code remove}, {@code equals}, and 47 * {@code hashCode} methods. Declarations for other inherited methods are 48 * also included here for convenience.<p> 49 * 50 * The {@code List} interface provides four methods for positional (indexed) 51 * access to list elements. Lists (like Java arrays) are zero based. Note 52 * that these operations may execute in time proportional to the index value 53 * for some implementations (the {@code LinkedList} class, for 54 * example). Thus, iterating over the elements in a list is typically 55 * preferable to indexing through it if the caller does not know the 56 * implementation.<p> 57 * 58 * The {@code List} interface provides a special iterator, called a 59 * {@code ListIterator}, that allows element insertion and replacement, and 60 * bidirectional access in addition to the normal operations that the 61 * {@code Iterator} interface provides. A method is provided to obtain a 62 * list iterator that starts at a specified position in the list.<p> 63 * 64 * The {@code List} interface provides two methods to search for a specified 65 * object. From a performance standpoint, these methods should be used with 66 * caution. In many implementations they will perform costly linear 67 * searches.<p> 68 * 69 * The {@code List} interface provides two methods to efficiently insert and 70 * remove multiple elements at an arbitrary point in the list.<p> 71 * 72 * Note: While it is permissible for lists to contain themselves as elements, 73 * extreme caution is advised: the {@code equals} and {@code hashCode} 74 * methods are no longer well defined on such a list. 75 * 76 * <p>Some list implementations have restrictions on the elements that 77 * they may contain. For example, some implementations prohibit null elements, 78 * and some have restrictions on the types of their elements. Attempting to 79 * add an ineligible element throws an unchecked exception, typically 80 * {@code NullPointerException} or {@code ClassCastException}. Attempting 81 * to query the presence of an ineligible element may throw an exception, 82 * or it may simply return false; some implementations will exhibit the former 83 * behavior and some will exhibit the latter. More generally, attempting an 84 * operation on an ineligible element whose completion would not result in 85 * the insertion of an ineligible element into the list may throw an 86 * exception or it may succeed, at the option of the implementation. 87 * Such exceptions are marked as "optional" in the specification for this 88 * interface. 89 * 90 * <p>This interface is a member of the 91 * <a href="{@docRoot}/../technotes/guides/collections/index.html"> 92 * Java Collections Framework</a>. 93 * 94 * @param <E> the type of elements in this list 95 * 96 * @author Josh Bloch 97 * @author Neal Gafter 98 * @see Collection 99 * @see Set 100 * @see ArrayList 101 * @see LinkedList 102 * @see Vector 103 * @see Arrays#asList(Object[]) 104 * @see Collections#nCopies(int, Object) 105 * @see Collections#EMPTY_LIST 106 * @see AbstractList 107 * @see AbstractSequentialList 108 * @since 1.2 109 */ 110 111 public interface List<E> extends Collection<E> { 112 // Query Operations 113 114 /** 115 * Returns the number of elements in this list. If this list contains 116 * more than {@code Integer.MAX_VALUE} elements, returns 117 * {@code Integer.MAX_VALUE}. 118 * 119 * @return the number of elements in this list 120 */ 121 int size(); 122 123 /** 124 * Returns {@code true} if this list contains no elements. 125 * 126 * @return {@code true} if this list contains no elements 127 */ 128 boolean isEmpty(); 129 130 /** 131 * Returns {@code true} if this list contains the specified element. 132 * More formally, returns {@code true} if and only if this list contains 133 * at least one element {@code e} such that 134 * {@code Objects.equals(o, e)}. 135 * 136 * @param o element whose presence in this list is to be tested 137 * @return {@code true} if this list contains the specified element 138 * @throws ClassCastException if the type of the specified element 139 * is incompatible with this list 140 * (<a href="Collection.html#optional-restrictions">optional</a>) 141 * @throws NullPointerException if the specified element is null and this 142 * list does not permit null elements 143 * (<a href="Collection.html#optional-restrictions">optional</a>) 144 */ 145 boolean contains(Object o); 146 147 /** 148 * Returns an iterator over the elements in this list in proper sequence. 149 * 150 * @return an iterator over the elements in this list in proper sequence 151 */ 152 Iterator<E> iterator(); 153 154 /** 155 * Returns an array containing all of the elements in this list in proper 156 * sequence (from first to last element). 157 * 158 * <p>The returned array will be "safe" in that no references to it are 159 * maintained by this list. (In other words, this method must 160 * allocate a new array even if this list is backed by an array). 161 * The caller is thus free to modify the returned array. 162 * 163 * <p>This method acts as bridge between array-based and collection-based 164 * APIs. 165 * 166 * @return an array containing all of the elements in this list in proper 167 * sequence 168 * @see Arrays#asList(Object[]) 169 */ 170 Object[] toArray(); 171 172 /** 173 * Returns an array containing all of the elements in this list in 174 * proper sequence (from first to last element); the runtime type of 175 * the returned array is that of the specified array. If the list fits 176 * in the specified array, it is returned therein. Otherwise, a new 177 * array is allocated with the runtime type of the specified array and 178 * the size of this list. 179 * 180 * <p>If the list fits in the specified array with room to spare (i.e., 181 * the array has more elements than the list), the element in the array 182 * immediately following the end of the list is set to {@code null}. 183 * (This is useful in determining the length of the list <i>only</i> if 184 * the caller knows that the list does not contain any null elements.) 185 * 186 * <p>Like the {@link #toArray()} method, this method acts as bridge between 187 * array-based and collection-based APIs. Further, this method allows 188 * precise control over the runtime type of the output array, and may, 189 * under certain circumstances, be used to save allocation costs. 190 * 191 * <p>Suppose {@code x} is a list known to contain only strings. 192 * The following code can be used to dump the list into a newly 193 * allocated array of {@code String}: 194 * 195 * <pre>{@code 196 * String[] y = x.toArray(new String[0]); 197 * }</pre> 198 * 199 * Note that {@code toArray(new Object[0])} is identical in function to 200 * {@code toArray()}. 201 * 202 * @param a the array into which the elements of this list are to 203 * be stored, if it is big enough; otherwise, a new array of the 204 * same runtime type is allocated for this purpose. 205 * @return an array containing the elements of this list 206 * @throws ArrayStoreException if the runtime type of the specified array 207 * is not a supertype of the runtime type of every element in 208 * this list 209 * @throws NullPointerException if the specified array is null 210 */ 211 <T> T[] toArray(T[] a); 212 213 214 // Modification Operations 215 216 /** 217 * Appends the specified element to the end of this list (optional 218 * operation). 219 * 220 * <p>Lists that support this operation may place limitations on what 221 * elements may be added to this list. In particular, some 222 * lists will refuse to add null elements, and others will impose 223 * restrictions on the type of elements that may be added. List 224 * classes should clearly specify in their documentation any restrictions 225 * on what elements may be added. 226 * 227 * @param e element to be appended to this list 228 * @return {@code true} (as specified by {@link Collection#add}) 229 * @throws UnsupportedOperationException if the {@code add} operation 230 * is not supported by this list 231 * @throws ClassCastException if the class of the specified element 232 * prevents it from being added to this list 233 * @throws NullPointerException if the specified element is null and this 234 * list does not permit null elements 235 * @throws IllegalArgumentException if some property of this element 236 * prevents it from being added to this list 237 */ 238 boolean add(E e); 239 240 /** 241 * Removes the first occurrence of the specified element from this list, 242 * if it is present (optional operation). If this list does not contain 243 * the element, it is unchanged. More formally, removes the element with 244 * the lowest index {@code i} such that 245 * {@code Objects.equals(o, get(i))} 246 * (if such an element exists). Returns {@code true} if this list 247 * contained the specified element (or equivalently, if this list changed 248 * as a result of the call). 249 * 250 * @param o element to be removed from this list, if present 251 * @return {@code true} if this list contained the specified element 252 * @throws ClassCastException if the type of the specified element 253 * is incompatible with this list 254 * (<a href="Collection.html#optional-restrictions">optional</a>) 255 * @throws NullPointerException if the specified element is null and this 256 * list does not permit null elements 257 * (<a href="Collection.html#optional-restrictions">optional</a>) 258 * @throws UnsupportedOperationException if the {@code remove} operation 259 * is not supported by this list 260 */ 261 boolean remove(Object o); 262 263 264 // Bulk Modification Operations 265 266 /** 267 * Returns {@code true} if this list contains all of the elements of the 268 * specified collection. 269 * 270 * @param c collection to be checked for containment in this list 271 * @return {@code true} if this list contains all of the elements of the 272 * specified collection 273 * @throws ClassCastException if the types of one or more elements 274 * in the specified collection are incompatible with this 275 * list 276 * (<a href="Collection.html#optional-restrictions">optional</a>) 277 * @throws NullPointerException if the specified collection contains one 278 * or more null elements and this list does not permit null 279 * elements 280 * (<a href="Collection.html#optional-restrictions">optional</a>), 281 * or if the specified collection is null 282 * @see #contains(Object) 283 */ 284 boolean containsAll(Collection<?> c); 285 286 /** 287 * Appends all of the elements in the specified collection to the end of 288 * this list, in the order that they are returned by the specified 289 * collection's iterator (optional operation). The behavior of this 290 * operation is undefined if the specified collection is modified while 291 * the operation is in progress. (Note that this will occur if the 292 * specified collection is this list, and it's nonempty.) 293 * 294 * @param c collection containing elements to be added to this list 295 * @return {@code true} if this list changed as a result of the call 296 * @throws UnsupportedOperationException if the {@code addAll} operation 297 * is not supported by this list 298 * @throws ClassCastException if the class of an element of the specified 299 * collection prevents it from being added to this list 300 * @throws NullPointerException if the specified collection contains one 301 * or more null elements and this list does not permit null 302 * elements, or if the specified collection is null 303 * @throws IllegalArgumentException if some property of an element of the 304 * specified collection prevents it from being added to this list 305 * @see #add(Object) 306 */ 307 boolean addAll(Collection<? extends E> c); 308 309 /** 310 * Inserts all of the elements in the specified collection into this 311 * list at the specified position (optional operation). Shifts the 312 * element currently at that position (if any) and any subsequent 313 * elements to the right (increases their indices). The new elements 314 * will appear in this list in the order that they are returned by the 315 * specified collection's iterator. The behavior of this operation is 316 * undefined if the specified collection is modified while the 317 * operation is in progress. (Note that this will occur if the specified 318 * collection is this list, and it's nonempty.) 319 * 320 * @param index index at which to insert the first element from the 321 * specified collection 322 * @param c collection containing elements to be added to this list 323 * @return {@code true} if this list changed as a result of the call 324 * @throws UnsupportedOperationException if the {@code addAll} operation 325 * is not supported by this list 326 * @throws ClassCastException if the class of an element of the specified 327 * collection prevents it from being added to this list 328 * @throws NullPointerException if the specified collection contains one 329 * or more null elements and this list does not permit null 330 * elements, or if the specified collection is null 331 * @throws IllegalArgumentException if some property of an element of the 332 * specified collection prevents it from being added to this list 333 * @throws IndexOutOfBoundsException if the index is out of range 334 * ({@code index < 0 || index > size()}) 335 */ 336 boolean addAll(int index, Collection<? extends E> c); 337 338 /** 339 * Removes from this list all of its elements that are contained in the 340 * specified collection (optional operation). 341 * 342 * @param c collection containing elements to be removed from this list 343 * @return {@code true} if this list changed as a result of the call 344 * @throws UnsupportedOperationException if the {@code removeAll} operation 345 * is not supported by this list 346 * @throws ClassCastException if the class of an element of this list 347 * is incompatible with the specified collection 348 * (<a href="Collection.html#optional-restrictions">optional</a>) 349 * @throws NullPointerException if this list contains a null element and the 350 * specified collection does not permit null elements 351 * (<a href="Collection.html#optional-restrictions">optional</a>), 352 * or if the specified collection is null 353 * @see #remove(Object) 354 * @see #contains(Object) 355 */ 356 boolean removeAll(Collection<?> c); 357 358 /** 359 * Retains only the elements in this list that are contained in the 360 * specified collection (optional operation). In other words, removes 361 * from this list all of its elements that are not contained in the 362 * specified collection. 363 * 364 * @param c collection containing elements to be retained in this list 365 * @return {@code true} if this list changed as a result of the call 366 * @throws UnsupportedOperationException if the {@code retainAll} operation 367 * is not supported by this list 368 * @throws ClassCastException if the class of an element of this list 369 * is incompatible with the specified collection 370 * (<a href="Collection.html#optional-restrictions">optional</a>) 371 * @throws NullPointerException if this list contains a null element and the 372 * specified collection does not permit null elements 373 * (<a href="Collection.html#optional-restrictions">optional</a>), 374 * or if the specified collection is null 375 * @see #remove(Object) 376 * @see #contains(Object) 377 */ 378 boolean retainAll(Collection<?> c); 379 380 /** 381 * Replaces each element of this list with the result of applying the 382 * operator to that element. Errors or runtime exceptions thrown by 383 * the operator are relayed to the caller. 384 * 385 * @implSpec 386 * The default implementation is equivalent to, for this {@code list}: 387 * <pre>{@code 388 * final ListIterator<E> li = list.listIterator(); 389 * while (li.hasNext()) { 390 * li.set(operator.apply(li.next())); 391 * } 392 * }</pre> 393 * 394 * If the list's list-iterator does not support the {@code set} operation 395 * then an {@code UnsupportedOperationException} will be thrown when 396 * replacing the first element. 397 * 398 * @param operator the operator to apply to each element 399 * @throws UnsupportedOperationException if this list is unmodifiable. 400 * Implementations may throw this exception if an element 401 * cannot be replaced or if, in general, modification is not 402 * supported 403 * @throws NullPointerException if the specified operator is null or 404 * if the operator result is a null value and this list does 405 * not permit null elements 406 * (<a href="Collection.html#optional-restrictions">optional</a>) 407 * @since 1.8 408 */ 409 default void replaceAll(UnaryOperator<E> operator) { 410 Objects.requireNonNull(operator); 411 final ListIterator<E> li = this.listIterator(); 412 while (li.hasNext()) { 413 li.set(operator.apply(li.next())); 414 } 415 } 416 417 /** 418 * Sorts this list according to the order induced by the specified 419 * {@link Comparator}. 420 * 421 * <p>All elements in this list must be <i>mutually comparable</i> using the 422 * specified comparator (that is, {@code c.compare(e1, e2)} must not throw 423 * a {@code ClassCastException} for any elements {@code e1} and {@code e2} 424 * in the list). 425 * 426 * <p>If the specified comparator is {@code null} then all elements in this 427 * list must implement the {@link Comparable} interface and the elements' 428 * {@linkplain Comparable natural ordering} should be used. 429 * 430 * <p>This list must be modifiable, but need not be resizable. 431 * 432 * @implSpec 433 * The default implementation obtains an array containing all elements in 434 * this list, sorts the array, and iterates over this list resetting each 435 * element from the corresponding position in the array. (This avoids the 436 * n<sup>2</sup> log(n) performance that would result from attempting 437 * to sort a linked list in place.) 438 * 439 * @implNote 440 * This implementation is a stable, adaptive, iterative mergesort that 441 * requires far fewer than n lg(n) comparisons when the input array is 442 * partially sorted, while offering the performance of a traditional 443 * mergesort when the input array is randomly ordered. If the input array 444 * is nearly sorted, the implementation requires approximately n 445 * comparisons. Temporary storage requirements vary from a small constant 446 * for nearly sorted input arrays to n/2 object references for randomly 447 * ordered input arrays. 448 * 449 * <p>The implementation takes equal advantage of ascending and 450 * descending order in its input array, and can take advantage of 451 * ascending and descending order in different parts of the same 452 * input array. It is well-suited to merging two or more sorted arrays: 453 * simply concatenate the arrays and sort the resulting array. 454 * 455 * <p>The implementation was adapted from Tim Peters's list sort for Python 456 * (<a href="http://svn.python.org/projects/python/trunk/Objects/listsort.txt"> 457 * TimSort</a>). It uses techniques from Peter McIlroy's "Optimistic 458 * Sorting and Information Theoretic Complexity", in Proceedings of the 459 * Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, pp 467-474, 460 * January 1993. 461 * 462 * @param c the {@code Comparator} used to compare list elements. 463 * A {@code null} value indicates that the elements' 464 * {@linkplain Comparable natural ordering} should be used 465 * @throws ClassCastException if the list contains elements that are not 466 * <i>mutually comparable</i> using the specified comparator 467 * @throws UnsupportedOperationException if the list's list-iterator does 468 * not support the {@code set} operation 469 * @throws IllegalArgumentException 470 * (<a href="Collection.html#optional-restrictions">optional</a>) 471 * if the comparator is found to violate the {@link Comparator} 472 * contract 473 * @since 1.8 474 */ 475 @SuppressWarnings({"unchecked", "rawtypes"}) 476 default void sort(Comparator<? super E> c) { 477 Object[] a = this.toArray(); 478 Arrays.sort(a, (Comparator) c); 479 ListIterator<E> i = this.listIterator(); 480 for (Object e : a) { 481 i.next(); 482 i.set((E) e); 483 } 484 } 485 486 /** 487 * Removes all of the elements from this list (optional operation). 488 * The list will be empty after this call returns. 489 * 490 * @throws UnsupportedOperationException if the {@code clear} operation 491 * is not supported by this list 492 */ 493 void clear(); 494 495 496 // Comparison and hashing 497 498 /** 499 * Compares the specified object with this list for equality. Returns 500 * {@code true} if and only if the specified object is also a list, both 501 * lists have the same size, and all corresponding pairs of elements in 502 * the two lists are <i>equal</i>. (Two elements {@code e1} and 503 * {@code e2} are <i>equal</i> if {@code Objects.equals(e1, e2)}.) 504 * In other words, two lists are defined to be 505 * equal if they contain the same elements in the same order. This 506 * definition ensures that the equals method works properly across 507 * different implementations of the {@code List} interface. 508 * 509 * @param o the object to be compared for equality with this list 510 * @return {@code true} if the specified object is equal to this list 511 */ 512 boolean equals(Object o); 513 514 /** 515 * Returns the hash code value for this list. The hash code of a list 516 * is defined to be the result of the following calculation: 517 * <pre>{@code 518 * int hashCode = 1; 519 * for (E e : list) 520 * hashCode = 31*hashCode + (e==null ? 0 : e.hashCode()); 521 * }</pre> 522 * This ensures that {@code list1.equals(list2)} implies that 523 * {@code list1.hashCode()==list2.hashCode()} for any two lists, 524 * {@code list1} and {@code list2}, as required by the general 525 * contract of {@link Object#hashCode}. 526 * 527 * @return the hash code value for this list 528 * @see Object#equals(Object) 529 * @see #equals(Object) 530 */ 531 int hashCode(); 532 533 534 // Positional Access Operations 535 536 /** 537 * Returns the element at the specified position in this list. 538 * 539 * @param index index of the element to return 540 * @return the element at the specified position in this list 541 * @throws IndexOutOfBoundsException if the index is out of range 542 * ({@code index < 0 || index >= size()}) 543 */ 544 E get(int index); 545 546 /** 547 * Replaces the element at the specified position in this list with the 548 * specified element (optional operation). 549 * 550 * @param index index of the element to replace 551 * @param element element to be stored at the specified position 552 * @return the element previously at the specified position 553 * @throws UnsupportedOperationException if the {@code set} operation 554 * is not supported by this list 555 * @throws ClassCastException if the class of the specified element 556 * prevents it from being added to this list 557 * @throws NullPointerException if the specified element is null and 558 * this list does not permit null elements 559 * @throws IllegalArgumentException if some property of the specified 560 * element prevents it from being added to this list 561 * @throws IndexOutOfBoundsException if the index is out of range 562 * ({@code index < 0 || index >= size()}) 563 */ 564 E set(int index, E element); 565 566 /** 567 * Inserts the specified element at the specified position in this list 568 * (optional operation). Shifts the element currently at that position 569 * (if any) and any subsequent elements to the right (adds one to their 570 * indices). 571 * 572 * @param index index at which the specified element is to be inserted 573 * @param element element to be inserted 574 * @throws UnsupportedOperationException if the {@code add} operation 575 * is not supported by this list 576 * @throws ClassCastException if the class of the specified element 577 * prevents it from being added to this list 578 * @throws NullPointerException if the specified element is null and 579 * this list does not permit null elements 580 * @throws IllegalArgumentException if some property of the specified 581 * element prevents it from being added to this list 582 * @throws IndexOutOfBoundsException if the index is out of range 583 * ({@code index < 0 || index > size()}) 584 */ 585 void add(int index, E element); 586 587 /** 588 * Removes the element at the specified position in this list (optional 589 * operation). Shifts any subsequent elements to the left (subtracts one 590 * from their indices). Returns the element that was removed from the 591 * list. 592 * 593 * @param index the index of the element to be removed 594 * @return the element previously at the specified position 595 * @throws UnsupportedOperationException if the {@code remove} operation 596 * is not supported by this list 597 * @throws IndexOutOfBoundsException if the index is out of range 598 * ({@code index < 0 || index >= size()}) 599 */ 600 E remove(int index); 601 602 603 // Search Operations 604 605 /** 606 * Returns the index of the first occurrence of the specified element 607 * in this list, or -1 if this list does not contain the element. 608 * More formally, returns the lowest index {@code i} such that 609 * {@code Objects.equals(o, get(i))}, 610 * or -1 if there is no such index. 611 * 612 * @param o element to search for 613 * @return the index of the first occurrence of the specified element in 614 * this list, or -1 if this list does not contain the element 615 * @throws ClassCastException if the type of the specified element 616 * is incompatible with this list 617 * (<a href="Collection.html#optional-restrictions">optional</a>) 618 * @throws NullPointerException if the specified element is null and this 619 * list does not permit null elements 620 * (<a href="Collection.html#optional-restrictions">optional</a>) 621 */ 622 int indexOf(Object o); 623 624 /** 625 * Returns the index of the last occurrence of the specified element 626 * in this list, or -1 if this list does not contain the element. 627 * More formally, returns the highest index {@code i} such that 628 * {@code Objects.equals(o, get(i))}, 629 * or -1 if there is no such index. 630 * 631 * @param o element to search for 632 * @return the index of the last occurrence of the specified element in 633 * this list, or -1 if this list does not contain the element 634 * @throws ClassCastException if the type of the specified element 635 * is incompatible with this list 636 * (<a href="Collection.html#optional-restrictions">optional</a>) 637 * @throws NullPointerException if the specified element is null and this 638 * list does not permit null elements 639 * (<a href="Collection.html#optional-restrictions">optional</a>) 640 */ 641 int lastIndexOf(Object o); 642 643 644 // List Iterators 645 646 /** 647 * Returns a list iterator over the elements in this list (in proper 648 * sequence). 649 * 650 * @return a list iterator over the elements in this list (in proper 651 * sequence) 652 */ 653 ListIterator<E> listIterator(); 654 655 /** 656 * Returns a list iterator over the elements in this list (in proper 657 * sequence), starting at the specified position in the list. 658 * The specified index indicates the first element that would be 659 * returned by an initial call to {@link ListIterator#next next}. 660 * An initial call to {@link ListIterator#previous previous} would 661 * return the element with the specified index minus one. 662 * 663 * @param index index of the first element to be returned from the 664 * list iterator (by a call to {@link ListIterator#next next}) 665 * @return a list iterator over the elements in this list (in proper 666 * sequence), starting at the specified position in the list 667 * @throws IndexOutOfBoundsException if the index is out of range 668 * ({@code index < 0 || index > size()}) 669 */ 670 ListIterator<E> listIterator(int index); 671 672 // View 673 674 /** 675 * Returns a view of the portion of this list between the specified 676 * {@code fromIndex}, inclusive, and {@code toIndex}, exclusive. (If 677 * {@code fromIndex} and {@code toIndex} are equal, the returned list is 678 * empty.) The returned list is backed by this list, so non-structural 679 * changes in the returned list are reflected in this list, and vice-versa. 680 * The returned list supports all of the optional list operations supported 681 * by this list.<p> 682 * 683 * This method eliminates the need for explicit range operations (of 684 * the sort that commonly exist for arrays). Any operation that expects 685 * a list can be used as a range operation by passing a subList view 686 * instead of a whole list. For example, the following idiom 687 * removes a range of elements from a list: 688 * <pre>{@code 689 * list.subList(from, to).clear(); 690 * }</pre> 691 * Similar idioms may be constructed for {@code indexOf} and 692 * {@code lastIndexOf}, and all of the algorithms in the 693 * {@code Collections} class can be applied to a subList.<p> 694 * 695 * The semantics of the list returned by this method become undefined if 696 * the backing list (i.e., this list) is <i>structurally modified</i> in 697 * any way other than via the returned list. (Structural modifications are 698 * those that change the size of this list, or otherwise perturb it in such 699 * a fashion that iterations in progress may yield incorrect results.) 700 * 701 * @param fromIndex low endpoint (inclusive) of the subList 702 * @param toIndex high endpoint (exclusive) of the subList 703 * @return a view of the specified range within this list 704 * @throws IndexOutOfBoundsException for an illegal endpoint index value 705 * ({@code fromIndex < 0 || toIndex > size || 706 * fromIndex > toIndex}) 707 */ 708 List<E> subList(int fromIndex, int toIndex); 709 710 /** 711 * Creates a {@link Spliterator} over the elements in this list. 712 * 713 * <p>The {@code Spliterator} reports {@link Spliterator#SIZED} and 714 * {@link Spliterator#ORDERED}. Implementations should document the 715 * reporting of additional characteristic values. 716 * 717 * @implSpec 718 * The default implementation creates a 719 * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator 720 * from the list's {@code Iterator}. The spliterator inherits the 721 * <em>fail-fast</em> properties of the list's iterator. 722 * 723 * @implNote 724 * The created {@code Spliterator} additionally reports 725 * {@link Spliterator#SUBSIZED}. 726 * 727 * @return a {@code Spliterator} over the elements in this list 728 * @since 1.8 729 */ 730 @Override 731 default Spliterator<E> spliterator() { 732 return Spliterators.spliterator(this, Spliterator.ORDERED); 733 } 734 }