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 <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}/../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 <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&nbsp;?&nbsp;e==null&nbsp;:&nbsp;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>{@code
 196      *     String[] y = x.toArray(new String[0]);
 197      * }</pre>
 198      *
 199      * Note that <tt>toArray(new Object[0])</tt> is identical in function to
 200      * <tt>toArray()</tt>.
 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 <tt>true</tt> (as specified by {@link Collection#add})
 229      * @throws UnsupportedOperationException if the <tt>add</tt> 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 <tt>i</tt> such that
 245      * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>
 246      * (if such an element exists).  Returns <tt>true</tt> 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 <tt>true</tt> 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 <tt>remove</tt> operation
 259      *         is not supported by this list
 260      */
 261     boolean remove(Object o);
 262 
 263 
 264     // Bulk Modification Operations
 265 
 266     /**
 267      * Returns <tt>true</tt> 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 <tt>true</tt> 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 <tt>true</tt> if this list changed as a result of the call
 296      * @throws UnsupportedOperationException if the <tt>addAll</tt> 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 <tt>true</tt> if this list changed as a result of the call
 324      * @throws UnsupportedOperationException if the <tt>addAll</tt> 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      *         (<tt>index &lt; 0 || index &gt; size()</tt>)
 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 <tt>true</tt> if this list changed as a result of the call
 344      * @throws UnsupportedOperationException if the <tt>removeAll</tt> 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 <tt>true</tt> if this list changed as a result of the call
 366      * @throws UnsupportedOperationException if the <tt>retainAll</tt> 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 <tt>clear</tt> 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      * <tt>true</tt> 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 <tt>e1</tt> and
 503      * <tt>e2</tt> are <i>equal</i> if <tt>(e1==null ? e2==null :
 504      * e1.equals(e2))</tt>.)  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 <tt>List</tt> interface.
 508      *
 509      * @param o the object to be compared for equality with this list
 510      * @return <tt>true</tt> 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 <tt>list1.equals(list2)</tt> implies that
 523      * <tt>list1.hashCode()==list2.hashCode()</tt> for any two lists,
 524      * <tt>list1</tt> and <tt>list2</tt>, 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      *         (<tt>index &lt; 0 || index &gt;= size()</tt>)
 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 <tt>set</tt> 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      *         (<tt>index &lt; 0 || index &gt;= size()</tt>)
 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 <tt>add</tt> 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      *         (<tt>index &lt; 0 || index &gt; size()</tt>)
 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 <tt>remove</tt> operation
 596      *         is not supported by this list
 597      * @throws IndexOutOfBoundsException if the index is out of range
 598      *         (<tt>index &lt; 0 || index &gt;= size()</tt>)
 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 <tt>i</tt> such that
 609      * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>,
 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 <tt>i</tt> such that
 628      * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>,
 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      * <tt>fromIndex</tt>, inclusive, and <tt>toIndex</tt>, exclusive.  (If
 677      * <tt>fromIndex</tt> and <tt>toIndex</tt> 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 <tt>indexOf</tt> and
 692      * <tt>lastIndexOf</tt>, and all of the algorithms in the
 693      * <tt>Collections</tt> 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      *         (<tt>fromIndex &lt; 0 || toIndex &gt; size ||
 706      *         fromIndex &gt; toIndex</tt>)
 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 }
--- EOF ---