Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.google.common.collect
Class Sets

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

public final class Sets
extends Object

Static utility methods pertaining to Set instances. Also see this class's counterparts Lists and Maps.

Since:
2010.01.04 stable (imported from Google Collections Library)
Author:
Kevin Bourrillion, Jared Levy

Nested Class Summary
static class Sets.SetView<E>
          An unmodifiable view of a set which may be backed by other sets; this view will change as the backing sets do.
 
Method Summary
static
<B> Set<List<B>>
cartesianProduct(List<? extends Set<? extends B>> sets)
          Returns every possible list that can be formed by choosing one element from each of the given sets in order; the "n-ary Cartesian product" of the sets.
static
<B> Set<List<B>>
cartesianProduct(Set<? extends B>... sets)
          Returns every possible list that can be formed by choosing one element from each of the given sets in order; the "n-ary Cartesian product" of the sets.
static
<E extends Enum<E>>
EnumSet<E>
complementOf(Collection<E> collection)
          Creates an EnumSet consisting of all enum values that are not in the specified collection.
static
<E extends Enum<E>>
EnumSet<E>
complementOf(Collection<E> collection, Class<E> type)
          Creates an EnumSet consisting of all enum values that are not in the specified collection.
static
<E> Sets.SetView<E>
difference(Set<E> set1, Set<?> set2)
          Returns an unmodifiable view of the difference of two sets.
static
<E> Set<E>
filter(Set<E> unfiltered, Predicate<? super E> predicate)
          Returns the elements of unfiltered that satisfy a predicate.
static
<E extends Enum<E>>
ImmutableSet<E>
immutableEnumSet(E anElement, E... otherElements)
          Returns an immutable set instance containing the given enum elements.
static
<E extends Enum<E>>
ImmutableSet<E>
immutableEnumSet(Iterable<E> elements)
          Returns an immutable set instance containing the given enum elements.
static
<E> Sets.SetView<E>
intersection(Set<E> set1, Set<?> set2)
          Returns an unmodifiable view of the intersection of two sets.
static
<E extends Enum<E>>
EnumSet<E>
newEnumSet(Iterable<E> iterable, Class<E> elementType)
          Returns a new EnumSet instance containing the given elements.
static
<E> HashSet<E>
newHashSet()
          Creates a mutable, empty HashSet instance.
static
<E> HashSet<E>
newHashSet(E... elements)
          Creates a mutable HashSet instance containing the given elements in unspecified order.
static
<E> HashSet<E>
newHashSet(Iterable<? extends E> elements)
          Creates a mutable HashSet instance containing the given elements in unspecified order.
static
<E> HashSet<E>
newHashSet(Iterator<? extends E> elements)
          Creates a mutable HashSet instance containing the given elements in unspecified order.
static
<E> HashSet<E>
newHashSetWithExpectedSize(int expectedSize)
          Creates an empty HashSet instance with enough capacity to hold the specified number of elements without rehashing.
static
<E> LinkedHashSet<E>
newLinkedHashSet()
          Creates a mutable, empty LinkedHashSet instance.
static
<E> LinkedHashSet<E>
newLinkedHashSet(Iterable<? extends E> elements)
          Creates a mutable LinkedHashSet instance containing the given elements in order.
static
<E> Set<E>
newSetFromMap(Map<E,Boolean> map)
          Returns a set backed by the specified map.
static
<E extends Comparable>
TreeSet<E>
newTreeSet()
          Creates a mutable, empty TreeSet instance sorted by the natural sort ordering of its elements.
static
<E> TreeSet<E>
newTreeSet(Comparator<? super E> comparator)
          Creates a mutable, empty TreeSet instance with the given comparator.
static
<E extends Comparable>
TreeSet<E>
newTreeSet(Iterable<? extends E> elements)
          Creates a mutable TreeSet instance containing the given elements sorted by their natural ordering.
static
<E> Sets.SetView<E>
union(Set<? extends E> set1, Set<? extends E> set2)
          Returns an unmodifiable view of the union of two sets.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

