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

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

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