    rev 48045 : 8177290: add copy factory methods for unmodifiable List, Set, Map
    8184690: add Collectors for collecting into unmodifiable List, Set, and Map
    Reviewed-by: alanb, briangoetz, dholmes, jrose, rriggs, scolebourne

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