immutableEnumSet

public static <E extends Enum<E>> ImmutableSet<E> immutableEnumSet(E anElement,
                                                                   E... otherElements)
Returns an immutable set instance containing the given enum elements. Internally, the returned set will be backed by an EnumSet.

The iteration order of the returned set follows the enum's iteration order, not the order in which the elements are provided to the method.

Parameters:
anElement - one of the elements the set should contain
otherElements - the rest of the elements the set should contain
Returns:
an immutable set containing those elements, minus duplicates

immutableEnumSet

public static <E extends Enum<E>> ImmutableSet<E> immutableEnumSet(Iterable<E> elements)
Returns an immutable set instance containing the given enum elements. Internally, the returned set will be backed by an EnumSet.

The iteration order of the returned set follows the enum's iteration order, not the order in which the elements appear in the given collection.

Parameters:
elements - the elements, all of the same enum type, that the set should contain
Returns:
an immutable set containing those elements, minus duplicates

newEnumSet

public static <E extends Enum<E>> EnumSet<E> newEnumSet(Iterable<E> iterable,
                                                        Class<E> elementType)
Returns a new EnumSet instance containing the given elements. Unlike EnumSet.copyOf(Collection), this method does not produce an exception on an empty collection, and it may be called on any iterable, not just a Collection.

newHashSet

public static <E> HashSet<E> newHashSet()
Creates a mutable, empty HashSet instance.

Note: if mutability is not required, use ImmutableSet.of() instead.

Note: if E is an Enum type, use EnumSet.noneOf(java.lang.Class) instead.

Returns:
a new, empty HashSet

newHashSet

public static <E> HashSet<E> newHashSet(E... elements)
Creates a mutable HashSet instance containing the given elements in unspecified order.

Note: if mutability is not required and the elements are non-null, use ImmutableSet.of(Object[]) instead.

Note: if E is an Enum type, use EnumSet.of(Enum, Enum[]) instead.

Parameters:
elements - the elements that the set should contain
Returns:
a new HashSet containing those elements (minus duplicates)

newHashSetWithExpectedSize

public static <E> HashSet<E> newHashSetWithExpectedSize(int expectedSize)
Creates an empty HashSet instance with enough capacity to hold the specified number of elements without rehashing.

Parameters:
expectedSize - the expected size
Returns:
a new, empty HashSet with enough capacity to hold expectedSize elements without rehashing
Throws:
IllegalArgumentException - if expectedSize is negative

newHashSet

public static <E> HashSet<E> newHashSet(Iterable<? extends E> elements)
Creates a mutable HashSet instance containing the given elements in unspecified order.

Note: if mutability is not required and the elements are non-null, use ImmutableSet.copyOf(Iterable) instead.

Note: if E is an Enum type, use newEnumSet(Iterable, Class) instead.

Parameters:
elements - the elements that the set should contain
Returns:
a new HashSet containing those elements (minus duplicates)

newHashSet

public static <E> HashSet<E> newHashSet(Iterator<? extends E> elements)
Creates a mutable HashSet instance containing the given elements in unspecified order.

Note: if mutability is not required and the elements are non-null, use ImmutableSet.copyOf(Iterable) instead.

Note: if E is an Enum type, you should create an EnumSet instead.

Parameters:
elements - the elements that the set should contain
Returns:
a new HashSet containing those elements (minus duplicates)

newLinkedHashSet

public static <E> LinkedHashSet<E> newLinkedHashSet()
Creates a mutable, empty LinkedHashSet instance.

Note: if mutability is not required, use ImmutableSet.of() instead.

Returns:
a new, empty LinkedHashSet

newLinkedHashSet

public static <E> LinkedHashSet<E> newLinkedHashSet(Iterable<? extends E> elements)
Creates a mutable LinkedHashSet instance containing the given elements in order.

Note: if mutability is not required and the elements are non-null, use ImmutableSet.copyOf(Iterable) instead.

Parameters:
elements - the elements that the set should contain, in order
Returns:
a new LinkedHashSet containing those elements (minus duplicates)

