rev 7727 : 8020539: Clean up doclint problems in java.util package, part 2
Summary: Clean up doclint errors and warnings in classes in java.util
Reviewed-by: darcy,chegar
Contributed-by: Brian Burkhalter <brian.burkhalter@oracle.com>

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