com.google.common.collect
Class Sets

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

public final class Sets
extends 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.

WARNING: These factories do not support the full variety of tuning parameters available in the collection constructors. Use them only for collections which will always remain small, or for which the cost of future growth operations is not a concern.

Author:

Kevin Bourrillion

Method Summary

static <E extends Enum<E>> EnumSet<E>	complementOf(Collection<E> collection) Creates an enum set with the given element type, initially containing all the elements of this type that are not contained in the specified set.
static <E extends Enum<E>> EnumSet<E>	complementOf(Collection<E> collection, Class<E> type) Creates an enum set with the given element type, initially containing all the elements of this type that are not contained in the specified set.
static <E> SortedSet<E>	emptySortedSet() Returns the empty sorted set (immutable).
static <E extends Enum<E>> Set<E>	immutableEnumSet(E anElement, E... otherElements) Returns an immutable Set instance containing the given elements of an enumerated type.
static <E> Set<E>	immutableSet() Optimization of #immutableSet for zero arguments.
static <E> Set<E>	immutableSet(Collection<E> collection) Returns an immutable Set instance containing the elements in the provided set.
static <E> Set<E>	immutableSet(E... elements) Returns an immutable Set instance containing the given elements.
static <E> Set<E>	immutableSet(E element) Optimization of #immutableSet for one argument.
static <E extends Comparable> SortedSet<E>	immutableSortedSet() Returns an empty sorted set.
static <E> SortedSet<E>	immutableSortedSet(Comparator<? super E> comparator) Returns an empty sorted set having the given Comparator.
static <E> SortedSet<E>	immutableSortedSet(Comparator<? super E> comparator, E... elements) Returns an immutable SortedSet instance containing the given elements sorted by the given Comparator.
static <E> SortedSet<E>	immutableSortedSet(Comparator<? super E> comparator, E element) Returns a sorted set having only the given element and the given Comparator.
static <E extends Comparable> SortedSet<E>	immutableSortedSet(E... elements) Returns an immutable SortedSet instance containing the given elements sorted by their natural ordering.
static <E extends Comparable> SortedSet<E>	immutableSortedSet(E element) Returns a sorted set having only the given element.
static <E> Set<E>	newConcurrentHashSet() Creates a thread-safe set backed by a hash map.
static <E> Set<E>	newConcurrentHashSet(E... elements) Creates a thread-safe set backed by a hash map, and containing the given elements.
static <E> Set<E>	newConcurrentHashSet(Iterable<? extends E> elements) Creates a thread-safe set backed by a hash map, and containing the given elements.
static <E> Set<E>	newConcurrentHashSet(Iterator<? extends E> elements) Creates a thread-safe set backed by a hash map, and containing the given elements.
static <E> HashSet<E>	newHashSet() Creates an empty HashSet instance.
static <E> HashSet<E>	newHashSet(E... elements) Creates a HashSet instance containing the given elements.
static <E> HashSet<E>	newHashSet(Iterable<? extends E> elements) Creates a HashSet instance containing the given elements.
static <E> HashSet<E>	newHashSet(Iterator<? extends E> elements) Creates a HashSet instance containing the given elements.
static <E> LinkedHashSet<E>	newLinkedHashSet() Creates an empty LinkedHashSet instance.
static <E> LinkedHashSet<E>	newLinkedHashSet(E... elements) Creates a LinkedHashSet instance containing the given elements.
static <E> LinkedHashSet<E>	newLinkedHashSet(Iterable<? extends E> elements) Creates a LinkedHashSet instance containing the given elements.
static <E> LinkedHashSet<E>	newLinkedHashSet(Iterator<? extends E> elements) Creates a LinkedHashSet instance containing the given elements.
static <E> Set<E>	newSetFromMap(Map<E,Boolean> map) Returns a set backed by the specified map.
static <E extends Comparable> SortedArraySet<E>	newSortedArraySet() Creates an empty SortedArraySet instance, with an initial capacity of zero.
static <E> SortedArraySet<E>	newSortedArraySet(Comparator<? super E> comparator) Creates an empty SortedArraySet instance, with an initial capacity of zero.
static <E> SortedArraySet<E>	newSortedArraySet(Comparator<? super E> comparator, E... elements) Creates a SortedArraySet instance containing the given elements.
static <E extends Comparable> SortedArraySet<E>	newSortedArraySet(E... elements) Creates a SortedArraySet instance containing the given elements.
static <E extends Comparable> SortedArraySet<E>	newSortedArraySet(Iterable<? extends E> elements) Creates a SortedArraySet instance containing the given elements.
static <E> SortedArraySet<E>	newSortedArraySet(Iterable<? extends E> elements, Comparator<? super E> comparator) Creates a SortedArraySet instance containing the given elements.
static <E extends Comparable> TreeSet<E>	newTreeSet() Creates a TreeSet instance using the default Comparator.
static <E> TreeSet<E>	newTreeSet(Comparator<? super E> comparator) Creates a TreeSet instance using the given Comparator.
static <E> TreeSet<E>	newTreeSet(Comparator<? super E> comparator, E... elements) Creates a TreeSet instance using the given Comparator and containing the given elements.
static <E> TreeSet<E>	newTreeSet(Comparator<? super E> comparator, Iterable<? extends E> elements) Creates a TreeSet instance using the given Comparator and containing the given elements.
static <E> TreeSet<E>	newTreeSet(Comparator<? super E> comparator, Iterator<? extends E> elements) Creates a TreeSet instance using the given Comparator and containing the given elements.
static <E extends Comparable> TreeSet<E>	newTreeSet(E... elements) Creates a TreeSet instance using the default Comparator and containing the given elements.
static <E extends Comparable> TreeSet<E>	newTreeSet(Iterable<? extends E> elements) Creates a TreeSet instance using the default Comparator and containing the given elements.
static <E extends Comparable> TreeSet<E>	newTreeSet(Iterator<? extends E> elements) Creates a TreeSet instance using the default Comparator and containing the given elements.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