newTreeSet

public static <E extends Comparable> TreeSet<E> newTreeSet()
Creates a mutable, empty TreeSet instance sorted by the natural sort ordering of its elements.

Note: if mutability is not required, use ImmutableSortedSet.of() instead.

Returns:
a new, empty TreeSet

newTreeSet

public static <E extends Comparable> TreeSet<E> newTreeSet(Iterable<? extends E> elements)
Creates a mutable TreeSet instance containing the given elements sorted by their natural ordering.

Note: if mutability is not required, use ImmutableSortedSet.copyOf(Iterable) instead.

Note: If elements is a SortedSet with an explicit comparator, this method has different behavior than TreeSet.TreeSet(SortedSet), which returns a TreeSet with that comparator.

Parameters:
elements - the elements that the set should contain
Returns:
a new TreeSet containing those elements (minus duplicates)

newTreeSet

public static <E> TreeSet<E> newTreeSet(Comparator<? super E> comparator)
Creates a mutable, empty TreeSet instance with the given comparator.

Note: if mutability is not required, use ImmutableSortedSet.orderedBy(comparator).build() instead.

Parameters:
comparator - the comparator to use to sort the set
Returns:
a new, empty TreeSet
Throws:
NullPointerException - if comparator is null

complementOf

public static <E extends Enum<E>> EnumSet<E> complementOf(Collection<E> collection)
Creates an EnumSet consisting of all enum values that are not in the specified collection. If the collection is an EnumSet, this method has the same behavior as EnumSet.complementOf(java.util.EnumSet). Otherwise, the specified collection must contain at least one element, in order to determine the element type. If the collection could be empty, use complementOf(Collection, Class) instead of this method.

Parameters:
collection - the collection whose complement should be stored in the enum set
Returns:
a new, modifiable EnumSet containing all values of the enum that aren't present in the given collection
Throws:
IllegalArgumentException - if collection is not an EnumSet instance and contains no elements

complementOf

public static <E extends Enum<E>> EnumSet<E> complementOf(Collection<E> collection,
                                                          Class<E> type)
Creates an EnumSet consisting of all enum values that are not in the specified collection. This is equivalent to EnumSet.complementOf(java.util.EnumSet), but can act on any input collection, as long as the elements are of enum type.

Parameters:
collection - the collection whose complement should be stored in the EnumSet
type - the type of the elements in the set
Returns:
a new, modifiable EnumSet initially containing all the values of the enum not present in the given collection

newSetFromMap

public static <E> Set<E> newSetFromMap(Map<E,Boolean> map)
Returns a set backed by the specified map. The resulting set displays the same ordering, concurrency, and performance characteristics as the backing map. In essence, this factory method provides a Set implementation corresponding to any Map implementation. There is no need to use this method on a Map implementation that already has a corresponding Set implementation (such as HashMap or TreeMap).

Each method invocation on the set returned by this method results in exactly one method invocation on the backing map or its keySet view, with one exception. The addAll method is implemented as a sequence of put invocations on the backing map.

The specified map must be empty at the time this method is invoked, and should not be accessed directly after this method returns. These conditions are ensured if the map is created empty, passed directly to this method, and no reference to the map is retained, as illustrated in the following code fragment: 

  Set<Object> identityHashSet = Sets.newSetFromMap(
      new IdentityHashMap<Object, Boolean>());
This method has the same behavior as the JDK 6 method Collections.newSetFromMap(). The returned set is serializable if the backing map is.

Parameters:
map - the backing map
Returns:
the set backed by the map
Throws:
IllegalArgumentException - if map is not empty

union

public static <E> Sets.SetView<E> union(Set<? extends E> set1,
                                        Set<? extends E> set2)
Returns an unmodifiable view of the union of two sets. The returned set contains all elements that are contained in either backing set. Iterating over the returned set iterates first over all the elements of set1, then over each element of set2, in order, that is not contained in set1.

Results are undefined if set1 and set2 are sets based on different equivalence relations (as HashSet, TreeSet, and the Map.keySet() of an IdentityHashMap all are).

