1 /*

     2  * Copyright 1997-2007 Sun Microsystems, Inc.  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.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 package java.util;

    27 

    28 /**

    29  * An ordered collection (also known as a <i>sequence</i>).  The user of this

    30  * interface has precise control over where in the list each element is

    31  * inserted.  The user can access elements by their integer index (position in

    32  * the list), and search for elements in the list.<p>

    33  *

    34  * Unlike sets, lists typically allow duplicate elements.  More formally,

    35  * lists typically allow pairs of elements <tt>e1</tt> and <tt>e2</tt>

    36  * such that <tt>e1.equals(e2)</tt>, and they typically allow multiple

    37  * null elements if they allow null elements at all.  It is not inconceivable

    38  * that someone might wish to implement a list that prohibits duplicates, by

    39  * throwing runtime exceptions when the user attempts to insert them, but we

    40  * expect this usage to be rare.<p>

    41  *

    42  * The <tt>List</tt> interface places additional stipulations, beyond those

    43  * specified in the <tt>Collection</tt> interface, on the contracts of the

    44  * <tt>iterator</tt>, <tt>add</tt>, <tt>remove</tt>, <tt>equals</tt>, and

    45  * <tt>hashCode</tt> methods.  Declarations for other inherited methods are

    46  * also included here for convenience.<p>

    47  *

    48  * The <tt>List</tt> interface provides four methods for positional (indexed)

    49  * access to list elements.  Lists (like Java arrays) are zero based.  Note

    50  * that these operations may execute in time proportional to the index value

    51  * for some implementations (the <tt>LinkedList</tt> class, for

    52  * example). Thus, iterating over the elements in a list is typically

    53  * preferable to indexing through it if the caller does not know the

    54  * implementation.<p>

    55  *

    56  * The <tt>List</tt> interface provides a special iterator, called a

    57  * <tt>ListIterator</tt>, that allows element insertion and replacement, and

    58  * bidirectional access in addition to the normal operations that the

    59  * <tt>Iterator</tt> interface provides.  A method is provided to obtain a

    60  * list iterator that starts at a specified position in the list.<p>

    61  *

    62  * The <tt>List</tt> interface provides two methods to search for a specified

    63  * object.  From a performance standpoint, these methods should be used with

    64  * caution.  In many implementations they will perform costly linear

    65  * searches.<p>

    66  *

    67  * The <tt>List</tt> interface provides two methods to efficiently insert and

    68  * remove multiple elements at an arbitrary point in the list.<p>

    69  *

    70  * Note: While it is permissible for lists to contain themselves as elements,

    71  * extreme caution is advised: the <tt>equals</tt> and <tt>hashCode</tt>

    72  * methods are no longer well defined on such a list.

    73  *

    74  * <p>Some list implementations have restrictions on the elements that

    75  * they may contain.  For example, some implementations prohibit null elements,

    76  * and some have restrictions on the types of their elements.  Attempting to

    77  * add an ineligible element throws an unchecked exception, typically

    78  * <tt>NullPointerException</tt> or <tt>ClassCastException</tt>.  Attempting

    79  * to query the presence of an ineligible element may throw an exception,

    80  * or it may simply return false; some implementations will exhibit the former

    81  * behavior and some will exhibit the latter.  More generally, attempting an

    82  * operation on an ineligible element whose completion would not result in

    83  * the insertion of an ineligible element into the list may throw an

    84  * exception or it may succeed, at the option of the implementation.

    85  * Such exceptions are marked as "optional" in the specification for this

    86  * interface.

    87  *

    88  * <p>This interface is a member of the

    89  * <a href="{@docRoot}/../technotes/guides/collections/index.html">

    90  * Java Collections Framework</a>.

    91  *

    92  * @author  Josh Bloch

    93  * @author  Neal Gafter

    94  * @see Collection

    95  * @see Set

    96  * @see ArrayList

    97  * @see LinkedList

    98  * @see Vector

    99  * @see Arrays#asList(Object[])

   100  * @see Collections#nCopies(int, Object)

   101  * @see Collections#EMPTY_LIST

   102  * @see AbstractList

   103  * @see AbstractSequentialList

   104  * @since 1.2

   105  */

   106 

   107 public interface List<E> extends Collection<E> {

   108     // Query Operations

   109 

   110     /**

   111      * Returns the number of elements in this list.  If this list contains

   112      * more than <tt>Integer.MAX_VALUE</tt> elements, returns

   113      * <tt>Integer.MAX_VALUE</tt>.

   114      *

   115      * @return the number of elements in this list

   116      */

   117     int size();

   118 

   119     /**

   120      * Returns <tt>true</tt> if this list contains no elements.

   121      *

   122      * @return <tt>true</tt> if this list contains no elements

   123      */

   124     boolean isEmpty();

   125 

   126     /**

   127      * Returns <tt>true</tt> if this list contains the specified element.

   128      * More formally, returns <tt>true</tt> if and only if this list contains

   129      * at least one element <tt>e</tt> such that

   130      * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.

   131      *

   132      * @param o element whose presence in this list is to be tested

   133      * @return <tt>true</tt> if this list contains the specified element

   134      * @throws ClassCastException if the type of the specified element

   135      *         is incompatible with this list (optional)

   136      * @throws NullPointerException if the specified element is null and this

   137      *         list does not permit null elements (optional)

   138      */

   139     boolean contains(Object o);

   140 

   141     /**

   142      * Returns an iterator over the elements in this list in proper sequence.

   143      *

   144      * @return an iterator over the elements in this list in proper sequence

   145      */

   146     Iterator<E> iterator();

   147 

   148     /**

   149      * Returns an array containing all of the elements in this list in proper

   150      * sequence (from first to last element).

   151      *

   152      * <p>The returned array will be "safe" in that no references to it are

   153      * maintained by this list.  (In other words, this method must

   154      * allocate a new array even if this list is backed by an array).

   155      * The caller is thus free to modify the returned array.

   156      *

   157      * <p>This method acts as bridge between array-based and collection-based

   158      * APIs.

   159      *

   160      * @return an array containing all of the elements in this list in proper

   161      *         sequence

   162      * @see Arrays#asList(Object[])

   163      */

   164     Object[] toArray();

   165 

   166     /**

   167      * Returns an array containing all of the elements in this list in

   168      * proper sequence (from first to last element); the runtime type of

   169      * the returned array is that of the specified array.  If the list fits

   170      * in the specified array, it is returned therein.  Otherwise, a new

   171      * array is allocated with the runtime type of the specified array and

   172      * the size of this list.

   173      *

   174      * <p>If the list fits in the specified array with room to spare (i.e.,

   175      * the array has more elements than the list), the element in the array

   176      * immediately following the end of the list is set to <tt>null</tt>.

   177      * (This is useful in determining the length of the list <i>only</i> if

   178      * the caller knows that the list does not contain any null elements.)

   179      *

   180      * <p>Like the {@link #toArray()} method, this method acts as bridge between

   181      * array-based and collection-based APIs.  Further, this method allows

   182      * precise control over the runtime type of the output array, and may,

   183      * under certain circumstances, be used to save allocation costs.

   184      *

   185      * <p>Suppose <tt>x</tt> is a list known to contain only strings.

   186      * The following code can be used to dump the list into a newly

   187      * allocated array of <tt>String</tt>:

   188      *

   189      * <pre>

   190      *     String[] y = x.toArray(new String[0]);</pre>

   191      *

   192      * Note that <tt>toArray(new Object[0])</tt> is identical in function to

   193      * <tt>toArray()</tt>.

   194      *

   195      * @param a the array into which the elements of this list are to

   196      *          be stored, if it is big enough; otherwise, a new array of the

   197      *          same runtime type is allocated for this purpose.

   198      * @return an array containing the elements of this list

   199      * @throws ArrayStoreException if the runtime type of the specified array

   200      *         is not a supertype of the runtime type of every element in

   201      *         this list

   202      * @throws NullPointerException if the specified array is null

   203      */

   204     <T> T[] toArray(T[] a);

   205 

   206 

   207     // Modification Operations

   208 

   209     /**

   210      * Appends the specified element to the end of this list (optional

   211      * operation).

   212      *

   213      * <p>Lists that support this operation may place limitations on what

   214      * elements may be added to this list.  In particular, some

   215      * lists will refuse to add null elements, and others will impose

   216      * restrictions on the type of elements that may be added.  List

   217      * classes should clearly specify in their documentation any restrictions

   218      * on what elements may be added.

   219      *

   220      * @param e element to be appended to this list

   221      * @return <tt>true</tt> (as specified by {@link Collection#add})

   222      * @throws UnsupportedOperationException if the <tt>add</tt> operation

   223      *         is not supported by this list

   224      * @throws ClassCastException if the class of the specified element

   225      *         prevents it from being added to this list

   226      * @throws NullPointerException if the specified element is null and this

   227      *         list does not permit null elements

   228      * @throws IllegalArgumentException if some property of this element

   229      *         prevents it from being added to this list

   230      */

   231     boolean add(E e);

   232 

   233     /**

   234      * Removes the first occurrence of the specified element from this list,

   235      * if it is present (optional operation).  If this list does not contain

   236      * the element, it is unchanged.  More formally, removes the element with

   237      * the lowest index <tt>i</tt> such that

   238      * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>

   239      * (if such an element exists).  Returns <tt>true</tt> if this list

   240      * contained the specified element (or equivalently, if this list changed

   241      * as a result of the call).

   242      *

   243      * @param o element to be removed from this list, if present

   244      * @return <tt>true</tt> if this list contained the specified element

   245      * @throws ClassCastException if the type of the specified element

   246      *         is incompatible with this list (optional)

   247      * @throws NullPointerException if the specified element is null and this

   248      *         list does not permit null elements (optional)

   249      * @throws UnsupportedOperationException if the <tt>remove</tt> operation

   250      *         is not supported by this list

   251      */

   252     boolean remove(Object o);

   253 

   254 

   255     // Bulk Modification Operations

   256 

   257     /**

   258      * Returns <tt>true</tt> if this list contains all of the elements of the

   259      * specified collection.

   260      *

   261      * @param  c collection to be checked for containment in this list

   262      * @return <tt>true</tt> if this list contains all of the elements of the

   263      *         specified collection

   264      * @throws ClassCastException if the types of one or more elements

   265      *         in the specified collection are incompatible with this

   266      *         list (optional)

   267      * @throws NullPointerException if the specified collection contains one

   268      *         or more null elements and this list does not permit null

   269      *         elements (optional), or if the specified collection is null

   270      * @see #contains(Object)

   271      */

   272     boolean containsAll(Collection<?> c);

   273 

   274     /**

   275      * Appends all of the elements in the specified collection to the end of

   276      * this list, in the order that they are returned by the specified

   277      * collection's iterator (optional operation).  The behavior of this

   278      * operation is undefined if the specified collection is modified while

   279      * the operation is in progress.  (Note that this will occur if the

   280      * specified collection is this list, and it's nonempty.)

   281      *

   282      * @param c collection containing elements to be added to this list

   283      * @return <tt>true</tt> if this list changed as a result of the call

   284      * @throws UnsupportedOperationException if the <tt>addAll</tt> operation

   285      *         is not supported by this list

   286      * @throws ClassCastException if the class of an element of the specified

   287      *         collection prevents it from being added to this list

   288      * @throws NullPointerException if the specified collection contains one

   289      *         or more null elements and this list does not permit null

   290      *         elements, or if the specified collection is null

   291      * @throws IllegalArgumentException if some property of an element of the

   292      *         specified collection prevents it from being added to this list

   293      * @see #add(Object)

   294      */

   295     boolean addAll(Collection<? extends E> c);

   296 

   297     /**

   298      * Inserts all of the elements in the specified collection into this

   299      * list at the specified position (optional operation).  Shifts the

   300      * element currently at that position (if any) and any subsequent

   301      * elements to the right (increases their indices).  The new elements

   302      * will appear in this list in the order that they are returned by the

   303      * specified collection's iterator.  The behavior of this operation is

   304      * undefined if the specified collection is modified while the

   305      * operation is in progress.  (Note that this will occur if the specified

   306      * collection is this list, and it's nonempty.)

   307      *

   308      * @param index index at which to insert the first element from the

   309      *              specified collection

   310      * @param c collection containing elements to be added to this list

   311      * @return <tt>true</tt> if this list changed as a result of the call

   312      * @throws UnsupportedOperationException if the <tt>addAll</tt> operation

   313      *         is not supported by this list

   314      * @throws ClassCastException if the class of an element of the specified

   315      *         collection prevents it from being added to this list

   316      * @throws NullPointerException if the specified collection contains one

   317      *         or more null elements and this list does not permit null

   318      *         elements, or if the specified collection is null

   319      * @throws IllegalArgumentException if some property of an element of the

   320      *         specified collection prevents it from being added to this list

   321      * @throws IndexOutOfBoundsException if the index is out of range

   322      *         (<tt>index &lt; 0 || index &gt; size()</tt>)

   323      */

   324     boolean addAll(int index, Collection<? extends E> c);

   325 

   326     /**

   327      * Removes from this list all of its elements that are contained in the

   328      * specified collection (optional operation).

   329      *

   330      * @param c collection containing elements to be removed from this list

   331      * @return <tt>true</tt> if this list changed as a result of the call

   332      * @throws UnsupportedOperationException if the <tt>removeAll</tt> operation

   333      *         is not supported by this list

   334      * @throws ClassCastException if the class of an element of this list

   335      *         is incompatible with the specified collection (optional)

   336      * @throws NullPointerException if this list contains a null element and the

   337      *         specified collection does not permit null elements (optional),

   338      *         or if the specified collection is null

   339      * @see #remove(Object)

   340      * @see #contains(Object)

   341      */

   342     boolean removeAll(Collection<?> c);

   343 

   344     /**

   345      * Retains only the elements in this list that are contained in the

   346      * specified collection (optional operation).  In other words, removes

   347      * from this list all of its elements that are not contained in the

   348      * specified collection.

   349      *

   350      * @param c collection containing elements to be retained in this list

   351      * @return <tt>true</tt> if this list changed as a result of the call

   352      * @throws UnsupportedOperationException if the <tt>retainAll</tt> operation

   353      *         is not supported by this list

   354      * @throws ClassCastException if the class of an element of this list

   355      *         is incompatible with the specified collection (optional)

   356      * @throws NullPointerException if this list contains a null element and the

   357      *         specified collection does not permit null elements (optional),

   358      *         or if the specified collection is null

   359      * @see #remove(Object)

   360      * @see #contains(Object)

   361      */

   362     boolean retainAll(Collection<?> c);

   363 

   364     /**

   365      * Removes all of the elements from this list (optional operation).

   366      * The list will be empty after this call returns.

   367      *

   368      * @throws UnsupportedOperationException if the <tt>clear</tt> operation

   369      *         is not supported by this list

   370      */

   371     void clear();

   372 

   373 

   374     // Comparison and hashing

   375 

   376     /**

   377      * Compares the specified object with this list for equality.  Returns

   378      * <tt>true</tt> if and only if the specified object is also a list, both

   379      * lists have the same size, and all corresponding pairs of elements in

   380      * the two lists are <i>equal</i>.  (Two elements <tt>e1</tt> and

   381      * <tt>e2</tt> are <i>equal</i> if <tt>(e1==null ? e2==null :

   382      * e1.equals(e2))</tt>.)  In other words, two lists are defined to be

   383      * equal if they contain the same elements in the same order.  This

   384      * definition ensures that the equals method works properly across

   385      * different implementations of the <tt>List</tt> interface.

   386      *

   387      * @param o the object to be compared for equality with this list

   388      * @return <tt>true</tt> if the specified object is equal to this list

   389      */

   390     boolean equals(Object o);

   391 

   392     /**

   393      * Returns the hash code value for this list.  The hash code of a list

   394      * is defined to be the result of the following calculation:

   395      * <pre>

   396      *  int hashCode = 1;

   397      *  for (E e : list)

   398      *      hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());

   399      * </pre>

   400      * This ensures that <tt>list1.equals(list2)</tt> implies that

   401      * <tt>list1.hashCode()==list2.hashCode()</tt> for any two lists,

   402      * <tt>list1</tt> and <tt>list2</tt>, as required by the general

   403      * contract of {@link Object#hashCode}.

   404      *

   405      * @return the hash code value for this list

   406      * @see Object#equals(Object)

   407      * @see #equals(Object)

   408      */

   409     int hashCode();

   410 

   411 

   412     // Positional Access Operations

   413 

   414     /**

   415      * Returns the element at the specified position in this list.

   416      *

   417      * @param index index of the element to return

   418      * @return the element at the specified position in this list

   419      * @throws IndexOutOfBoundsException if the index is out of range

   420      *         (<tt>index &lt; 0 || index &gt;= size()</tt>)

   421      */

   422     E get(int index);

   423 

   424     /**

   425      * Replaces the element at the specified position in this list with the

   426      * specified element (optional operation).

   427      *

   428      * @param index index of the element to replace

   429      * @param element element to be stored at the specified position

   430      * @return the element previously at the specified position

   431      * @throws UnsupportedOperationException if the <tt>set</tt> operation

   432      *         is not supported by this list

   433      * @throws ClassCastException if the class of the specified element

   434      *         prevents it from being added to this list

   435      * @throws NullPointerException if the specified element is null and

   436      *         this list does not permit null elements

   437      * @throws IllegalArgumentException if some property of the specified

   438      *         element prevents it from being added to this list

   439      * @throws IndexOutOfBoundsException if the index is out of range

   440      *         (<tt>index &lt; 0 || index &gt;= size()</tt>)

   441      */

   442     E set(int index, E element);

   443 

   444     /**

   445      * Inserts the specified element at the specified position in this list

   446      * (optional operation).  Shifts the element currently at that position

   447      * (if any) and any subsequent elements to the right (adds one to their

   448      * indices).

   449      *

   450      * @param index index at which the specified element is to be inserted

   451      * @param element element to be inserted

   452      * @throws UnsupportedOperationException if the <tt>add</tt> operation

   453      *         is not supported by this list

   454      * @throws ClassCastException if the class of the specified element

   455      *         prevents it from being added to this list

   456      * @throws NullPointerException if the specified element is null and

   457      *         this list does not permit null elements

   458      * @throws IllegalArgumentException if some property of the specified

   459      *         element prevents it from being added to this list

   460      * @throws IndexOutOfBoundsException if the index is out of range

   461      *         (<tt>index &lt; 0 || index &gt; size()</tt>)

   462      */

   463     void add(int index, E element);

   464 

   465     /**

   466      * Removes the element at the specified position in this list (optional

   467      * operation).  Shifts any subsequent elements to the left (subtracts one

   468      * from their indices).  Returns the element that was removed from the

   469      * list.

   470      *

   471      * @param index the index of the element to be removed

   472      * @return the element previously at the specified position

   473      * @throws UnsupportedOperationException if the <tt>remove</tt> operation

   474      *         is not supported by this list

   475      * @throws IndexOutOfBoundsException if the index is out of range

   476      *         (<tt>index &lt; 0 || index &gt;= size()</tt>)

   477      */

   478     E remove(int index);

   479 

   480 

   481     // Search Operations

   482 

   483     /**

   484      * Returns the index of the first occurrence of the specified element

   485      * in this list, or -1 if this list does not contain the element.

   486      * More formally, returns the lowest index <tt>i</tt> such that

   487      * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>,

   488      * or -1 if there is no such index.

   489      *

   490      * @param o element to search for

   491      * @return the index of the first occurrence of the specified element in

   492      *         this list, or -1 if this list does not contain the element

   493      * @throws ClassCastException if the type of the specified element

   494      *         is incompatible with this list (optional)

   495      * @throws NullPointerException if the specified element is null and this

   496      *         list does not permit null elements (optional)

   497      */

   498     int indexOf(Object o);

   499 

   500     /**

   501      * Returns the index of the last occurrence of the specified element

   502      * in this list, or -1 if this list does not contain the element.

   503      * More formally, returns the highest index <tt>i</tt> such that

   504      * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>,

   505      * or -1 if there is no such index.

   506      *

   507      * @param o element to search for

   508      * @return the index of the last occurrence of the specified element in

   509      *         this list, or -1 if this list does not contain the element

   510      * @throws ClassCastException if the type of the specified element

   511      *         is incompatible with this list (optional)

   512      * @throws NullPointerException if the specified element is null and this

   513      *         list does not permit null elements (optional)

   514      */

   515     int lastIndexOf(Object o);

   516 

   517 

   518     // List Iterators

   519 

   520     /**

   521      * Returns a list iterator over the elements in this list (in proper

   522      * sequence).

   523      *

   524      * @return a list iterator over the elements in this list (in proper

   525      *         sequence)

   526      */

   527     ListIterator<E> listIterator();

   528 

   529     /**

   530      * Returns a list iterator over the elements in this list (in proper

   531      * sequence), starting at the specified position in the list.

   532      * The specified index indicates the first element that would be

   533      * returned by an initial call to {@link ListIterator#next next}.

   534      * An initial call to {@link ListIterator#previous previous} would

   535      * return the element with the specified index minus one.

   536      *

   537      * @param index index of the first element to be returned from the

   538      *        list iterator (by a call to {@link ListIterator#next next})

   539      * @return a list iterator over the elements in this list (in proper

   540      *         sequence), starting at the specified position in the list

   541      * @throws IndexOutOfBoundsException if the index is out of range

   542      *         ({@code index < 0 || index > size()})

   543      */

   544     ListIterator<E> listIterator(int index);

   545 

   546     // View

   547 

   548     /**

   549      * Returns a view of the portion of this list between the specified

   550      * <tt>fromIndex</tt>, inclusive, and <tt>toIndex</tt>, exclusive.  (If

   551      * <tt>fromIndex</tt> and <tt>toIndex</tt> are equal, the returned list is

   552      * empty.)  The returned list is backed by this list, so non-structural

   553      * changes in the returned list are reflected in this list, and vice-versa.

   554      * The returned list supports all of the optional list operations supported

   555      * by this list.<p>

   556      *

   557      * This method eliminates the need for explicit range operations (of

   558      * the sort that commonly exist for arrays).  Any operation that expects

   559      * a list can be used as a range operation by passing a subList view

   560      * instead of a whole list.  For example, the following idiom

   561      * removes a range of elements from a list:

   562      * <pre>

   563      *      list.subList(from, to).clear();

   564      * </pre>

   565      * Similar idioms may be constructed for <tt>indexOf</tt> and

   566      * <tt>lastIndexOf</tt>, and all of the algorithms in the

   567      * <tt>Collections</tt> class can be applied to a subList.<p>

   568      *

   569      * The semantics of the list returned by this method become undefined if

   570      * the backing list (i.e., this list) is <i>structurally modified</i> in

   571      * any way other than via the returned list.  (Structural modifications are

   572      * those that change the size of this list, or otherwise perturb it in such

   573      * a fashion that iterations in progress may yield incorrect results.)

   574      *

   575      * @param fromIndex low endpoint (inclusive) of the subList

   576      * @param toIndex high endpoint (exclusive) of the subList

   577      * @return a view of the specified range within this list

   578      * @throws IndexOutOfBoundsException for an illegal endpoint index value

   579      *         (<tt>fromIndex &lt; 0 || toIndex &gt; size ||

   580      *         fromIndex &gt; toIndex</tt>)

   581      */

   582     List<E> subList(int fromIndex, int toIndex);

   583 }