1 /*
2 * Copyright (c) 1997, 2018, 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
84 * a method that might perform invocations, and using an existing
85 * iterator to examine the collection.
86 *
87 * <p>Many methods in Collections Framework interfaces are defined in
88 * terms of the {@link Object#equals(Object) equals} method. For example,
89 * the specification for the {@link #contains(Object) contains(Object o)}
90 * method says: "returns {@code true} if and only if this collection
91 * contains at least one element {@code e} such that
92 * {@code (o==null ? e==null : o.equals(e))}." This specification should
93 * <i>not</i> be construed to imply that invoking {@code Collection.contains}
94 * with a non-null argument {@code o} will cause {@code o.equals(e)} to be
95 * invoked for any element {@code e}. Implementations are free to implement
96 * optimizations whereby the {@code equals} invocation is avoided, for
97 * example, by first comparing the hash codes of the two elements. (The
98 * {@link Object#hashCode()} specification guarantees that two objects with
99 * unequal hash codes cannot be equal.) More generally, implementations of
100 * the various Collections Framework interfaces are free to take advantage of
101 * the specified behavior of underlying {@link Object} methods wherever the
102 * implementor deems it appropriate.
103 *
104 * <p>Some collection operations which perform recursive traversal of the
105 * collection may fail with an exception for self-referential instances where
106 * the collection directly or indirectly contains itself. This includes the
107 * {@code clone()}, {@code equals()}, {@code hashCode()} and {@code toString()}
108 * methods. Implementations may optionally handle the self-referential scenario,
109 * however most current implementations do not do so.
110 *
111 * <h2><a id="view">View Collections</a></h2>
112 *
113 * <p>Most collections manage storage for elements they contain. By contrast, <i>view
114 * collections</i> themselves do not store elements, but instead they rely on a
115 * backing collection to store the actual elements. Operations that are not handled
116 * by the view collection itself are delegated to the backing collection. Examples of
117 * view collections include the wrapper collections returned by methods such as
118 * {@link Collections#checkedCollection Collections.checkedCollection},
119 * {@link Collections#synchronizedCollection Collections.synchronizedCollection}, and
120 * {@link Collections#unmodifiableCollection Collections.unmodifiableCollection}.
121 * Other examples of view collections include collections that provide a
122 * different representation of the same elements, for example, as
123 * provided by {@link List#subList List.subList},
428 * equivalently, if this collection changed as a result of the call).
429 *
430 * @param o element to be removed from this collection, if present
431 * @return {@code true} if an element was removed as a result of this call
432 * @throws ClassCastException if the type of the specified element
433 * is incompatible with this collection
434 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
435 * @throws NullPointerException if the specified element is null and this
436 * collection does not permit null elements
437 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
438 * @throws UnsupportedOperationException if the {@code remove} operation
439 * is not supported by this collection
440 */
441 boolean remove(Object o);
442
443
444 // Bulk Operations
445
446 /**
447 * Returns {@code true} if this collection contains all of the elements
448 * in the specified collection.
449 *
450 * @param c collection to be checked for containment in this collection
451 * @return {@code true} if this collection contains all of the elements
452 * in the specified collection
453 * @throws ClassCastException if the types of one or more elements
454 * in the specified collection are incompatible with this
455 * collection
456 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
457 * @throws NullPointerException if the specified collection contains one
458 * or more null elements and this collection does not permit null
459 * elements
460 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>),
461 * or if the specified collection is null.
462 * @see #contains(Object)
463 */
464 boolean containsAll(Collection<?> c);
465
466 /**
467 * Adds all of the elements in the specified collection to this collection
468 * (optional operation). The behavior of this operation is undefined if
476 * @throws UnsupportedOperationException if the {@code addAll} operation
477 * is not supported by this collection
478 * @throws ClassCastException if the class of an element of the specified
479 * collection prevents it from being added to this collection
480 * @throws NullPointerException if the specified collection contains a
481 * null element and this collection does not permit null elements,
482 * or if the specified collection is null
483 * @throws IllegalArgumentException if some property of an element of the
484 * specified collection prevents it from being added to this
485 * collection
486 * @throws IllegalStateException if not all the elements can be added at
487 * this time due to insertion restrictions
488 * @see #add(Object)
489 */
490 boolean addAll(Collection<? extends E> c);
491
492 /**
493 * Removes all of this collection's elements that are also contained in the
494 * specified collection (optional operation). After this call returns,
495 * this collection will contain no elements in common with the specified
496 * collection.
497 *
498 * @param c collection containing elements to be removed from this collection
499 * @return {@code true} if this collection changed as a result of the
500 * call
501 * @throws UnsupportedOperationException if the {@code removeAll} method
502 * is not supported by this collection
503 * @throws ClassCastException if the types of one or more elements
504 * in this collection are incompatible with the specified
505 * collection
506 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
507 * @throws NullPointerException if this collection contains one or more
508 * null elements and the specified collection does not support
509 * null elements
510 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>),
511 * or if the specified collection is null
512 * @see #remove(Object)
513 * @see #contains(Object)
514 */
515 boolean removeAll(Collection<?> c);
516
517 /**
536 * supported.
537 * @since 1.8
538 */
539 default boolean removeIf(Predicate<? super E> filter) {
540 Objects.requireNonNull(filter);
541 boolean removed = false;
542 final Iterator<E> each = iterator();
543 while (each.hasNext()) {
544 if (filter.test(each.next())) {
545 each.remove();
546 removed = true;
547 }
548 }
549 return removed;
550 }
551
552 /**
553 * Retains only the elements in this collection that are contained in the
554 * specified collection (optional operation). In other words, removes from
555 * this collection all of its elements that are not contained in the
556 * specified collection.
557 *
558 * @param c collection containing elements to be retained in this collection
559 * @return {@code true} if this collection changed as a result of the call
560 * @throws UnsupportedOperationException if the {@code retainAll} operation
561 * is not supported by this collection
562 * @throws ClassCastException if the types of one or more elements
563 * in this collection are incompatible with the specified
564 * collection
565 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
566 * @throws NullPointerException if this collection contains one or more
567 * null elements and the specified collection does not permit null
568 * elements
569 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>),
570 * or if the specified collection is null
571 * @see #remove(Object)
572 * @see #contains(Object)
573 */
574 boolean retainAll(Collection<?> c);
575
576 /**
577 * Removes all of the elements from this collection (optional operation).
|
1 /*
2 * Copyright (c) 1997, 2019, 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
84 * a method that might perform invocations, and using an existing
85 * iterator to examine the collection.
86 *
87 * <p>Many methods in Collections Framework interfaces are defined in
88 * terms of the {@link Object#equals(Object) equals} method. For example,
89 * the specification for the {@link #contains(Object) contains(Object o)}
90 * method says: "returns {@code true} if and only if this collection
91 * contains at least one element {@code e} such that
92 * {@code (o==null ? e==null : o.equals(e))}." This specification should
93 * <i>not</i> be construed to imply that invoking {@code Collection.contains}
94 * with a non-null argument {@code o} will cause {@code o.equals(e)} to be
95 * invoked for any element {@code e}. Implementations are free to implement
96 * optimizations whereby the {@code equals} invocation is avoided, for
97 * example, by first comparing the hash codes of the two elements. (The
98 * {@link Object#hashCode()} specification guarantees that two objects with
99 * unequal hash codes cannot be equal.) More generally, implementations of
100 * the various Collections Framework interfaces are free to take advantage of
101 * the specified behavior of underlying {@link Object} methods wherever the
102 * implementor deems it appropriate.
103 *
104 * <p>Some collection interfaces and implementations may specify membership
105 * semantics that are not defined in terms of the {@code equals} method. For
106 * example, the {@link SortedSet#contains(Object) SortedSet.contains} method
107 * is defined in terms of a comparison method provided at construction time
108 * instead of the {@code equals} method. Such collections are well-defined,
109 * although their behavior may be counterintuitive when mixed with collections
110 * that use different membership semantics. For operations that may involve the
111 * membership semantics of more than one collection, it is specified which
112 * collection's membership semantics the operation uses.
113 *
114 * <p>Some collection operations which perform recursive traversal of the
115 * collection may fail with an exception for self-referential instances where
116 * the collection directly or indirectly contains itself. This includes the
117 * {@code clone()}, {@code equals()}, {@code hashCode()} and {@code toString()}
118 * methods. Implementations may optionally handle the self-referential scenario,
119 * however most current implementations do not do so.
120 *
121 * <h2><a id="view">View Collections</a></h2>
122 *
123 * <p>Most collections manage storage for elements they contain. By contrast, <i>view
124 * collections</i> themselves do not store elements, but instead they rely on a
125 * backing collection to store the actual elements. Operations that are not handled
126 * by the view collection itself are delegated to the backing collection. Examples of
127 * view collections include the wrapper collections returned by methods such as
128 * {@link Collections#checkedCollection Collections.checkedCollection},
129 * {@link Collections#synchronizedCollection Collections.synchronizedCollection}, and
130 * {@link Collections#unmodifiableCollection Collections.unmodifiableCollection}.
131 * Other examples of view collections include collections that provide a
132 * different representation of the same elements, for example, as
133 * provided by {@link List#subList List.subList},
438 * equivalently, if this collection changed as a result of the call).
439 *
440 * @param o element to be removed from this collection, if present
441 * @return {@code true} if an element was removed as a result of this call
442 * @throws ClassCastException if the type of the specified element
443 * is incompatible with this collection
444 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
445 * @throws NullPointerException if the specified element is null and this
446 * collection does not permit null elements
447 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
448 * @throws UnsupportedOperationException if the {@code remove} operation
449 * is not supported by this collection
450 */
451 boolean remove(Object o);
452
453
454 // Bulk Operations
455
456 /**
457 * Returns {@code true} if this collection contains all of the elements
458 * in the specified collection. This operation uses the membership semantics
459 * of this collection.
460 *
461 * @implNote
462 * Most implementations will call this collection's {@code contains}
463 * method repeatedly. This may result in performance problems if the
464 * {@code contains} method has linear or worse performance.
465 *
466 * @param c collection to be checked for containment in this collection
467 * @return {@code true} if this collection contains all of the elements
468 * in the specified collection
469 * @throws ClassCastException if the types of one or more elements
470 * in the specified collection are incompatible with this
471 * collection
472 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
473 * @throws NullPointerException if the specified collection contains one
474 * or more null elements and this collection does not permit null
475 * elements
476 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>),
477 * or if the specified collection is null.
478 * @see #contains(Object)
479 */
480 boolean containsAll(Collection<?> c);
481
482 /**
483 * Adds all of the elements in the specified collection to this collection
484 * (optional operation). The behavior of this operation is undefined if
492 * @throws UnsupportedOperationException if the {@code addAll} operation
493 * is not supported by this collection
494 * @throws ClassCastException if the class of an element of the specified
495 * collection prevents it from being added to this collection
496 * @throws NullPointerException if the specified collection contains a
497 * null element and this collection does not permit null elements,
498 * or if the specified collection is null
499 * @throws IllegalArgumentException if some property of an element of the
500 * specified collection prevents it from being added to this
501 * collection
502 * @throws IllegalStateException if not all the elements can be added at
503 * this time due to insertion restrictions
504 * @see #add(Object)
505 */
506 boolean addAll(Collection<? extends E> c);
507
508 /**
509 * Removes all of this collection's elements that are also contained in the
510 * specified collection (optional operation). After this call returns,
511 * this collection will contain no elements in common with the specified
512 * collection. This operation uses the membership semantics of the specified
513 * collection.
514 *
515 * @implNote
516 * Most implementations will call the specified collection's {@code contains}
517 * method repeatedly. This may result in performance problems if the specified
518 * collection's {@code contains} operation has linear or worse performance.
519 *
520 * @param c collection containing elements to be removed from this collection
521 * @return {@code true} if this collection changed as a result of the
522 * call
523 * @throws UnsupportedOperationException if the {@code removeAll} method
524 * is not supported by this collection
525 * @throws ClassCastException if the types of one or more elements
526 * in this collection are incompatible with the specified
527 * collection
528 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
529 * @throws NullPointerException if this collection contains one or more
530 * null elements and the specified collection does not support
531 * null elements
532 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>),
533 * or if the specified collection is null
534 * @see #remove(Object)
535 * @see #contains(Object)
536 */
537 boolean removeAll(Collection<?> c);
538
539 /**
558 * supported.
559 * @since 1.8
560 */
561 default boolean removeIf(Predicate<? super E> filter) {
562 Objects.requireNonNull(filter);
563 boolean removed = false;
564 final Iterator<E> each = iterator();
565 while (each.hasNext()) {
566 if (filter.test(each.next())) {
567 each.remove();
568 removed = true;
569 }
570 }
571 return removed;
572 }
573
574 /**
575 * Retains only the elements in this collection that are contained in the
576 * specified collection (optional operation). In other words, removes from
577 * this collection all of its elements that are not contained in the
578 * specified collection. This operation uses the membership semantics of the
579 * specified collection.
580 *
581 * @implNote
582 * Most implementations will call the specified collection's {@code contains}
583 * method repeatedly. This may result in performance problems if the specified
584 * collection's {@code contains} operation has linear or worse performance.
585 *
586 * @param c collection containing elements to be retained in this collection
587 * @return {@code true} if this collection changed as a result of the call
588 * @throws UnsupportedOperationException if the {@code retainAll} operation
589 * is not supported by this collection
590 * @throws ClassCastException if the types of one or more elements
591 * in this collection are incompatible with the specified
592 * collection
593 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
594 * @throws NullPointerException if this collection contains one or more
595 * null elements and the specified collection does not permit null
596 * elements
597 * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>),
598 * or if the specified collection is null
599 * @see #remove(Object)
600 * @see #contains(Object)
601 */
602 boolean retainAll(Collection<?> c);
603
604 /**
605 * Removes all of the elements from this collection (optional operation).
|