immutableSortedSet

public static <E extends Comparable> SortedSet<E> immutableSortedSet(E... elements)

Returns an immutable SortedSet instance containing the given elements sorted by their natural ordering.

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

SortedSet<Base> set = Sets.immutableSortedSet(sub1, sub2);

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

SortedSet<Base> set = Sets.<Base>immutableSortedSet(sub1, sub2);

Parameters:

elements - the elements that the set should contain

Returns:

an immutable SortedSet instance containing those elements, minus duplicates

immutableSortedSet

public static <E> SortedSet<E> immutableSortedSet(@Nullable
                                                  Comparator<? super E> comparator,
                                                  E... elements)

Returns an immutable SortedSet instance containing the given elements sorted by the given Comparator.

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

SortedSet<Base> set = Sets.immutableSortedSet(sub1, sub2);

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

SortedSet<Base> set = Sets.<Base>immutableSortedSet(sub1, sub2);

Parameters:

comparator - the comparator to sort the elements by

elements - the elements that the set should contain

Returns:

an immutable SortedSet instance containing those elements, minus duplicates

immutableSortedSet

public static <E extends Comparable> SortedSet<E> immutableSortedSet()

Returns an empty sorted set. This is an optimization of immutableSortedSet(Comparable...) for zero arguments.

Returns:

an immutable empty sorted set

immutableSortedSet

public static <E> SortedSet<E> immutableSortedSet(@Nullable
                                                  Comparator<? super E> comparator)

Returns an empty sorted set having the given Comparator. This is an optimization of immutableSortedSet(Comparator,Object...) for zero arguments.

Parameters:

comparator - the comparator for the empty set

Returns:

an immutable empty sorted set

immutableSortedSet

public static <E extends Comparable> SortedSet<E> immutableSortedSet(E element)

Returns a sorted set having only the given element. This is an optimization of immutableSortedSet(Comparable...) for one argument.

Parameters:

element - the lone element to be in the returned set

Returns:

an immutable sorted set containing only the given element

immutableSortedSet

public static <E> SortedSet<E> immutableSortedSet(@Nullable
                                                  Comparator<? super E> comparator,
                                                  @Nullable
                                                  E element)

Returns a sorted set having only the given element and the given Comparator. This is an optimization of immutableSortedSet(Comparator,Object...) for one argument.

Parameters:

comparator - the comparator for the one-element set

element - the lone element to be in the returned set

Returns:

an immutable sorted set containing only the given element

immutableSet

public static <E> Set<E> immutableSet(E... elements)

Returns an immutable Set instance containing the given elements.

Unlike an unmodifiable set such as that returned by Collections.unmodifiableSet(), which provides a read-only view of an underlying set which may itself be mutable, an immutable set makes a copy of the original set or collection, so that changes to the original are not reflected in the immutable set.

Immutability has two important advantages over unmodifiability. First, it allows the hash code to be computed once and cached, rather than computed every time it is needed, which takes O(n) time for a set of n elements. Second, it prevents any inadvertent modification of the value of the set. This is critical, for example, if the set is an element of a HashSet or a key in a HashMap.

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

