com.google.common.collect
Class Sets

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

public final class Sets
extends java.lang.Object

Provides static methods for creating mutable Set instances easily and other static methods for working with sets.

You can replace code like:

Set<String> set = new HashSet<String>();
Collections.addAll(set, "foo", "bar", "baz");

with just:

Set<String> set = newHashSet("foo", "bar", "baz");

You can also create an empty Set, or populate your new Set using any array, Iterator or Iterable.

See also this class's counterparts Lists and Maps.

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 <E extends java.lang.Enum<E>> java.util.EnumSet<E>	complementOf(java.util.Collection<E> collection) Creates an EnumSet consisting of all enum values that are not in the specified collection.
static <E extends java.lang.Enum<E>> java.util.EnumSet<E>	complementOf(java.util.Collection<E> collection, java.lang.Class<E> type) Creates an EnumSet consisting of all enum values that are not in the specified collection.
static <E> Sets.SetView<E>	difference(java.util.Set<E> set1, java.util.Set<?> set2) Returns an unmodifiable view of the difference of two sets.
static <E extends java.lang.Enum<E>> java.util.Set<E>	immutableEnumSet(E anElement, E... otherElements) Returns an immutable set instance containing the given enum elements.
static <E> Sets.SetView<E>	intersection(java.util.Set<E> set1, java.util.Set<?> set2) Returns an unmodifiable view of the intersection of two sets.
static <E> java.util.Set<E>	newConcurrentHashSet() Creates a thread-safe set backed by a hash map.
static <E> java.util.Set<E>	newConcurrentHashSet(E... elements) Creates a thread-safe set backed by a hash map and containing the given elements.
static <E> java.util.Set<E>	newConcurrentHashSet(java.lang.Iterable<? extends E> elements) Creates a thread-safe set backed by a hash map and containing the given elements.
static <E> java.util.Set<E>	newConcurrentHashSet(java.util.Iterator<? extends E> elements) Creates a thread-safe set backed by a hash map and containing the given elements.
static <E extends java.lang.Enum<E>> java.util.EnumSet<E>	newEnumSet(java.lang.Iterable<E> iterable, java.lang.Class<E> elementType) Returns a new EnumSet instance containing the given elements.
static <E> java.util.HashSet<E>	newHashSet() Creates an empty HashSet instance.
static <E> java.util.HashSet<E>	newHashSet(E... elements) Creates a HashSet instance containing the given elements.
static <E> java.util.HashSet<E>	newHashSet(java.lang.Iterable<? extends E> elements) Creates a HashSet instance containing the given elements.
static <E> java.util.HashSet<E>	newHashSet(java.util.Iterator<? extends E> elements) Creates a HashSet instance containing the given elements.
static <E> java.util.HashSet<E>	newHashSetWithExpectedSize(int expectedSize) Creates an empty HashSet instance with enough capacity to hold the specified number of elements without rehashing.
static <E> java.util.Set<E>	newIdentityHashSet(ReferenceType referenceType) Creates an empty Set that uses identity to determine equality.
static <E> java.util.LinkedHashSet<E>	newLinkedHashSet() Creates an empty LinkedHashSet instance.
static <E> java.util.LinkedHashSet<E>	newLinkedHashSet(java.lang.Iterable<? extends E> elements) Creates a LinkedHashSet instance containing the given elements.
static <E> java.util.Set<E>	newSetFromMap(java.util.Map<E,java.lang.Boolean> map) Returns a set backed by the specified map.
static <E extends java.lang.Comparable> java.util.TreeSet<E>	newTreeSet() Creates an empty TreeSet instance sorted by the natural sort ordering of its elements.
static <E> java.util.TreeSet<E>	newTreeSet(java.util.Comparator<? super E> comparator) Creates an empty TreeSet instance with the given comparator.
static <E> java.util.TreeSet<E>	newTreeSet(java.util.Comparator<? super E> comparator, E... elements) Creates a TreeSet instance containing the given elements sorted by the given comparator.
static <E> java.util.TreeSet<E>	newTreeSet(java.util.Comparator<? super E> comparator, java.lang.Iterable<? extends E> elements) Creates a TreeSet instance containing the given elements sorted by the given comparator.
static <E> java.util.TreeSet<E>	newTreeSet(java.util.Comparator<? super E> comparator, java.util.Iterator<? extends E> elements) Creates a TreeSet instance containing the given elements sorted by the given comparator.
static <E extends java.lang.Comparable> java.util.TreeSet<E>	newTreeSet(E... elements) Creates a TreeSet instance containing the given elements sorted by their natural ordering.
static <E extends java.lang.Comparable> java.util.TreeSet<E>	newTreeSet(java.lang.Iterable<? extends E> elements) Creates a TreeSet instance containing the given elements sorted by their natural ordering.
static <E extends java.lang.Comparable> java.util.TreeSet<E>	newTreeSet(java.util.Iterator<? extends E> elements) Creates a TreeSet instance containing the given elements sorted by their natural ordering.
static <E> Sets.SetView<E>	union(java.util.Set<? extends E> set1, java.util.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 java.lang.Enum<E>> java.util.Set<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. See ImmutableSet for a description of immutability. The set is serializable.

Parameters:

anElement - one of the elements the set should contain

otherElements - the rest of the elements the set should contain

Returns:

an immutable Set instance containing those elements, minus duplicates

newEnumSet

public static <E extends java.lang.Enum<E>> java.util.EnumSet<E> newEnumSet(java.lang.Iterable<E> iterable,
                                                                            java.lang.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> java.util.HashSet<E> newHashSet()

Creates an empty HashSet instance.

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

Note: if you need an immutable empty Set, use Collections.emptySet() instead.

Returns:

a newly created, empty HashSet

newHashSet

public static <E> java.util.HashSet<E> newHashSet(E... elements)

Creates a HashSet instance containing the given elements.

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

Note: if you need an immutable set without nulls, you should use ImmutableSet.of(Object...).

Note: due to a bug in javac 1.5.0_06, we cannot support the following:

Set<Base> set = Sets.newHashSet(sub1, sub2);

where sub1 and sub2 are references to subtypes of Base, not of Base itself. To get around this, you must use:

Set<Base> set = Sets.<Base>newHashSet(sub1, sub2);

Parameters:

elements - the elements that the set should contain

Returns:

a newly created HashSet containing those elements (minus duplicates)

newHashSetWithExpectedSize

public static <E> java.util.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 newly created HashSet, empty, with enough capacity to hold expectedSize elements without rehashing.

Throws:

java.lang.IllegalArgumentException - if expectedSize is negative

newHashSet

public static <E> java.util.HashSet<E> newHashSet(java.lang.Iterable<? extends E> elements)

Creates a HashSet instance containing the given elements.

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

Note: if you need an immutable set without nulls, you should use ImmutableSet.copyOf(java.lang.Iterable).

Parameters:

elements - the elements that the set should contain

Returns:

a newly created HashSet containing those elements (minus duplicates)

newHashSet

public static <E> java.util.HashSet<E> newHashSet(java.util.Iterator<? extends E> elements)

Creates a HashSet instance containing the given elements.

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

Note: if you need an immutable set without nulls, you should use ImmutableSet.

Parameters:

elements - the elements that the set should contain

Returns:

a newly created HashSet containing those elements (minus duplicates)

newConcurrentHashSet

public static <E> java.util.Set<E> newConcurrentHashSet()

Creates a thread-safe set backed by a hash map. The set is backed by a ConcurrentHashMap instance, and thus carries the same concurrency guarantees.

Unlike HashSet, this class does NOT allow null to be used as an element. The set is serializable.

Returns:

a newly created, empty thread-safe Set

newConcurrentHashSet

public static <E> java.util.Set<E> newConcurrentHashSet(E... elements)

Creates a thread-safe set backed by a hash map and containing the given elements. The set is backed by a ConcurrentHashMap instance, and thus carries the same concurrency guarantees.

Unlike HashSet, this class does NOT allow null to be used as an element. The set is serializable.

Please see the notice in newHashSet(Object...) about a relevant javac bug.

Parameters:

elements - the elements that the set should contain

Returns:

a newly created thread-safe Set containing those elements (minus duplicates)

Throws:

java.lang.NullPointerException - if any of the elements is null

newConcurrentHashSet

public static <E> java.util.Set<E> newConcurrentHashSet(java.lang.Iterable<? extends E> elements)

Creates a thread-safe set backed by a hash map and containing the given elements. The set is backed by a ConcurrentHashMap instance, and thus carries the same concurrency guarantees.

Unlike HashSet, this class does NOT allow null to be used as an element. The set is serializable.

Parameters:

elements - the elements that the set should contain

Returns:

a newly created thread-safe Set containing those elements (minus duplicates)

Throws:

java.lang.NullPointerException - if elements or any of its contents is null

newConcurrentHashSet

public static <E> java.util.Set<E> newConcurrentHashSet(java.util.Iterator<? extends E> elements)

Creates a thread-safe set backed by a hash map and containing the given elements. The set is backed by a ConcurrentHashMap instance, and thus carries the same concurrency guarantees.

Unlike HashSet, this class does NOT allow null to be used as an element. The set is serializable.

Parameters:

elements - the elements that the set should contain

Returns:

a newly created thread-safe Set containing those elements (minus duplicates)

Throws:

java.lang.NullPointerException - if elements or any of its contents is null

newLinkedHashSet

public static <E> java.util.LinkedHashSet<E> newLinkedHashSet()

Creates an empty LinkedHashSet instance.

Returns:

a newly created, empty LinkedHashSet

newLinkedHashSet

public static <E> java.util.LinkedHashSet<E> newLinkedHashSet(java.lang.Iterable<? extends E> elements)

Creates a LinkedHashSet instance containing the given elements.

Note: if you need an immutable set without nulls, you should use ImmutableSet.copyOf(Iterable).

Parameters:

elements - the elements that the set should contain, in order

Returns:

a newly created LinkedHashSet containing those elements (minus duplicates)

newTreeSet

public static <E extends java.lang.Comparable> java.util.TreeSet<E> newTreeSet()

Creates an empty TreeSet instance sorted by the natural sort ordering of its elements.

Returns:

a newly created, empty TreeSet

newTreeSet

public static <E extends java.lang.Comparable> java.util.TreeSet<E> newTreeSet(E... elements)

Creates a TreeSet instance containing the given elements sorted by their natural ordering.

Note: if you need an immutable sorted set without nulls, you should use ImmutableSortedSet.of(Comparable...).

Please see the notice in newHashSet(Object...) about a relevant javac bug.

Parameters:

elements - the elements that the set should contain

Returns:

a newly created TreeSet containing those elements (minus duplicates)

newTreeSet

public static <E extends java.lang.Comparable> java.util.TreeSet<E> newTreeSet(java.lang.Iterable<? extends E> elements)

Creates a TreeSet instance containing the given elements sorted by their natural ordering.

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.

Note: if you need an immutable sorted set without nulls, you should use ImmutableSortedSet.copyOf(Iterable).

Parameters:

elements - the elements that the set should contain

Returns:

a newly created TreeSet containing those elements (minus duplicates)

newTreeSet

public static <E extends java.lang.Comparable> java.util.TreeSet<E> newTreeSet(java.util.Iterator<? extends E> elements)

Creates a TreeSet instance containing the given elements sorted by their natural ordering.

Parameters:

elements - the elements that the set should contain

Returns:

a newly created TreeSet containing those elements (minus duplicates)

newTreeSet

public static <E> java.util.TreeSet<E> newTreeSet(@Nullable
                                                  java.util.Comparator<? super E> comparator)

Creates an empty TreeSet instance with the given comparator.

Parameters:

comparator - the comparator to use to sort the set

Returns:

a newly created, empty TreeSet

newTreeSet

public static <E> java.util.TreeSet<E> newTreeSet(@Nullable
                                                  java.util.Comparator<? super E> comparator,
                                                  E... elements)

Creates a TreeSet instance containing the given elements sorted by the given comparator.

Note: if you need an immutable sorted set without nulls, you should use ImmutableSortedSet.of(Comparator, Object...).

Please see the notice in newHashSet(Object...) about a relevant javac bug.

Parameters:

comparator - the comparator to use to sort the set

elements - the elements that the set should contain

Returns:

a newly created TreeSet containing those elements (minus duplicates)

newTreeSet

public static <E> java.util.TreeSet<E> newTreeSet(@Nullable
                                                  java.util.Comparator<? super E> comparator,
                                                  java.lang.Iterable<? extends E> elements)

Creates a TreeSet instance containing the given elements sorted by the given comparator.

Note: if you need an immutable sorted set without nulls, you should use ImmutableSortedSet.copyOf(Comparator, Iterable).

Parameters:

comparator - the comparator to use to sort the set

elements - the elements that the set should contain

Returns:

a newly created TreeSet containing those elements (minus duplicates)

newTreeSet

public static <E> java.util.TreeSet<E> newTreeSet(@Nullable
                                                  java.util.Comparator<? super E> comparator,
                                                  java.util.Iterator<? extends E> elements)

Creates a TreeSet instance containing the given elements sorted by the given comparator.

Parameters:

comparator - the comparator to use to sort the set

elements - the elements that the set should contain

Returns:

a newly created TreeSet containing those elements (minus duplicates)

newIdentityHashSet

public static <E> java.util.Set<E> newIdentityHashSet(ReferenceType referenceType)

Creates an empty Set that uses identity to determine equality. It compares object references, instead of calling equals, to determine whether a provided object matches an element in the set. For example, contains returns false when passed an object that equals a set member, but isn't the same instance. This behavior is similar to the way IdentityHashMap handles key lookups.

The referenceType parameter specifies the kind of reference that the returned set uses: ReferenceType.STRONG, ReferenceType.WEAK, or ReferenceType.SOFT. The returned set is thread-safe when the reference type is ReferenceType.WEAK or ReferenceType.SOFT, but not when the reference type is ReferenceType.STRONG.

Throws:

java.lang.IllegalArgumentException - if referenceType is ReferenceType.PHANTOM

complementOf

public static <E extends java.lang.Enum<E>> java.util.EnumSet<E> complementOf(java.util.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:

java.lang.IllegalArgumentException - if collection is not an EnumSet instance and contains no elements

complementOf

public static <E extends java.lang.Enum<E>> java.util.EnumSet<E> complementOf(java.util.Collection<E> collection,
                                                                              java.lang.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> java.util.Set<E> newSetFromMap(java.util.Map<E,java.lang.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:

java.lang.IllegalArgumentException - if map is not empty

union

public static <E> Sets.SetView<E> union(java.util.Set<? extends E> set1,
                                        java.util.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).

intersection

public static <E> Sets.SetView<E> intersection(java.util.Set<E> set1,
                                               java.util.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).

difference

public static <E> Sets.SetView<E> difference(java.util.Set<E> set1,
                                             java.util.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).