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 * The root interface in the <i>collection hierarchy</i>. A collection
30 * represents a group of objects, known as its <i>elements</i>. Some
31 * collections allow duplicate elements and others do not. Some are ordered
32 * and others unordered. The JDK does not provide any <i>direct</i>
33 * implementations of this interface: it provides implementations of more
34 * specific subinterfaces like <tt>Set</tt> and <tt>List</tt>. This interface
35 * is typically used to pass collections around and manipulate them where
36 * maximum generality is desired.
37 *
38 * <p><i>Bags</i> or <i>multisets</i> (unordered collections that may contain
39 * duplicate elements) should implement this interface directly.
40 *
41 * <p>All general-purpose <tt>Collection</tt> implementation classes (which
42 * typically implement <tt>Collection</tt> indirectly through one of its
43 * subinterfaces) should provide two "standard" constructors: a void (no
44 * arguments) constructor, which creates an empty collection, and a
45 * constructor with a single argument of type <tt>Collection</tt>, which
46 * creates a new collection with the same elements as its argument. In
47 * effect, the latter constructor allows the user to copy any collection,
354 * collection.
355 *
356 * @param c collection containing elements to be removed from this collection
357 * @return <tt>true</tt> if this collection changed as a result of the
358 * call
359 * @throws UnsupportedOperationException if the <tt>removeAll</tt> method
360 * is not supported by this collection
361 * @throws ClassCastException if the types of one or more elements
362 * in this collection are incompatible with the specified
363 * collection
364 * (<a href="#optional-restrictions">optional</a>)
365 * @throws NullPointerException if this collection contains one or more
366 * null elements and the specified collection does not support
367 * null elements
368 * (<a href="#optional-restrictions">optional</a>),
369 * or if the specified collection is null
370 * @see #remove(Object)
371 * @see #contains(Object)
372 */
373 boolean removeAll(Collection<?> c);
374
375 /**
376 * Retains only the elements in this collection that are contained in the
377 * specified collection (optional operation). In other words, removes from
378 * this collection all of its elements that are not contained in the
379 * specified collection.
380 *
381 * @param c collection containing elements to be retained in this collection
382 * @return <tt>true</tt> if this collection changed as a result of the call
383 * @throws UnsupportedOperationException if the <tt>retainAll</tt> operation
384 * is not supported by this collection
385 * @throws ClassCastException if the types of one or more elements
386 * in this collection are incompatible with the specified
387 * collection
388 * (<a href="#optional-restrictions">optional</a>)
389 * @throws NullPointerException if this collection contains one or more
390 * null elements and the specified collection does not permit null
391 * elements
392 * (<a href="#optional-restrictions">optional</a>),
393 * or if the specified collection is null
|
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.Predicate;
29
30 /**
31 * The root interface in the <i>collection hierarchy</i>. A collection
32 * represents a group of objects, known as its <i>elements</i>. Some
33 * collections allow duplicate elements and others do not. Some are ordered
34 * and others unordered. The JDK does not provide any <i>direct</i>
35 * implementations of this interface: it provides implementations of more
36 * specific subinterfaces like <tt>Set</tt> and <tt>List</tt>. This interface
37 * is typically used to pass collections around and manipulate them where
38 * maximum generality is desired.
39 *
40 * <p><i>Bags</i> or <i>multisets</i> (unordered collections that may contain
41 * duplicate elements) should implement this interface directly.
42 *
43 * <p>All general-purpose <tt>Collection</tt> implementation classes (which
44 * typically implement <tt>Collection</tt> indirectly through one of its
45 * subinterfaces) should provide two "standard" constructors: a void (no
46 * arguments) constructor, which creates an empty collection, and a
47 * constructor with a single argument of type <tt>Collection</tt>, which
48 * creates a new collection with the same elements as its argument. In
49 * effect, the latter constructor allows the user to copy any collection,
356 * collection.
357 *
358 * @param c collection containing elements to be removed from this collection
359 * @return <tt>true</tt> if this collection changed as a result of the
360 * call
361 * @throws UnsupportedOperationException if the <tt>removeAll</tt> method
362 * is not supported by this collection
363 * @throws ClassCastException if the types of one or more elements
364 * in this collection are incompatible with the specified
365 * collection
366 * (<a href="#optional-restrictions">optional</a>)
367 * @throws NullPointerException if this collection contains one or more
368 * null elements and the specified collection does not support
369 * null elements
370 * (<a href="#optional-restrictions">optional</a>),
371 * or if the specified collection is null
372 * @see #remove(Object)
373 * @see #contains(Object)
374 */
375 boolean removeAll(Collection<?> c);
376
377 /**
378 * Removes all of the elements of this collection that satisfy the given
379 * predicate. RuntimeExceptions and Errors thrown by the predicate are
380 * propagated to the caller.
381 *
382 * @implSpec
383 * The default implementation traverses all elements of the collection using
384 * its {@link #iterator}. Each matching element is removed using
385 * {@link Iterator#remove()}. If the collection's iterator does not
386 * support removal then an {@code UnsupportedOperationException} will be
387 * thrown on the first matching element.
388 *
389 * @param filter a predicate which returns {@code true} for elements to be
390 * removed
391 * @return {@code true} if any elements were removed
392 * @throws NullPointerException if the specified filter is null
393 * @throws UnsupportedOperationException if the {@code remove}
394 * method is not supported by this collection's
395 * {@link #iterator}
396 * @since 1.8
397 */
398 default boolean removeIf(Predicate<? super E> filter) {
399 Objects.requireNonNull(filter);
400 boolean removed = false;
401 final Iterator<E> each = iterator();
402 while (each.hasNext()) {
403 if (filter.test(each.next())) {
404 each.remove();
405 removed = true;
406 }
407 }
408 return removed;
409 }
410
411 /**
412 * Retains only the elements in this collection that are contained in the
413 * specified collection (optional operation). In other words, removes from
414 * this collection all of its elements that are not contained in the
415 * specified collection.
416 *
417 * @param c collection containing elements to be retained in this collection
418 * @return <tt>true</tt> if this collection changed as a result of the call
419 * @throws UnsupportedOperationException if the <tt>retainAll</tt> operation
420 * is not supported by this collection
421 * @throws ClassCastException if the types of one or more elements
422 * in this collection are incompatible with the specified
423 * collection
424 * (<a href="#optional-restrictions">optional</a>)
425 * @throws NullPointerException if this collection contains one or more
426 * null elements and the specified collection does not permit null
427 * elements
428 * (<a href="#optional-restrictions">optional</a>),
429 * or if the specified collection is null
|