Set<Base> set = Sets.immutableSet(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>immutableSet(sub1, sub2);

Note: If <E> is an enum type, use immutableEnumSet(E, E...) instead.

Parameters:

elements - the elements that the set should contain

Returns:

an immutable Set instance containing those elements, minus duplicates

immutableSet

public static <E> Set<E> immutableSet()

Optimization of #immutableSet for zero arguments.

Returns:

an immutable empty set

See Also:

Collections.emptySet()

immutableSet

public static <E> Set<E> immutableSet(@Nullable
                                      E element)

Optimization of #immutableSet for one argument.

Parameters:

element - the lone element to be in the returned set

Returns:

an immutable set containing only the given element

See Also:

Collections.singleton(T)

immutableSet

public static <E> Set<E> immutableSet(Collection<E> collection)

Returns an immutable Set instance containing the elements in the provided set. See immutableSet(Object...) for details.

Parameters:

collection - a collection containing the elements to be in the returned set

Returns:

an immutable Set instance containing those elements

immutableEnumSet

public static <E extends Enum<E>> Set<E> immutableEnumSet(E anElement,
                                                          E... otherElements)

Returns an immutable Set instance containing the given elements of an enumerated type. Internally this set will be backed by an EnumSet.

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 these elements, minus duplicates

newHashSet

public static <E> 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 only need an immutable empty Set, use Collections.emptySet() instead.

Returns:

a newly-created, initially-empty HashSet

newHashSet

public static <E> 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 it is an immutable Set you seek, you should use immutableSet(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)

newHashSet

public static <E> HashSet<E> newHashSet(Iterable<? extends E> elements)

Creates a HashSet instance containing the given elements.

Note: if E is an Enum type, and elements is a Collection, use EnumSet.copyOf(Collection) instead.

Parameters:

elements - the elements that the set should contain

Returns:

a newly-created HashSet containing those elements (minus duplicates)

newHashSet

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

Creates a HashSet instance containing the given elements.

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

Parameters:

elements - the elements that the set should contain

Returns:

a newly-created HashSet containing those elements (minus duplicates)

newConcurrentHashSet

public static <E> 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.

Returns:

a newly-created, initially-empty thread-safe Set

newConcurrentHashSet

public static <E> 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.

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)

newConcurrentHashSet

