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 *
356 * Retains only the elements in this list that are contained in the
357 * specified collection (optional operation). In other words, removes
358 * from this list all of its elements that are not contained in the
359 * specified collection.
360 *
361 * @param c collection containing elements to be retained in this list
362 * @return <tt>true</tt> if this list changed as a result of the call
363 * @throws UnsupportedOperationException if the <tt>retainAll</tt> operation
364 * is not supported by this list
365 * @throws ClassCastException if the class of an element of this list
366 * is incompatible with the specified collection
367 * (<a href="Collection.html#optional-restrictions">optional</a>)
368 * @throws NullPointerException if this list contains a null element and the
369 * specified collection does not permit null elements
370 * (<a href="Collection.html#optional-restrictions">optional</a>),
371 * or if the specified collection is null
372 * @see #remove(Object)
373 * @see #contains(Object)
374 */
375 boolean retainAll(Collection<?> c);
376
377 /**
378 * Removes all of the elements from this list (optional operation).
379 * The list will be empty after this call returns.
380 *
381 * @throws UnsupportedOperationException if the <tt>clear</tt> operation
382 * is not supported by this list
383 */
384 void clear();
385
386
387 // Comparison and hashing
388
389 /**
390 * Compares the specified object with this list for equality. Returns
391 * <tt>true</tt> if and only if the specified object is also a list, both
392 * lists have the same size, and all corresponding pairs of elements in
393 * the two lists are <i>equal</i>. (Two elements <tt>e1</tt> and
394 * <tt>e2</tt> are <i>equal</i> if <tt>(e1==null ? e2==null :
395 * e1.equals(e2))</tt>.) In other words, two lists are defined to be
|
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 *
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. Exceptions thrown by the operator are relayed
382 * to the caller.
383 *
384 * @implSpec
385 * The default implementation is equivalent to, for this {@code list}:
386 * <pre>
387 * final ListIterator<E> li = list.listIterator();
388 * while (li.hasNext()) {
389 * li.set(operator.apply(li.next()));
390 * }
391 * </pre>
392 * If the list's list-iterator does not support the {@code set} operation
393 * then an {@code UnsupportedOperationException} will be thrown when
394 * replacing the first element.
395 *
396 * @param operator the operator to apply to each element
397 * @throws UnsupportedOperationException if the <code>replaceAll</code>
398 * operation is not supported by this list
399 * @throws NullPointerException if the specified operator is null
400 * @throws NullPointerException if the an element is replaced with a null
401 * value and this list does not permit null elements
402 * (<a href="Collection.html#optional-restrictions">optional</a>)
403 * @since 1.8
404 */
405 default void replaceAll(UnaryOperator<E> operator) {
406 Objects.requireNonNull(operator);
407 final ListIterator<E> li = this.listIterator();
408 while (li.hasNext()) {
409 li.set(operator.apply(li.next()));
410 }
411 }
412
413 /**
414 * Sorts this list using the supplied {@code Comparator} to compare elements.
415 *
416 * @implSpec
417 * The default implementation is equivalent to, for this {@code list}:
418 * <pre>Collections.sort(list, c)</pre>
419 *
420 * @param c the {@code Comparator} used to compare list elements.
421 * A {@code null} value indicates that the elements'
422 * {@linkplain Comparable natural ordering} should be used.
423 * @since 1.8
424 * @throws ClassCastException if the list contains elements that are not
425 * <i>mutually comparable</i> using the specified comparator.
426 * @throws UnsupportedOperationException if the list's list-iterator does
427 * not support the {@code set} operation.
428 * @throws IllegalArgumentException (optional) if the comparator is
429 * found to violate the {@link Comparator} contract
430 */
431 default void sort(Comparator<? super E> c) {
432 Collections.sort(this, c);
433 }
434
435 /**
436 * Removes all of the elements from this list (optional operation).
437 * The list will be empty after this call returns.
438 *
439 * @throws UnsupportedOperationException if the <tt>clear</tt> operation
440 * is not supported by this list
441 */
442 void clear();
443
444
445 // Comparison and hashing
446
447 /**
448 * Compares the specified object with this list for equality. Returns
449 * <tt>true</tt> if and only if the specified object is also a list, both
450 * lists have the same size, and all corresponding pairs of elements in
451 * the two lists are <i>equal</i>. (Two elements <tt>e1</tt> and
452 * <tt>e2</tt> are <i>equal</i> if <tt>(e1==null ? e2==null :
453 * e1.equals(e2))</tt>.) In other words, two lists are defined to be
|