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 < 0 || toIndex > size ||
597 * fromIndex > 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 < 0 || toIndex > size ||
599 * fromIndex > 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 }
|