public static <E> Set<E> newConcurrentHashSet(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.

Parameters:

elements - the elements that the set should contain

Returns:

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

newConcurrentHashSet

public static <E> Set<E> newConcurrentHashSet(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.

Parameters:

elements - the elements that the set should contain

Returns:

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

newLinkedHashSet

public static <E> LinkedHashSet<E> newLinkedHashSet()

Creates an empty LinkedHashSet instance.

Returns:

a newly-created, initially-empty LinkedHashSet

newLinkedHashSet

public static <E> LinkedHashSet<E> newLinkedHashSet(E... elements)

Creates a LinkedHashSet instance containing the given elements.

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

Parameters:

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

Returns:

a newly-created LinkedHashSet containing those elements (minus duplicates)

newLinkedHashSet

public static <E> LinkedHashSet<E> newLinkedHashSet(Iterable<? extends E> elements)

Creates a LinkedHashSet instance containing the given elements.

Parameters:

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

Returns:

a newly-created LinkedHashSet containing those elements (minus duplicates)

newLinkedHashSet

public static <E> LinkedHashSet<E> newLinkedHashSet(Iterator<? extends E> elements)

Creates a LinkedHashSet instance containing the given elements.

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 Comparable> TreeSet<E> newTreeSet()

Creates a TreeSet instance using the default Comparator.

Note: If E is an Enum type, and you don't require the set to implement SortedSet (only ordered iteration), use EnumSet.noneOf(java.lang.Class) instead.

Returns:

a newly-created, initially-empty TreeSet

newTreeSet

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

Creates a TreeSet instance using the default Comparator and containing the given elements.

Note: If E is an Enum type, and you don't require the set to implement SortedSet (only ordered iteration), use EnumSet.of(Enum, Enum...) instead.

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 Comparable> TreeSet<E> newTreeSet(Iterable<? extends E> elements)

Creates a TreeSet instance using the default Comparator and containing the given elements.

Note: If E is an Enum type, and you don't require the set to implement SortedSet (only ordered iteration), use EnumSet.copyOf(Collection) instead.

Parameters:

elements - the elements that the set should contain

Returns:

a newly-created TreeSet containing those elements (minus duplicates)

newTreeSet

public static <E extends Comparable> TreeSet<E> newTreeSet(Iterator<? extends E> elements)

Creates a TreeSet instance using the default Comparator and containing the given elements.

Note: if E is an Enum type, and you don't require the set to implement SortedSet (only ordered iteration), you should manually create an EnumSet instead.

Parameters:

elements - the elements that the set should contain

Returns:

a newly-created TreeSet containing those elements (minus duplicates)

newTreeSet

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

Creates a TreeSet instance using the given Comparator.

Parameters:

comparator - the comparator to use to sort the set

Returns:

a newly-created, initially-empty TreeSet

newTreeSet

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

Creates a TreeSet instance using the given Comparator and containing the given elements.

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> TreeSet<E> newTreeSet(@Nullable
                                        Comparator<? super E> comparator,
                                        Iterable<? extends E> elements)

Creates a TreeSet instance using the given Comparator and containing the given elements.

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> TreeSet<E> newTreeSet(@Nullable
                                        Comparator<? super E> comparator,
                                        Iterator<? extends E> elements)

Creates a TreeSet instance using the given Comparator and containing the given elements.

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)

newSortedArraySet

public static <E extends Comparable> SortedArraySet<E> newSortedArraySet()

Creates an empty SortedArraySet instance, with an initial capacity of zero.

TODO: change the initial capacity to the traditional default of ten.

Returns:

a newly-created, initially-empty SortedArraySet

newSortedArraySet

public static <E> SortedArraySet<E> newSortedArraySet(Comparator<? super E> comparator)

Creates an empty SortedArraySet instance, with an initial capacity of zero.

TODO: change the initial capacity to the traditional default of ten.

Parameters:

comparator - the comparator to use

Returns:

a newly-created, initially-empty SortedArraySet

newSortedArraySet

public static <E extends Comparable> SortedArraySet<E> newSortedArraySet(Iterable<? extends E> elements)

Creates a SortedArraySet instance containing the given elements.

TODO: change this method to preserve the ordering of the specified iterable if it is an instance of SortedSet.

Parameters:

elements - the elements that the set should contain

Returns:

a newly-created SortedArraySet containing those elements (minus duplicates)

newSortedArraySet

public static <E> SortedArraySet<E> newSortedArraySet(Iterable<? extends E> elements,
                                                      Comparator<? super E> comparator)

Creates a SortedArraySet instance containing the given elements.

TODO: change the initial capacity to the traditional default of ten, if the iterable is not a collection.

Parameters:

elements - the elements that the set should contain

comparator - the comparator to use

Returns:

a newly-created SortedArraySet containing those elements (minus duplicates)

newSortedArraySet

public static <E> SortedArraySet<E> newSortedArraySet(Comparator<? super E> comparator,
                                                      E... elements)

Creates a SortedArraySet instance containing the given elements.

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

Parameters:

comparator - the comparator to use

elements - the elements that the set should contain

Returns:

a newly-created SortedArraySet containing those elements (minus duplicates)

newSortedArraySet

public static <E extends Comparable> SortedArraySet<E> newSortedArraySet(E... elements)

Creates a SortedArraySet instance containing the given elements.

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 SortedArraySet containing those elements (minus duplicates)

complementOf

public static <E extends Enum<E>> EnumSet<E> complementOf(Collection<E> collection)

Creates an enum set with the given element type, initially containing all the elements of this type that are not contained in the specified set. If the specified collection is an EnumSet instance, this method behaves identically to EnumSet.complementOf(java.util.EnumSet). Otherwise, the specified collection must contain at least one element (in order to determine the new enum set's element type). If the collection could possibly be empty, use complementOf(Collection,Class) instead of this method.

Parameters:

collection - the collection from whose complement to initialize the enum set

Returns:

a new, modifiable enum set initially containing all the values of the enum not present in the given set

Throws:

IllegalArgumentException - if set 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 enum set with the given element type, initially containing all the elements of this type that are not contained in the specified set. This is equivalent to EnumSet.complementOf(java.util.EnumSet), but can act on any type of set, so long as the elements are of enum type.

Parameters:

collection - the collection from whose complement to initialize this enum set

type - the type of the elements in the set

Returns:

a new, modifiable enum set initially containing all the values of the enum not present in the given set

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).

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<Foo> identityHashSet = Sets.newSetFromMap(
       new IdentityHashMap<Foo, Boolean>());

emptySortedSet

public static <E> SortedSet<E> emptySortedSet()

Returns the empty sorted set (immutable). This set is serializable.