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 * <h2><a name="immutable">Immutable List Factory Methods</a></h2> 91 * <p>The {@link List#of(Object...) List.of()} factory methods 92 * provide a convenient way to create immutable lists. The {@code List} 93 * instances created by these methods have the following characteristics: 94 * 95 * <ul> 96 * <li>They cannot be modified. Attempts to modify them result in 97 * an {@code UnsupportedOperationException}. 98 * <li>They disallow null elements. Attempts to create them with 99 * null elements result in {@code NullPointerException}. 100 * <li>They are serializable if all elements are serializable. 101 * </ul> 102 * 103 * <p>This interface is a member of the 104 * <a href="{@docRoot}/../technotes/guides/collections/index.html"> 105 * Java Collections Framework</a>. 106 * 107 * @param <E> the type of elements in this list 108 * 109 * @author Josh Bloch 110 * @author Neal Gafter 111 * @see Collection 112 * @see Set 113 * @see ArrayList 114 * @see LinkedList 115 * @see Vector 116 * @see Arrays#asList(Object[]) 117 * @see Collections#nCopies(int, Object) 118 * @see Collections#EMPTY_LIST 119 * @see AbstractList 120 * @see AbstractSequentialList 121 * @since 1.2 122 */ 123 124 public interface List<E> extends Collection<E> { 125 // Query Operations 126 127 /** 128 * Returns the number of elements in this list. If this list contains 129 * more than {@code Integer.MAX_VALUE} elements, returns 130 * {@code Integer.MAX_VALUE}. 131 * 132 * @return the number of elements in this list 133 */ 134 int size(); 135 136 /** 137 * Returns {@code true} if this list contains no elements. 138 * 139 * @return {@code true} if this list contains no elements 140 */ 141 boolean isEmpty(); 142 143 /** 144 * Returns {@code true} if this list contains the specified element. 145 * More formally, returns {@code true} if and only if this list contains 146 * at least one element {@code e} such that 147 * {@code Objects.equals(o, e)}. 148 * 149 * @param o element whose presence in this list is to be tested 150 * @return {@code true} if this list contains the specified element 151 * @throws ClassCastException if the type of the specified element 152 * is incompatible with this list 153 * (<a href="Collection.html#optional-restrictions">optional</a>) 154 * @throws NullPointerException if the specified element is null and this 155 * list does not permit null elements 156 * (<a href="Collection.html#optional-restrictions">optional</a>) 157 */ 158 boolean contains(Object o); 159 160 /** 161 * Returns an iterator over the elements in this list in proper sequence. 162 * 163 * @return an iterator over the elements in this list in proper sequence 164 */ 165 Iterator<E> iterator(); 166 167 /** 168 * Returns an array containing all of the elements in this list in proper 169 * sequence (from first to last element). 170 * 171 * <p>The returned array will be "safe" in that no references to it are 172 * maintained by this list. (In other words, this method must 173 * allocate a new array even if this list is backed by an array). 174 * The caller is thus free to modify the returned array. 175 * 176 * <p>This method acts as bridge between array-based and collection-based 177 * APIs. 178 * 179 * @return an array containing all of the elements in this list in proper 180 * sequence 181 * @see Arrays#asList(Object[]) 182 */ 183 Object[] toArray(); 184 185 /** 186 * Returns an array containing all of the elements in this list in 187 * proper sequence (from first to last element); the runtime type of 188 * the returned array is that of the specified array. If the list fits 189 * in the specified array, it is returned therein. Otherwise, a new 190 * array is allocated with the runtime type of the specified array and 191 * the size of this list. 192 * 193 * <p>If the list fits in the specified array with room to spare (i.e., 194 * the array has more elements than the list), the element in the array 195 * immediately following the end of the list is set to {@code null}. 196 * (This is useful in determining the length of the list <i>only</i> if 197 * the caller knows that the list does not contain any null elements.) 198 * 199 * <p>Like the {@link #toArray()} method, this method acts as bridge between 200 * array-based and collection-based APIs. Further, this method allows 201 * precise control over the runtime type of the output array, and may, 202 * under certain circumstances, be used to save allocation costs. 203 * 204 * <p>Suppose {@code x} is a list known to contain only strings. 205 * The following code can be used to dump the list into a newly 206 * allocated array of {@code String}: 207 * 208 * <pre>{@code 209 * String[] y = x.toArray(new String[0]); 210 * }</pre> 211 * 212 * Note that {@code toArray(new Object[0])} is identical in function to 213 * {@code toArray()}. 214 * 215 * @param a the array into which the elements of this list are to 216 * be stored, if it is big enough; otherwise, a new array of the 217 * same runtime type is allocated for this purpose. 218 * @return an array containing the elements of this list 219 * @throws ArrayStoreException if the runtime type of the specified array 220 * is not a supertype of the runtime type of every element in 221 * this list 222 * @throws NullPointerException if the specified array is null 223 */ 224 <T> T[] toArray(T[] a); 225 226 227 // Modification Operations 228 229 /** 230 * Appends the specified element to the end of this list (optional 231 * operation). 232 * 233 * <p>Lists that support this operation may place limitations on what 234 * elements may be added to this list. In particular, some 235 * lists will refuse to add null elements, and others will impose 236 * restrictions on the type of elements that may be added. List 237 * classes should clearly specify in their documentation any restrictions 238 * on what elements may be added. 239 * 240 * @param e element to be appended to this list 241 * @return {@code true} (as specified by {@link Collection#add}) 242 * @throws UnsupportedOperationException if the {@code add} operation 243 * is not supported by this list 244 * @throws ClassCastException if the class of the specified element 245 * prevents it from being added to this list 246 * @throws NullPointerException if the specified element is null and this 247 * list does not permit null elements 248 * @throws IllegalArgumentException if some property of this element 249 * prevents it from being added to this list 250 */ 251 boolean add(E e); 252 253 /** 254 * Removes the first occurrence of the specified element from this list, 255 * if it is present (optional operation). If this list does not contain 256 * the element, it is unchanged. More formally, removes the element with 257 * the lowest index {@code i} such that 258 * {@code Objects.equals(o, get(i))} 259 * (if such an element exists). Returns {@code true} if this list 260 * contained the specified element (or equivalently, if this list changed 261 * as a result of the call). 262 * 263 * @param o element to be removed from this list, if present 264 * @return {@code true} if this list contained the specified element 265 * @throws ClassCastException if the type of the specified element 266 * is incompatible with this list 267 * (<a href="Collection.html#optional-restrictions">optional</a>) 268 * @throws NullPointerException if the specified element is null and this 269 * list does not permit null elements 270 * (<a href="Collection.html#optional-restrictions">optional</a>) 271 * @throws UnsupportedOperationException if the {@code remove} operation 272 * is not supported by this list 273 */ 274 boolean remove(Object o); 275 276 277 // Bulk Modification Operations 278 279 /** 280 * Returns {@code true} if this list contains all of the elements of the 281 * specified collection. 282 * 283 * @param c collection to be checked for containment in this list 284 * @return {@code true} if this list contains all of the elements of the 285 * specified collection 286 * @throws ClassCastException if the types of one or more elements 287 * in the specified collection are incompatible with this 288 * list 289 * (<a href="Collection.html#optional-restrictions">optional</a>) 290 * @throws NullPointerException if the specified collection contains one 291 * or more null elements and this list does not permit null 292 * elements 293 * (<a href="Collection.html#optional-restrictions">optional</a>), 294 * or if the specified collection is null 295 * @see #contains(Object) 296 */ 297 boolean containsAll(Collection<?> c); 298 299 /** 300 * Appends all of the elements in the specified collection to the end of 301 * this list, in the order that they are returned by the specified 302 * collection's iterator (optional operation). The behavior of this 303 * operation is undefined if the specified collection is modified while 304 * the operation is in progress. (Note that this will occur if the 305 * specified collection is this list, and it's nonempty.) 306 * 307 * @param c collection containing elements to be added to this list 308 * @return {@code true} if this list changed as a result of the call 309 * @throws UnsupportedOperationException if the {@code addAll} operation 310 * is not supported by this list 311 * @throws ClassCastException if the class of an element of the specified 312 * collection prevents it from being added to this list 313 * @throws NullPointerException if the specified collection contains one 314 * or more null elements and this list does not permit null 315 * elements, or if the specified collection is null 316 * @throws IllegalArgumentException if some property of an element of the 317 * specified collection prevents it from being added to this list 318 * @see #add(Object) 319 */ 320 boolean addAll(Collection<? extends E> c); 321 322 /** 323 * Inserts all of the elements in the specified collection into this 324 * list at the specified position (optional operation). Shifts the 325 * element currently at that position (if any) and any subsequent 326 * elements to the right (increases their indices). The new elements 327 * will appear in this list in the order that they are returned by the 328 * specified collection's iterator. The behavior of this operation is 329 * undefined if the specified collection is modified while the 330 * operation is in progress. (Note that this will occur if the specified 331 * collection is this list, and it's nonempty.) 332 * 333 * @param index index at which to insert the first element from the 334 * specified collection 335 * @param c collection containing elements to be added to this list 336 * @return {@code true} if this list changed as a result of the call 337 * @throws UnsupportedOperationException if the {@code addAll} operation 338 * is not supported by this list 339 * @throws ClassCastException if the class of an element of the specified 340 * collection prevents it from being added to this list 341 * @throws NullPointerException if the specified collection contains one 342 * or more null elements and this list does not permit null 343 * elements, or if the specified collection is null 344 * @throws IllegalArgumentException if some property of an element of the 345 * specified collection prevents it from being added to this list 346 * @throws IndexOutOfBoundsException if the index is out of range 347 * ({@code index < 0 || index > size()}) 348 */ 349 boolean addAll(int index, Collection<? extends E> c); 350 351 /** 352 * Removes from this list all of its elements that are contained in the 353 * specified collection (optional operation). 354 * 355 * @param c collection containing elements to be removed from this list 356 * @return {@code true} if this list changed as a result of the call 357 * @throws UnsupportedOperationException if the {@code removeAll} operation 358 * is not supported by this list 359 * @throws ClassCastException if the class of an element of this list 360 * is incompatible with the specified collection 361 * (<a href="Collection.html#optional-restrictions">optional</a>) 362 * @throws NullPointerException if this list contains a null element and the 363 * specified collection does not permit null elements 364 * (<a href="Collection.html#optional-restrictions">optional</a>), 365 * or if the specified collection is null 366 * @see #remove(Object) 367 * @see #contains(Object) 368 */ 369 boolean removeAll(Collection<?> c); 370 371 /** 372 * Retains only the elements in this list that are contained in the 373 * specified collection (optional operation). In other words, removes 374 * from this list all of its elements that are not contained in the 375 * specified collection. 376 * 377 * @param c collection containing elements to be retained in this list 378 * @return {@code true} if this list changed as a result of the call 379 * @throws UnsupportedOperationException if the {@code retainAll} operation 380 * is not supported by this list 381 * @throws ClassCastException if the class of an element of this list 382 * is incompatible with the specified collection 383 * (<a href="Collection.html#optional-restrictions">optional</a>) 384 * @throws NullPointerException if this list contains a null element and the 385 * specified collection does not permit null elements 386 * (<a href="Collection.html#optional-restrictions">optional</a>), 387 * or if the specified collection is null 388 * @see #remove(Object) 389 * @see #contains(Object) 390 */ 391 boolean retainAll(Collection<?> c); 392 393 /** 394 * Replaces each element of this list with the result of applying the 395 * operator to that element. Errors or runtime exceptions thrown by 396 * the operator are relayed to the caller. 397 * 398 * @implSpec 399 * The default implementation is equivalent to, for this {@code list}: 400 * <pre>{@code 401 * final ListIterator<E> li = list.listIterator(); 402 * while (li.hasNext()) { 403 * li.set(operator.apply(li.next())); 404 * } 405 * }</pre> 406 * 407 * If the list's list-iterator does not support the {@code set} operation 408 * then an {@code UnsupportedOperationException} will be thrown when 409 * replacing the first element. 410 * 411 * @param operator the operator to apply to each element 412 * @throws UnsupportedOperationException if this list is unmodifiable. 413 * Implementations may throw this exception if an element 414 * cannot be replaced or if, in general, modification is not 415 * supported 416 * @throws NullPointerException if the specified operator is null or 417 * if the operator result is a null value and this list does 418 * not permit null elements 419 * (<a href="Collection.html#optional-restrictions">optional</a>) 420 * @since 1.8 421 */ 422 default void replaceAll(UnaryOperator<E> operator) { 423 Objects.requireNonNull(operator); 424 final ListIterator<E> li = this.listIterator(); 425 while (li.hasNext()) { 426 li.set(operator.apply(li.next())); 427 } 428 } 429 430 /** 431 * Sorts this list according to the order induced by the specified 432 * {@link Comparator}. 433 * 434 * <p>All elements in this list must be <i>mutually comparable</i> using the 435 * specified comparator (that is, {@code c.compare(e1, e2)} must not throw 436 * a {@code ClassCastException} for any elements {@code e1} and {@code e2} 437 * in the list). 438 * 439 * <p>If the specified comparator is {@code null} then all elements in this 440 * list must implement the {@link Comparable} interface and the elements' 441 * {@linkplain Comparable natural ordering} should be used. 442 * 443 * <p>This list must be modifiable, but need not be resizable. 444 * 445 * @implSpec 446 * The default implementation obtains an array containing all elements in 447 * this list, sorts the array, and iterates over this list resetting each 448 * element from the corresponding position in the array. (This avoids the 449 * n<sup>2</sup> log(n) performance that would result from attempting 450 * to sort a linked list in place.) 451 * 452 * @implNote 453 * This implementation is a stable, adaptive, iterative mergesort that 454 * requires far fewer than n lg(n) comparisons when the input array is 455 * partially sorted, while offering the performance of a traditional 456 * mergesort when the input array is randomly ordered. If the input array 457 * is nearly sorted, the implementation requires approximately n 458 * comparisons. Temporary storage requirements vary from a small constant 459 * for nearly sorted input arrays to n/2 object references for randomly 460 * ordered input arrays. 461 * 462 * <p>The implementation takes equal advantage of ascending and 463 * descending order in its input array, and can take advantage of 464 * ascending and descending order in different parts of the same 465 * input array. It is well-suited to merging two or more sorted arrays: 466 * simply concatenate the arrays and sort the resulting array. 467 * 468 * <p>The implementation was adapted from Tim Peters's list sort for Python 469 * (<a href="http://svn.python.org/projects/python/trunk/Objects/listsort.txt"> 470 * TimSort</a>). It uses techniques from Peter McIlroy's "Optimistic 471 * Sorting and Information Theoretic Complexity", in Proceedings of the 472 * Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, pp 467-474, 473 * January 1993. 474 * 475 * @param c the {@code Comparator} used to compare list elements. 476 * A {@code null} value indicates that the elements' 477 * {@linkplain Comparable natural ordering} should be used 478 * @throws ClassCastException if the list contains elements that are not 479 * <i>mutually comparable</i> using the specified comparator 480 * @throws UnsupportedOperationException if the list's list-iterator does 481 * not support the {@code set} operation 482 * @throws IllegalArgumentException 483 * (<a href="Collection.html#optional-restrictions">optional</a>) 484 * if the comparator is found to violate the {@link Comparator} 485 * contract 486 * @since 1.8 487 */ 488 @SuppressWarnings({"unchecked", "rawtypes"}) 489 default void sort(Comparator<? super E> c) { 490 Object[] a = this.toArray(); 491 Arrays.sort(a, (Comparator) c); 492 ListIterator<E> i = this.listIterator(); 493 for (Object e : a) { 494 i.next(); 495 i.set((E) e); 496 } 497 } 498 499 /** 500 * Removes all of the elements from this list (optional operation). 501 * The list will be empty after this call returns. 502 * 503 * @throws UnsupportedOperationException if the {@code clear} operation 504 * is not supported by this list 505 */ 506 void clear(); 507 508 509 // Comparison and hashing 510 511 /** 512 * Compares the specified object with this list for equality. Returns 513 * {@code true} if and only if the specified object is also a list, both 514 * lists have the same size, and all corresponding pairs of elements in 515 * the two lists are <i>equal</i>. (Two elements {@code e1} and 516 * {@code e2} are <i>equal</i> if {@code Objects.equals(e1, e2)}.) 517 * In other words, two lists are defined to be 518 * equal if they contain the same elements in the same order. This 519 * definition ensures that the equals method works properly across 520 * different implementations of the {@code List} interface. 521 * 522 * @param o the object to be compared for equality with this list 523 * @return {@code true} if the specified object is equal to this list 524 */ 525 boolean equals(Object o); 526 527 /** 528 * Returns the hash code value for this list. The hash code of a list 529 * is defined to be the result of the following calculation: 530 * <pre>{@code 531 * int hashCode = 1; 532 * for (E e : list) 533 * hashCode = 31*hashCode + (e==null ? 0 : e.hashCode()); 534 * }</pre> 535 * This ensures that {@code list1.equals(list2)} implies that 536 * {@code list1.hashCode()==list2.hashCode()} for any two lists, 537 * {@code list1} and {@code list2}, as required by the general 538 * contract of {@link Object#hashCode}. 539 * 540 * @return the hash code value for this list 541 * @see Object#equals(Object) 542 * @see #equals(Object) 543 */ 544 int hashCode(); 545 546 547 // Positional Access Operations 548 549 /** 550 * Returns the element at the specified position in this list. 551 * 552 * @param index index of the element to return 553 * @return the element at the specified position in this list 554 * @throws IndexOutOfBoundsException if the index is out of range 555 * ({@code index < 0 || index >= size()}) 556 */ 557 E get(int index); 558 559 /** 560 * Replaces the element at the specified position in this list with the 561 * specified element (optional operation). 562 * 563 * @param index index of the element to replace 564 * @param element element to be stored at the specified position 565 * @return the element previously at the specified position 566 * @throws UnsupportedOperationException if the {@code set} operation 567 * is not supported by this list 568 * @throws ClassCastException if the class of the specified element 569 * prevents it from being added to this list 570 * @throws NullPointerException if the specified element is null and 571 * this list does not permit null elements 572 * @throws IllegalArgumentException if some property of the specified 573 * element prevents it from being added to this list 574 * @throws IndexOutOfBoundsException if the index is out of range 575 * ({@code index < 0 || index >= size()}) 576 */ 577 E set(int index, E element); 578 579 /** 580 * Inserts the specified element at the specified position in this list 581 * (optional operation). Shifts the element currently at that position 582 * (if any) and any subsequent elements to the right (adds one to their 583 * indices). 584 * 585 * @param index index at which the specified element is to be inserted 586 * @param element element to be inserted 587 * @throws UnsupportedOperationException if the {@code add} operation 588 * is not supported by this list 589 * @throws ClassCastException if the class of the specified element 590 * prevents it from being added to this list 591 * @throws NullPointerException if the specified element is null and 592 * this list does not permit null elements 593 * @throws IllegalArgumentException if some property of the specified 594 * element prevents it from being added to this list 595 * @throws IndexOutOfBoundsException if the index is out of range 596 * ({@code index < 0 || index > size()}) 597 */ 598 void add(int index, E element); 599 600 /** 601 * Removes the element at the specified position in this list (optional 602 * operation). Shifts any subsequent elements to the left (subtracts one 603 * from their indices). Returns the element that was removed from the 604 * list. 605 * 606 * @param index the index of the element to be removed 607 * @return the element previously at the specified position 608 * @throws UnsupportedOperationException if the {@code remove} operation 609 * is not supported by this list 610 * @throws IndexOutOfBoundsException if the index is out of range 611 * ({@code index < 0 || index >= size()}) 612 */ 613 E remove(int index); 614 615 616 // Search Operations 617 618 /** 619 * Returns the index of the first occurrence of the specified element 620 * in this list, or -1 if this list does not contain the element. 621 * More formally, returns the lowest index {@code i} such that 622 * {@code Objects.equals(o, get(i))}, 623 * or -1 if there is no such index. 624 * 625 * @param o element to search for 626 * @return the index of the first occurrence of the specified element in 627 * this list, or -1 if this list does not contain the element 628 * @throws ClassCastException if the type of the specified element 629 * is incompatible with this list 630 * (<a href="Collection.html#optional-restrictions">optional</a>) 631 * @throws NullPointerException if the specified element is null and this 632 * list does not permit null elements 633 * (<a href="Collection.html#optional-restrictions">optional</a>) 634 */ 635 int indexOf(Object o); 636 637 /** 638 * Returns the index of the last occurrence of the specified element 639 * in this list, or -1 if this list does not contain the element. 640 * More formally, returns the highest index {@code i} such that 641 * {@code Objects.equals(o, get(i))}, 642 * or -1 if there is no such index. 643 * 644 * @param o element to search for 645 * @return the index of the last occurrence of the specified element in 646 * this list, or -1 if this list does not contain the element 647 * @throws ClassCastException if the type of the specified element 648 * is incompatible with this list 649 * (<a href="Collection.html#optional-restrictions">optional</a>) 650 * @throws NullPointerException if the specified element is null and this 651 * list does not permit null elements 652 * (<a href="Collection.html#optional-restrictions">optional</a>) 653 */ 654 int lastIndexOf(Object o); 655 656 657 // List Iterators 658 659 /** 660 * Returns a list iterator over the elements in this list (in proper 661 * sequence). 662 * 663 * @return a list iterator over the elements in this list (in proper 664 * sequence) 665 */ 666 ListIterator<E> listIterator(); 667 668 /** 669 * Returns a list iterator over the elements in this list (in proper 670 * sequence), starting at the specified position in the list. 671 * The specified index indicates the first element that would be 672 * returned by an initial call to {@link ListIterator#next next}. 673 * An initial call to {@link ListIterator#previous previous} would 674 * return the element with the specified index minus one. 675 * 676 * @param index index of the first element to be returned from the 677 * list iterator (by a call to {@link ListIterator#next next}) 678 * @return a list iterator over the elements in this list (in proper 679 * sequence), starting at the specified position in the list 680 * @throws IndexOutOfBoundsException if the index is out of range 681 * ({@code index < 0 || index > size()}) 682 */ 683 ListIterator<E> listIterator(int index); 684 685 // View 686 687 /** 688 * Returns a view of the portion of this list between the specified 689 * {@code fromIndex}, inclusive, and {@code toIndex}, exclusive. (If 690 * {@code fromIndex} and {@code toIndex} are equal, the returned list is 691 * empty.) The returned list is backed by this list, so non-structural 692 * changes in the returned list are reflected in this list, and vice-versa. 693 * The returned list supports all of the optional list operations supported 694 * by this list.<p> 695 * 696 * This method eliminates the need for explicit range operations (of 697 * the sort that commonly exist for arrays). Any operation that expects 698 * a list can be used as a range operation by passing a subList view 699 * instead of a whole list. For example, the following idiom 700 * removes a range of elements from a list: 701 * <pre>{@code 702 * list.subList(from, to).clear(); 703 * }</pre> 704 * Similar idioms may be constructed for {@code indexOf} and 705 * {@code lastIndexOf}, and all of the algorithms in the 706 * {@code Collections} class can be applied to a subList.<p> 707 * 708 * The semantics of the list returned by this method become undefined if 709 * the backing list (i.e., this list) is <i>structurally modified</i> in 710 * any way other than via the returned list. (Structural modifications are 711 * those that change the size of this list, or otherwise perturb it in such 712 * a fashion that iterations in progress may yield incorrect results.) 713 * 714 * @param fromIndex low endpoint (inclusive) of the subList 715 * @param toIndex high endpoint (exclusive) of the subList 716 * @return a view of the specified range within this list 717 * @throws IndexOutOfBoundsException for an illegal endpoint index value 718 * ({@code fromIndex < 0 || toIndex > size || 719 * fromIndex > toIndex}) 720 */ 721 List<E> subList(int fromIndex, int toIndex); 722 723 /** 724 * Creates a {@link Spliterator} over the elements in this list. 725 * 726 * <p>The {@code Spliterator} reports {@link Spliterator#SIZED} and 727 * {@link Spliterator#ORDERED}. Implementations should document the 728 * reporting of additional characteristic values. 729 * 730 * @implSpec 731 * The default implementation creates a 732 * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator 733 * from the list's {@code Iterator}. The spliterator inherits the 734 * <em>fail-fast</em> properties of the list's iterator. 735 * 736 * @implNote 737 * The created {@code Spliterator} additionally reports 738 * {@link Spliterator#SUBSIZED}. 739 * 740 * @return a {@code Spliterator} over the elements in this list 741 * @since 1.8 742 */ 743 @Override 744 default Spliterator<E> spliterator() { 745 return Spliterators.spliterator(this, Spliterator.ORDERED); 746 } 747 748 /** 749 * Creates an immutable list containing zero elements. 750 * 751 * See <a href="#immutable">Immutable List Factory Methods</a> for details. 752 * 753 * @param <E> the list's element type 754 * @return the newly created list 755 * 756 * @since 1.9 757 */ 758 static <E> List<E> of() { 759 return Collections.emptyList(); 760 } 761 762 /** 763 * Creates an immutable list containing one element. 764 * 765 * See <a href="#immutable">Immutable List Factory Methods</a> for details. 766 * 767 * @param <E> the list's element type 768 * @param e1 the single list element 769 * @return the newly created list 770 * @throws NullPointerException if the element is null 771 * 772 * @since 1.9 773 */ 774 static <E> List<E> of(E e1) { 775 return Collections.singletonList(Objects.requireNonNull(e1)); 776 } 777 778 /** 779 * Creates an immutable list containing two elements. 780 * 781 * See <a href="#immutable">Immutable List Factory Methods</a> for details. 782 * 783 * @param <E> the list's element type 784 * @param e1 the first list element 785 * @param e2 the second list element 786 * @return the newly created list 787 * @throws NullPointerException if an element is null 788 * 789 * @since 1.9 790 */ 791 static <E> List<E> of(E e1, E e2) { 792 return Collections.unmodifiableList( 793 Arrays.asList(Objects.requireNonNull(e1), 794 Objects.requireNonNull(e2))); 795 } 796 797 /** 798 * Creates an immutable list containing three elements. 799 * 800 * See <a href="#immutable">Immutable List Factory Methods</a> for details. 801 * 802 * @param <E> the list's element type 803 * @param e1 the first list element 804 * @param e2 the second list element 805 * @param e3 the third list element 806 * @return the newly created list 807 * @throws NullPointerException if an element is null 808 * 809 * @since 1.9 810 */ 811 static <E> List<E> of(E e1, E e2, E e3) { 812 return Collections.unmodifiableList( 813 Arrays.asList(Objects.requireNonNull(e1), 814 Objects.requireNonNull(e2), 815 Objects.requireNonNull(e3))); 816 } 817 818 /** 819 * Creates an immutable list containing four elements. 820 * 821 * See <a href="#immutable">Immutable List Factory Methods</a> for details. 822 * 823 * @param <E> the list's element type 824 * @param e1 the first list element 825 * @param e2 the second list element 826 * @param e3 the third list element 827 * @param e4 the fourth list element 828 * @return the newly created list 829 * @throws NullPointerException if an element is null 830 * 831 * @since 1.9 832 */ 833 static <E> List<E> of(E e1, E e2, E e3, E e4) { 834 return Collections.unmodifiableList( 835 Arrays.asList(Objects.requireNonNull(e1), 836 Objects.requireNonNull(e2), 837 Objects.requireNonNull(e3), 838 Objects.requireNonNull(e4))); 839 } 840 841 /** 842 * Creates an immutable list containing five elements. 843 * 844 * See <a href="#immutable">Immutable List Factory Methods</a> for details. 845 * 846 * @param <E> the list's element type 847 * @param e1 the first list element 848 * @param e2 the second list element 849 * @param e3 the third list element 850 * @param e4 the fourth list element 851 * @param e5 the fifth list element 852 * @return the newly created list 853 * @throws NullPointerException if an element is null 854 * 855 * @since 1.9 856 */ 857 static <E> List<E> of(E e1, E e2, E e3, E e4, E e5) { 858 return Collections.unmodifiableList( 859 Arrays.asList(Objects.requireNonNull(e1), 860 Objects.requireNonNull(e2), 861 Objects.requireNonNull(e3), 862 Objects.requireNonNull(e4), 863 Objects.requireNonNull(e5))); 864 } 865 866 /** 867 * Creates an immutable list containing six elements. 868 * 869 * See <a href="#immutable">Immutable List Factory Methods</a> for details. 870 * 871 * @param <E> the list's element type 872 * @param e1 the first list element 873 * @param e2 the second list element 874 * @param e3 the third list element 875 * @param e4 the fourth list element 876 * @param e5 the fifth list element 877 * @param e6 the sixth list element 878 * @return the newly created list 879 * @throws NullPointerException if an element is null 880 * 881 * @since 1.9 882 */ 883 static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6) { 884 return Collections.unmodifiableList( 885 Arrays.asList(Objects.requireNonNull(e1), 886 Objects.requireNonNull(e2), 887 Objects.requireNonNull(e3), 888 Objects.requireNonNull(e4), 889 Objects.requireNonNull(e5), 890 Objects.requireNonNull(e6))); 891 } 892 893 /** 894 * Creates an immutable list containing seven elements. 895 * 896 * See <a href="#immutable">Immutable List Factory Methods</a> for details. 897 * 898 * @param <E> the list's element type 899 * @param e1 the first list element 900 * @param e2 the second list element 901 * @param e3 the third list element 902 * @param e4 the fourth list element 903 * @param e5 the fifth list element 904 * @param e6 the sixth list element 905 * @param e7 the seventh list element 906 * @return the newly created list 907 * @throws NullPointerException if an element is null 908 * 909 * @since 1.9 910 */ 911 static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7) { 912 return Collections.unmodifiableList( 913 Arrays.asList(Objects.requireNonNull(e1), 914 Objects.requireNonNull(e2), 915 Objects.requireNonNull(e3), 916 Objects.requireNonNull(e4), 917 Objects.requireNonNull(e5), 918 Objects.requireNonNull(e6), 919 Objects.requireNonNull(e7))); 920 } 921 922 /** 923 * Creates an immutable list containing eight elements. 924 * 925 * See <a href="#immutable">Immutable List Factory Methods</a> for details. 926 * 927 * @param <E> the list's element type 928 * @param e1 the first list element 929 * @param e2 the second list element 930 * @param e3 the third list element 931 * @param e4 the fourth list element 932 * @param e5 the fifth list element 933 * @param e6 the sixth list element 934 * @param e7 the seventh list element 935 * @param e8 the eighth list element 936 * @return the newly created list 937 * @throws NullPointerException if an element is null 938 * 939 * @since 1.9 940 */ 941 static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) { 942 return Collections.unmodifiableList( 943 Arrays.asList(Objects.requireNonNull(e1), 944 Objects.requireNonNull(e2), 945 Objects.requireNonNull(e3), 946 Objects.requireNonNull(e4), 947 Objects.requireNonNull(e5), 948 Objects.requireNonNull(e6), 949 Objects.requireNonNull(e7), 950 Objects.requireNonNull(e8))); 951 } 952 953 /** 954 * Creates an immutable list containing nine elements. 955 * 956 * See <a href="#immutable">Immutable List Factory Methods</a> for details. 957 * 958 * @param <E> the list's element type 959 * @param e1 the first list element 960 * @param e2 the second list element 961 * @param e3 the third list element 962 * @param e4 the fourth list element 963 * @param e5 the fifth list element 964 * @param e6 the sixth list element 965 * @param e7 the seventh list element 966 * @param e8 the eighth list element 967 * @param e9 the ninth list element 968 * @return the newly created list 969 * @throws NullPointerException if an element is null 970 * 971 * @since 1.9 972 */ 973 static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) { 974 return Collections.unmodifiableList( 975 Arrays.asList(Objects.requireNonNull(e1), 976 Objects.requireNonNull(e2), 977 Objects.requireNonNull(e3), 978 Objects.requireNonNull(e4), 979 Objects.requireNonNull(e5), 980 Objects.requireNonNull(e6), 981 Objects.requireNonNull(e7), 982 Objects.requireNonNull(e8), 983 Objects.requireNonNull(e9))); 984 } 985 986 /** 987 * Creates an immutable list containing ten elements. 988 * 989 * See <a href="#immutable">Immutable List Factory Methods</a> for details. 990 * 991 * @param <E> the list's element type 992 * @param e1 the first list element 993 * @param e2 the second list element 994 * @param e3 the third list element 995 * @param e4 the fourth list element 996 * @param e5 the fifth list element 997 * @param e6 the sixth list element 998 * @param e7 the seventh list element 999 * @param e8 the eighth list element 1000 * @param e9 the ninth list element 1001 * @param e10 the tenth list element 1002 * @return the newly created list 1003 * @throws NullPointerException if an element is null 1004 * 1005 * @since 1.9 1006 */ 1007 static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10) { 1008 return Collections.unmodifiableList( 1009 Arrays.asList(Objects.requireNonNull(e1), 1010 Objects.requireNonNull(e2), 1011 Objects.requireNonNull(e3), 1012 Objects.requireNonNull(e4), 1013 Objects.requireNonNull(e5), 1014 Objects.requireNonNull(e6), 1015 Objects.requireNonNull(e7), 1016 Objects.requireNonNull(e8), 1017 Objects.requireNonNull(e9), 1018 Objects.requireNonNull(e10))); 1019 } 1020 1021 /** 1022 * Creates an immutable list containing an arbitrary number of elements. 1023 * 1024 * See <a href="#immutable">Immutable List Factory Methods</a> for details. 1025 * 1026 * @apiNote 1027 * This method also accepts a single array as an argument. The element type of 1028 * the resulting list will be the component type of the array, and the size of 1029 * the list will be equal to the length of the array. To create a list with 1030 * a single element that is an array, do the following: 1031 * 1032 * <pre>{@code 1033 * String[] array = ... ; 1034 * List<String[]> list = List.<String[]>of(array); 1035 * }</pre> 1036 * 1037 * This will cause the {@link List#of(Object) List.of(E)} method 1038 * to be invoked instead. 1039 * 1040 * @param <E> the list's element type 1041 * @param es the elements to be contained in the list 1042 * @return the newly created list 1043 * @throws NullPointerException if an element is null 1044 * 1045 * @since 1.9 1046 */ 1047 @SafeVarargs 1048 @SuppressWarnings("varargs") 1049 static <E> List<E> of(E... es) { 1050 for (E e : es) { 1051 Objects.requireNonNull(e); 1052 } 1053 // NOTE: this can allow a null element to slip through 1054 return Collections.unmodifiableList(Arrays.asList(es)); 1055 } 1056 }