List.java revision d2449bb576ad1e3a3877364e5e1ae28625f69e35
1/* 2 * Copyright (c) 1997, 2010, 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 26package java.util; 27 28import 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 <tt>e1</tt> and <tt>e2</tt> 38 * such that <tt>e1.equals(e2)</tt>, 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 <tt>List</tt> interface places additional stipulations, beyond those 45 * specified in the <tt>Collection</tt> interface, on the contracts of the 46 * <tt>iterator</tt>, <tt>add</tt>, <tt>remove</tt>, <tt>equals</tt>, and 47 * <tt>hashCode</tt> methods. Declarations for other inherited methods are 48 * also included here for convenience.<p> 49 * 50 * The <tt>List</tt> 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 <tt>LinkedList</tt> 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 <tt>List</tt> interface provides a special iterator, called a 59 * <tt>ListIterator</tt>, that allows element insertion and replacement, and 60 * bidirectional access in addition to the normal operations that the 61 * <tt>Iterator</tt> 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 <tt>List</tt> 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 <tt>List</tt> 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 <tt>equals</tt> and <tt>hashCode</tt> 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 * <tt>NullPointerException</tt> or <tt>ClassCastException</tt>. 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}openjdk-redirect.html?v=8&path=/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 111public 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 <tt>Integer.MAX_VALUE</tt> elements, returns 117 * <tt>Integer.MAX_VALUE</tt>. 118 * 119 * @return the number of elements in this list 120 */ 121 int size(); 122 123 /** 124 * Returns <tt>true</tt> if this list contains no elements. 125 * 126 * @return <tt>true</tt> if this list contains no elements 127 */ 128 boolean isEmpty(); 129 130 /** 131 * Returns <tt>true</tt> if this list contains the specified element. 132 * More formally, returns <tt>true</tt> if and only if this list contains 133 * at least one element <tt>e</tt> such that 134 * <tt>(o==null ? e==null : o.equals(e))</tt>. 135 * 136 * @param o element whose presence in this list is to be tested 137 * @return <tt>true</tt> 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 <tt>null</tt>. 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 <tt>x</tt> 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 <tt>String</tt>: 194 * 195 * <pre> 196 * String[] y = x.toArray(new String[0]);</pre> 197 * 198 * Note that <tt>toArray(new Object[0])</tt> is identical in function to 199 * <tt>toArray()</tt>. 200 * 201 * @param a the array into which the elements of this list are to 202 * be stored, if it is big enough; otherwise, a new array of the 203 * same runtime type is allocated for this purpose. 204 * @return an array containing the elements of this list 205 * @throws ArrayStoreException if the runtime type of the specified array 206 * is not a supertype of the runtime type of every element in 207 * this list 208 * @throws NullPointerException if the specified array is null 209 */ 210 <T> T[] toArray(T[] a); 211 212 213 // Modification Operations 214 215 /** 216 * Appends the specified element to the end of this list (optional 217 * operation). 218 * 219 * <p>Lists that support this operation may place limitations on what 220 * elements may be added to this list. In particular, some 221 * lists will refuse to add null elements, and others will impose 222 * restrictions on the type of elements that may be added. List 223 * classes should clearly specify in their documentation any restrictions 224 * on what elements may be added. 225 * 226 * @param e element to be appended to this list 227 * @return <tt>true</tt> (as specified by {@link Collection#add}) 228 * @throws UnsupportedOperationException if the <tt>add</tt> operation 229 * is not supported by this list 230 * @throws ClassCastException if the class of the specified element 231 * prevents it from being added to this list 232 * @throws NullPointerException if the specified element is null and this 233 * list does not permit null elements 234 * @throws IllegalArgumentException if some property of this element 235 * prevents it from being added to this list 236 */ 237 boolean add(E e); 238 239 /** 240 * Removes the first occurrence of the specified element from this list, 241 * if it is present (optional operation). If this list does not contain 242 * the element, it is unchanged. More formally, removes the element with 243 * the lowest index <tt>i</tt> such that 244 * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt> 245 * (if such an element exists). Returns <tt>true</tt> if this list 246 * contained the specified element (or equivalently, if this list changed 247 * as a result of the call). 248 * 249 * @param o element to be removed from this list, if present 250 * @return <tt>true</tt> if this list contained the specified element 251 * @throws ClassCastException if the type of the specified element 252 * is incompatible with this list 253 * (<a href="Collection.html#optional-restrictions">optional</a>) 254 * @throws NullPointerException if the specified element is null and this 255 * list does not permit null elements 256 * (<a href="Collection.html#optional-restrictions">optional</a>) 257 * @throws UnsupportedOperationException if the <tt>remove</tt> operation 258 * is not supported by this list 259 */ 260 boolean remove(Object o); 261 262 263 // Bulk Modification Operations 264 265 /** 266 * Returns <tt>true</tt> if this list contains all of the elements of the 267 * specified collection. 268 * 269 * @param c collection to be checked for containment in this list 270 * @return <tt>true</tt> if this list contains all of the elements of the 271 * specified collection 272 * @throws ClassCastException if the types of one or more elements 273 * in the specified collection are incompatible with this 274 * list 275 * (<a href="Collection.html#optional-restrictions">optional</a>) 276 * @throws NullPointerException if the specified collection contains one 277 * or more null elements and this list does not permit null 278 * elements 279 * (<a href="Collection.html#optional-restrictions">optional</a>), 280 * or if the specified collection is null 281 * @see #contains(Object) 282 */ 283 boolean containsAll(Collection<?> c); 284 285 /** 286 * Appends all of the elements in the specified collection to the end of 287 * this list, in the order that they are returned by the specified 288 * collection's iterator (optional operation). The behavior of this 289 * operation is undefined if the specified collection is modified while 290 * the operation is in progress. (Note that this will occur if the 291 * specified collection is this list, and it's nonempty.) 292 * 293 * @param c collection containing elements to be added to this list 294 * @return <tt>true</tt> if this list changed as a result of the call 295 * @throws UnsupportedOperationException if the <tt>addAll</tt> operation 296 * is not supported by this list 297 * @throws ClassCastException if the class of an element of the specified 298 * collection prevents it from being added to this list 299 * @throws NullPointerException if the specified collection contains one 300 * or more null elements and this list does not permit null 301 * elements, or if the specified collection is null 302 * @throws IllegalArgumentException if some property of an element of the 303 * specified collection prevents it from being added to this list 304 * @see #add(Object) 305 */ 306 boolean addAll(Collection<? extends E> c); 307 308 /** 309 * Inserts all of the elements in the specified collection into this 310 * list at the specified position (optional operation). Shifts the 311 * element currently at that position (if any) and any subsequent 312 * elements to the right (increases their indices). The new elements 313 * will appear in this list in the order that they are returned by the 314 * specified collection's iterator. The behavior of this operation is 315 * undefined if the specified collection is modified while the 316 * operation is in progress. (Note that this will occur if the specified 317 * collection is this list, and it's nonempty.) 318 * 319 * @param index index at which to insert the first element from the 320 * specified collection 321 * @param c collection containing elements to be added to this list 322 * @return <tt>true</tt> if this list changed as a result of the call 323 * @throws UnsupportedOperationException if the <tt>addAll</tt> operation 324 * is not supported by this list 325 * @throws ClassCastException if the class of an element of the specified 326 * collection prevents it from being added to this list 327 * @throws NullPointerException if the specified collection contains one 328 * or more null elements and this list does not permit null 329 * elements, or if the specified collection is null 330 * @throws IllegalArgumentException if some property of an element of the 331 * specified collection prevents it from being added to this list 332 * @throws IndexOutOfBoundsException if the index is out of range 333 * (<tt>index < 0 || index > size()</tt>) 334 */ 335 boolean addAll(int index, Collection<? extends E> c); 336 337 /** 338 * Removes from this list all of its elements that are contained in the 339 * specified collection (optional operation). 340 * 341 * @param c collection containing elements to be removed from this list 342 * @return <tt>true</tt> if this list changed as a result of the call 343 * @throws UnsupportedOperationException if the <tt>removeAll</tt> operation 344 * is not supported by this list 345 * @throws ClassCastException if the class of an element of this list 346 * is incompatible with the specified collection 347 * (<a href="Collection.html#optional-restrictions">optional</a>) 348 * @throws NullPointerException if this list contains a null element and the 349 * specified collection does not permit null elements 350 * (<a href="Collection.html#optional-restrictions">optional</a>), 351 * or if the specified collection is null 352 * @see #remove(Object) 353 * @see #contains(Object) 354 */ 355 boolean removeAll(Collection<?> c); 356 357 /** 358 * Retains only the elements in this list that are contained in the 359 * specified collection (optional operation). In other words, removes 360 * from this list all of its elements that are not contained in the 361 * specified collection. 362 * 363 * @param c collection containing elements to be retained in this list 364 * @return <tt>true</tt> if this list changed as a result of the call 365 * @throws UnsupportedOperationException if the <tt>retainAll</tt> operation 366 * is not supported by this list 367 * @throws ClassCastException if the class of an element of this list 368 * is incompatible with the specified collection 369 * (<a href="Collection.html#optional-restrictions">optional</a>) 370 * @throws NullPointerException if this list contains a null element and the 371 * specified collection does not permit null elements 372 * (<a href="Collection.html#optional-restrictions">optional</a>), 373 * or if the specified collection is null 374 * @see #remove(Object) 375 * @see #contains(Object) 376 */ 377 boolean retainAll(Collection<?> c); 378 379 /** 380 * Removes all of the elements from this list (optional operation). 381 * The list will be empty after this call returns. 382 * 383 * @throws UnsupportedOperationException if the <tt>clear</tt> operation 384 * is not supported by this list 385 */ 386 void clear(); 387 388 389 // Comparison and hashing 390 391 /** 392 * Compares the specified object with this list for equality. Returns 393 * <tt>true</tt> if and only if the specified object is also a list, both 394 * lists have the same size, and all corresponding pairs of elements in 395 * the two lists are <i>equal</i>. (Two elements <tt>e1</tt> and 396 * <tt>e2</tt> are <i>equal</i> if <tt>(e1==null ? e2==null : 397 * e1.equals(e2))</tt>.) In other words, two lists are defined to be 398 * equal if they contain the same elements in the same order. This 399 * definition ensures that the equals method works properly across 400 * different implementations of the <tt>List</tt> interface. 401 * 402 * @param o the object to be compared for equality with this list 403 * @return <tt>true</tt> if the specified object is equal to this list 404 */ 405 boolean equals(Object o); 406 407 /** 408 * Returns the hash code value for this list. The hash code of a list 409 * is defined to be the result of the following calculation: 410 * <pre> 411 * int hashCode = 1; 412 * for (E e : list) 413 * hashCode = 31*hashCode + (e==null ? 0 : e.hashCode()); 414 * </pre> 415 * This ensures that <tt>list1.equals(list2)</tt> implies that 416 * <tt>list1.hashCode()==list2.hashCode()</tt> for any two lists, 417 * <tt>list1</tt> and <tt>list2</tt>, as required by the general 418 * contract of {@link Object#hashCode}. 419 * 420 * @return the hash code value for this list 421 * @see Object#equals(Object) 422 * @see #equals(Object) 423 */ 424 int hashCode(); 425 426 427 // Positional Access Operations 428 429 /** 430 * Returns the element at the specified position in this list. 431 * 432 * @param index index of the element to return 433 * @return the element at the specified position in this list 434 * @throws IndexOutOfBoundsException if the index is out of range 435 * (<tt>index < 0 || index >= size()</tt>) 436 */ 437 E get(int index); 438 439 /** 440 * Replaces the element at the specified position in this list with the 441 * specified element (optional operation). 442 * 443 * @param index index of the element to replace 444 * @param element element to be stored at the specified position 445 * @return the element previously at the specified position 446 * @throws UnsupportedOperationException if the <tt>set</tt> operation 447 * is not supported by this list 448 * @throws ClassCastException if the class of the specified element 449 * prevents it from being added to this list 450 * @throws NullPointerException if the specified element is null and 451 * this list does not permit null elements 452 * @throws IllegalArgumentException if some property of the specified 453 * element prevents it from being added to this list 454 * @throws IndexOutOfBoundsException if the index is out of range 455 * (<tt>index < 0 || index >= size()</tt>) 456 */ 457 E set(int index, E element); 458 459 /** 460 * Inserts the specified element at the specified position in this list 461 * (optional operation). Shifts the element currently at that position 462 * (if any) and any subsequent elements to the right (adds one to their 463 * indices). 464 * 465 * @param index index at which the specified element is to be inserted 466 * @param element element to be inserted 467 * @throws UnsupportedOperationException if the <tt>add</tt> operation 468 * is not supported by this list 469 * @throws ClassCastException if the class of the specified element 470 * prevents it from being added to this list 471 * @throws NullPointerException if the specified element is null and 472 * this list does not permit null elements 473 * @throws IllegalArgumentException if some property of the specified 474 * element prevents it from being added to this list 475 * @throws IndexOutOfBoundsException if the index is out of range 476 * (<tt>index < 0 || index > size()</tt>) 477 */ 478 void add(int index, E element); 479 480 /** 481 * Removes the element at the specified position in this list (optional 482 * operation). Shifts any subsequent elements to the left (subtracts one 483 * from their indices). Returns the element that was removed from the 484 * list. 485 * 486 * @param index the index of the element to be removed 487 * @return the element previously at the specified position 488 * @throws UnsupportedOperationException if the <tt>remove</tt> operation 489 * is not supported by this list 490 * @throws IndexOutOfBoundsException if the index is out of range 491 * (<tt>index < 0 || index >= size()</tt>) 492 */ 493 E remove(int index); 494 495 496 // Search Operations 497 498 /** 499 * Returns the index of the first occurrence of the specified element 500 * in this list, or -1 if this list does not contain the element. 501 * More formally, returns the lowest index <tt>i</tt> such that 502 * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>, 503 * or -1 if there is no such index. 504 * 505 * @param o element to search for 506 * @return the index of the first occurrence of the specified element in 507 * this list, or -1 if this list does not contain the element 508 * @throws ClassCastException if the type of the specified element 509 * is incompatible with this list 510 * (<a href="Collection.html#optional-restrictions">optional</a>) 511 * @throws NullPointerException if the specified element is null and this 512 * list does not permit null elements 513 * (<a href="Collection.html#optional-restrictions">optional</a>) 514 */ 515 int indexOf(Object o); 516 517 /** 518 * Returns the index of the last occurrence of the specified element 519 * in this list, or -1 if this list does not contain the element. 520 * More formally, returns the highest index <tt>i</tt> such that 521 * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>, 522 * or -1 if there is no such index. 523 * 524 * @param o element to search for 525 * @return the index of the last occurrence of the specified element in 526 * this list, or -1 if this list does not contain the element 527 * @throws ClassCastException if the type of the specified element 528 * is incompatible with this list 529 * (<a href="Collection.html#optional-restrictions">optional</a>) 530 * @throws NullPointerException if the specified element is null and this 531 * list does not permit null elements 532 * (<a href="Collection.html#optional-restrictions">optional</a>) 533 */ 534 int lastIndexOf(Object o); 535 536 537 // List Iterators 538 539 /** 540 * Returns a list iterator over the elements in this list (in proper 541 * sequence). 542 * 543 * @return a list iterator over the elements in this list (in proper 544 * sequence) 545 */ 546 ListIterator<E> listIterator(); 547 548 /** 549 * Returns a list iterator over the elements in this list (in proper 550 * sequence), starting at the specified position in the list. 551 * The specified index indicates the first element that would be 552 * returned by an initial call to {@link ListIterator#next next}. 553 * An initial call to {@link ListIterator#previous previous} would 554 * return the element with the specified index minus one. 555 * 556 * @param index index of the first element to be returned from the 557 * list iterator (by a call to {@link ListIterator#next next}) 558 * @return a list iterator over the elements in this list (in proper 559 * sequence), starting at the specified position in the list 560 * @throws IndexOutOfBoundsException if the index is out of range 561 * ({@code index < 0 || index > size()}) 562 */ 563 ListIterator<E> listIterator(int index); 564 565 // View 566 567 /** 568 * Returns a view of the portion of this list between the specified 569 * <tt>fromIndex</tt>, inclusive, and <tt>toIndex</tt>, exclusive. (If 570 * <tt>fromIndex</tt> and <tt>toIndex</tt> are equal, the returned list is 571 * empty.) The returned list is backed by this list, so non-structural 572 * changes in the returned list are reflected in this list, and vice-versa. 573 * The returned list supports all of the optional list operations supported 574 * by this list.<p> 575 * 576 * This method eliminates the need for explicit range operations (of 577 * the sort that commonly exist for arrays). Any operation that expects 578 * a list can be used as a range operation by passing a subList view 579 * instead of a whole list. For example, the following idiom 580 * removes a range of elements from a list: 581 * <pre> 582 * list.subList(from, to).clear(); 583 * </pre> 584 * Similar idioms may be constructed for <tt>indexOf</tt> and 585 * <tt>lastIndexOf</tt>, and all of the algorithms in the 586 * <tt>Collections</tt> class can be applied to a subList.<p> 587 * 588 * The semantics of the list returned by this method become undefined if 589 * the backing list (i.e., this list) is <i>structurally modified</i> in 590 * any way other than via the returned list. (Structural modifications are 591 * those that change the size of this list, or otherwise perturb it in such 592 * a fashion that iterations in progress may yield incorrect results.) 593 * 594 * @param fromIndex low endpoint (inclusive) of the subList 595 * @param toIndex high endpoint (exclusive) of the subList 596 * @return a view of the specified range within this list 597 * @throws IndexOutOfBoundsException for an illegal endpoint index value 598 * (<tt>fromIndex < 0 || toIndex > size || 599 * fromIndex > toIndex</tt>) 600 */ 601 List<E> subList(int fromIndex, int toIndex); 602 603 /** 604 * Creates a {@link Spliterator} over the elements in this list. 605 * 606 * <p>The {@code Spliterator} reports {@link Spliterator#SIZED} and 607 * {@link Spliterator#ORDERED}. Implementations should document the 608 * reporting of additional characteristic values. 609 * 610 * @implSpec 611 * The default implementation creates a 612 * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator 613 * from the list's {@code Iterator}. The spliterator inherits the 614 * <em>fail-fast</em> properties of the list's iterator. 615 * 616 * @implNote 617 * The created {@code Spliterator} additionally reports 618 * {@link Spliterator#SUBSIZED}. 619 * 620 * @return a {@code Spliterator} over the elements in this list 621 * @since 1.8 622 */ 623 @Override 624 default Spliterator<E> spliterator() { 625 return Spliterators.spliterator(this, Spliterator.ORDERED); 626 } 627 628 /** 629 * Replaces each element of this list with the result of applying the 630 * operator to that element. Errors or runtime exceptions thrown by 631 * the operator are relayed to the caller. 632 * 633 * @implSpec 634 * The default implementation is equivalent to, for this {@code list}: 635 * <pre>{@code 636 * final ListIterator<E> li = list.listIterator(); 637 * while (li.hasNext()) { 638 * li.set(operator.apply(li.next())); 639 * } 640 * }</pre> 641 * 642 * If the list's list-iterator does not support the {@code set} operation 643 * then an {@code UnsupportedOperationException} will be thrown when 644 * replacing the first element. 645 * 646 * @param operator the operator to apply to each element 647 * @throws UnsupportedOperationException if this list is unmodifiable. 648 * Implementations may throw this exception if an element 649 * cannot be replaced or if, in general, modification is not 650 * supported 651 * @throws NullPointerException if the specified operator is null or 652 * if the operator result is a null value and this list does 653 * not permit null elements 654 * (<a href="Collection.html#optional-restrictions">optional</a>) 655 * @since 1.8 656 */ 657 default void replaceAll(UnaryOperator<E> operator) { 658 Objects.requireNonNull(operator); 659 final ListIterator<E> li = this.listIterator(); 660 while (li.hasNext()) { 661 li.set(operator.apply(li.next())); 662 } 663 } 664 665 /** 666 * Sorts this list using the supplied {@code Comparator} to compare elements. 667 * 668 * @implSpec 669 * The default implementation is equivalent to, for this {@code list}: 670 * <pre>Collections.sort(list, c)</pre> 671 * 672 * @param c the {@code Comparator} used to compare list elements. 673 * A {@code null} value indicates that the elements' 674 * {@linkplain Comparable natural ordering} should be used 675 * @throws ClassCastException if the list contains elements that are not 676 * <i>mutually comparable</i> using the specified comparator 677 * @throws UnsupportedOperationException if the list's list-iterator does 678 * not support the {@code set} operation 679 * @throws IllegalArgumentException 680 * (<a href="Collection.html#optional-restrictions">optional</a>) 681 * if the comparator is found to violate the {@link Comparator} 682 * contract 683 * @since 1.8 684 */ 685 default void sort(Comparator<? super E> c) { 686 Collections.sort(this, c); 687 } 688} 689