com.google.common.collect
Class Collections2

java.lang.Object
  extended by com.google.common.collect.Collections2

public final class Collections2
extends Object

Provides static methods for working with Collection instances.

Author:
Chris Povirk, Mike Bostock, Jared Levy

Method Summary
static
<T> Collection<T>
filter(Collection<T> unfiltered, Predicate<? super T> predicate)
          Returns the elements of unfiltered that satisfy a predicate.
static
<T> Collection<T>
forIterable(Iterable<T> iterable)
          Returns a limited Collection view of the given Iterable, or the Iterable itself if it is already a Collection (in which case the rest of this documentation does not apply).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

forIterable

public static <T> Collection<T> forIterable(Iterable<T> iterable)
Returns a limited Collection view of the given Iterable, or the Iterable itself if it is already a Collection (in which case the rest of this documentation does not apply). The returned collection is not appropriate for general use for a number of reasons. Instead, it exists to provide frequently desired methods for dealing with Iterable objects -- such as Collection.removeAll(Collection) -- through the familiar Collection interface. To treat the contents of an Iterable as a full-fledged, performant Collection, it is recommended that clients call a method like ImmutableSet.copyOf(Iterable) or Iterables.addAll(Collection, Iterable) to dump the contents of the Iterable into a standard Collection. For cases in which a view of the Iterable is required, forIterable() is available.

A number of limitations result from building on the Iterable interface. Notably, size(), contains(), and many other methods of the returned collection are O(n). The returned collection does not support the insertion of items. Removal of elements is supported if the underlying Iterable supports it, and all non-mutative operations are supported. Additionally, each method call on the returned collection calls Iterable.iterator() on the source Iterable. Thus, if you wish to call more than one method on the collection or to otherwise access the contents of the Iterable after calling a method, the Iterable must support the creation of multiple iterators.

Object.equals(Object) and Object.hashCode() are inherited from Object, as the returned Collection is not an implementation of any additional interface, such as List or Set.

The behavior of the returned collection's iterator in the face of concurrent structural modification of the returned collection or of the underlying Iterable is undefined, and no guarantee is made that the objects are fail-fast.

Usage Example

 // Remove all instances of "foo" from an Iterable:
 Collections2.forIterable(iterable).removeAll(ImmutableSet.of("foo"));
 


filter

public static <T> Collection<T> filter(Collection<T> unfiltered,
                                       Predicate<? super T> predicate)
Returns the elements of unfiltered that satisfy a predicate. The returned collection is a live view of unfiltered; changes to one affect the other.

The resulting collection's iterator does not support remove(), but all other collection methods are supported. The collection's add() and addAll() methods throw an IllegalArgumentException if an element that doesn't satisfy the predicate is provided. When methods such as removeAll() and clear() are called on the filtered collection, only elements that satisfy the filter will be removed from the underlying collection.

The returned collection isn't threadsafe or serializable, even if unfiltered is.

Many of the filtered collection's methods, such as size(), iterate across every element in the underlying collection and determine which elements satisfy the filter. When a live view is not needed, it may be faster to copy the filtered collection and use the copy.

The clear(), removeAll(), and retainAll() methods all call Iterator.remove() on the underlying collection's iterator. Consequently, methods like the following throw an UnsupportedOperationException.

  Collections2.filter(Collections2.filter(collection, predicate1),
     predicate2)).clear();
Instead, call Predicates.and(Predicate, Predicate) to combine the predicates and pass the combined predicate to this method.