Note: The returned view performs better when set1 is the smaller of the two sets. If you have reason to believe one of your sets will generally be smaller than the other, pass it first.

intersection

public static <E> Sets.SetView<E> intersection(Set<E> set1,
                                               Set<?> set2)
Returns an unmodifiable view of the intersection of two sets. The returned set contains all elements that are contained by both backing sets. The iteration order of the returned set matches that of set1.

Results are undefined if set1 and set2 are sets based on different equivalence relations (as HashSet, TreeSet, and the keySet of an IdentityHashMap all are).

Note: The returned view performs slightly better when set1 is the smaller of the two sets. If you have reason to believe one of your sets will generally be smaller than the other, pass it first. Unfortunately, since this method sets the generic type of the returned set based on the type of the first set passed, this could in rare cases force you to make a cast, for example: 

  Set<Object> aFewBadObjects = ...
  Set<String> manyBadStrings = ...

  // impossible for a non-String to be in the intersection
  SuppressWarnings("unchecked")
  Set<String> badStrings = (Set) Sets.intersection(
      aFewBadObjects, manyBadStrings);
This is unfortunate, but should come up only very rarely.

difference

public static <E> Sets.SetView<E> difference(Set<E> set1,
                                             Set<?> set2)
Returns an unmodifiable view of the difference of two sets. The returned set contains all elements that are contained by set1 and not contained by set2. set2 may also contain elements not present in set1; these are simply ignored. The iteration order of the returned set matches that of set1.

Results are undefined if set1 and set2 are sets based on different equivalence relations (as HashSet, TreeSet, and the keySet of an IdentityHashMap all are).

filter

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

The resulting set's iterator does not support remove(), but all other set methods are supported. The set'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 set, only elements that satisfy the filter will be removed from the underlying collection.

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

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

cartesianProduct

public static <B> Set<List<B>> cartesianProduct(List<? extends Set<? extends B>> sets)
Returns every possible list that can be formed by choosing one element from each of the given sets in order; the "n-ary Cartesian product" of the sets. For example: 
   cartesianProduct(ImmutableList.of(
       ImmutableSet.of(1, 2),
       ImmutableSet.of("A", "B", "C")))
returns a set containing six lists: The order in which these lists are returned is not guaranteed, however the position of an element inside a tuple always corresponds to the position of the set from which it came in the input list. Note that if any input set is empty, the Cartesian product will also be empty. If no sets at all are provided (an empty list), the resulting Cartesian product has one element, an empty list (counter-intuitive, but mathematically consistent).

Type Parameters:
B - any common base class shared by all axes (often just Object)
Parameters:
sets - the sets to choose elements from, in the order that the elements chosen from those sets should appear in the resulting lists
Returns:
the Cartesian product, as an immutable set containing immutable lists
Throws:
NullPointerException - if sets, any one of the sets, or any element of a provided set is null
Since:
2010.01.04 tentative

cartesianProduct

public static <B> Set<List<B>> cartesianProduct(Set<? extends B>... sets)
Returns every possible list that can be formed by choosing one element from each of the given sets in order; the "n-ary Cartesian product" of the sets. For example: 
   cartesianProduct(
       ImmutableSet.of(1, 2),
       ImmutableSet.of("A", "B", "C"))
returns a set containing six lists: w The order in which these lists are returned is not guaranteed, however the position of an element inside a tuple always corresponds to the position of the set from which it came in the input list. Note that if any input set is empty, the Cartesian product will also be empty. If no sets at all are provided, the resulting Cartesian product has one element, an empty list (counter-intuitive, but mathematically consistent).

Type Parameters:
B - any common base class shared by all axes (often just Object)
Parameters:
sets - the sets to choose elements from, in the order that the elements chosen from those sets should appear in the resulting lists
Returns:
the Cartesian product, as an immutable set containing immutable lists
Throws:
NullPointerException - if sets, any one of the sets, or any element of a provided set is null
Since:
2010.01.04 tentative
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD