src/share/classes/java/util/List.java

Print this page
rev 6197 : [mq]: collections


   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 /**
  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  *


 580      *      list.subList(from, to).clear();
 581      * </pre>
 582      * Similar idioms may be constructed for <tt>indexOf</tt> and
 583      * <tt>lastIndexOf</tt>, and all of the algorithms in the
 584      * <tt>Collections</tt> class can be applied to a subList.<p>
 585      *
 586      * The semantics of the list returned by this method become undefined if
 587      * the backing list (i.e., this list) is <i>structurally modified</i> in
 588      * any way other than via the returned list.  (Structural modifications are
 589      * those that change the size of this list, or otherwise perturb it in such
 590      * a fashion that iterations in progress may yield incorrect results.)
 591      *
 592      * @param fromIndex low endpoint (inclusive) of the subList
 593      * @param toIndex high endpoint (exclusive) of the subList
 594      * @return a view of the specified range within this list
 595      * @throws IndexOutOfBoundsException for an illegal endpoint index value
 596      *         (<tt>fromIndex &lt; 0 || toIndex &gt; size ||
 597      *         fromIndex &gt; toIndex</tt>)
 598      */
 599     List<E> subList(int fromIndex, int toIndex);





























 600 }


   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  *


 582      *      list.subList(from, to).clear();
 583      * </pre>
 584      * Similar idioms may be constructed for <tt>indexOf</tt> and
 585      * <tt>lastIndexOf</tt>, and all of the algorithms in the
 586      * <tt>Collections</tt> class can be applied to a subList.<p>
 587      *
 588      * The semantics of the list returned by this method become undefined if
 589      * the backing list (i.e., this list) is <i>structurally modified</i> in
 590      * any way other than via the returned list.  (Structural modifications are
 591      * those that change the size of this list, or otherwise perturb it in such
 592      * a fashion that iterations in progress may yield incorrect results.)
 593      *
 594      * @param fromIndex low endpoint (inclusive) of the subList
 595      * @param toIndex high endpoint (exclusive) of the subList
 596      * @return a view of the specified range within this list
 597      * @throws IndexOutOfBoundsException for an illegal endpoint index value
 598      *         (<tt>fromIndex &lt; 0 || toIndex &gt; size ||
 599      *         fromIndex &gt; toIndex</tt>)
 600      */
 601     List<E> subList(int fromIndex, int toIndex);
 602 
 603     /**
 604      * Apply the specified operator to each element of this list, replacing
 605      * the element with the result of applying the operator to the current
 606      * element.
 607      *
 608      * @param operator the operator to apply to each element
 609      * @throws NullPointerException if the specified operator is null
 610      * @since 1.8
 611      */
 612     public default void replaceAll(UnaryOperator<E> operator) {
 613         Objects.requireNonNull(operator);
 614         final ListIterator<E> li = this.listIterator();
 615         while (li.hasNext()) {
 616             li.set(operator.operate(li.next()));
 617         }
 618     }
 619 
 620     /**
 621      * Sort this list using the supplied {@code Comparator} to compare elements.
 622      *
 623      * @param c the {@code Comparator} used to compare list elements
 624      * @throws NullPointerException if the specified comparator is null
 625      * @since 1.8
 626      */
 627     public default void sort(Comparator<? super E> c) {
 628         Objects.requireNonNull(c);
 629         Collections.<E>sort(this, c);
 630     }
 631 }