Sets
Date: 2016-05-24

com.google.common.collect

## Class Sets

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

-     @GwtCompatible(emulated=true)
      public final class Sets
      extends java.lang.Object

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

  See the Guava User Guide article on `Sets`.

  Since:
    2.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <B> java.util.Set<java.util.List<B>>` | `cartesianProduct(java.util.List<? extends java.util.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> java.util.Set<java.util.List<B>>` | `cartesianProduct(java.util.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 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> java.util.NavigableSet<E>` | `filter(java.util.NavigableSet<E> unfiltered, Predicate<? super E> predicate)` Returns the elements of a `NavigableSet`, `unfiltered`, that satisfy a predicate.
    `static <E> java.util.Set<E>` | `filter(java.util.Set<E> unfiltered, Predicate<? super E> predicate)` Returns the elements of `unfiltered` that satisfy a predicate.
    `static <E> java.util.SortedSet<E>` | `filter(java.util.SortedSet<E> unfiltered, Predicate<? super E> predicate)` Returns the elements of a `SortedSet`, `unfiltered`, that satisfy a predicate.
    `static <E extends java.lang.Enum<E>> ImmutableSet<E>` | `immutableEnumSet(E anElement, E... otherElements)` Returns an immutable set instance containing the given enum elements.
    `static <E extends java.lang.Enum<E>> ImmutableSet<E>` | `immutableEnumSet(java.lang.Iterable<E> elements)` 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(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.concurrent.CopyOnWriteArraySet<E>` | `newCopyOnWriteArraySet()` Creates an empty `CopyOnWriteArraySet` instance.
    `static <E> java.util.concurrent.CopyOnWriteArraySet<E>` | `newCopyOnWriteArraySet(java.lang.Iterable<? extends E> elements)` Creates a `CopyOnWriteArraySet` instance 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, mutable `EnumSet` instance containing the given elements in their natural order.
    `static <E> java.util.HashSet<E>` | `newHashSet()` Creates a mutable, initially empty `HashSet` instance.
    `static <E> java.util.HashSet<E>` | `newHashSet(E... elements)` Creates a mutable `HashSet` instance initially containing the given elements.
    `static <E> java.util.HashSet<E>` | `newHashSet(java.lang.Iterable<? extends E> elements)` Creates a mutable `HashSet` instance containing the given elements.
    `static <E> java.util.HashSet<E>` | `newHashSet(java.util.Iterator<? extends E> elements)` Creates a mutable `HashSet` instance containing the given elements.
    `static <E> java.util.HashSet<E>` | `newHashSetWithExpectedSize(int expectedSize)` Creates a `HashSet` instance, with a high enough initial table size that it should hold `expectedSize` elements without resizing.
    `static <E> java.util.Set<E>` | `newIdentityHashSet()` Creates an empty `Set` that uses identity to determine equality.
    `static <E> java.util.LinkedHashSet<E>` | `newLinkedHashSet()` Creates a mutable, empty `LinkedHashSet` instance.
    `static <E> java.util.LinkedHashSet<E>` | `newLinkedHashSet(java.lang.Iterable<? extends E> elements)` Creates a mutable `LinkedHashSet` instance containing the given elements in order.
    `static <E> java.util.LinkedHashSet<E>` | `newLinkedHashSetWithExpectedSize(int expectedSize)` Creates a `LinkedHashSet` instance, with a high enough "initial capacity" that it should hold `expectedSize` elements without growth.
    `static <E> java.util.Set<E>` | `newSetFromMap(java.util.Map<E,java.lang.Boolean> map)` Deprecated. Use `Collections.newSetFromMap(java.util.Map<E, java.lang.Boolean>)` instead. This method will be removed in August 2017.
    `static <E extends java.lang.Comparable> java.util.TreeSet<E>` | `newTreeSet()` Creates a mutable, 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 a mutable, empty `TreeSet` instance with the given comparator.
    `static <E extends java.lang.Comparable> java.util.TreeSet<E>` | `newTreeSet(java.lang.Iterable<? extends E> elements)` Creates a mutable `TreeSet` instance containing the given elements sorted by their natural ordering.
    `static <E> java.util.Set<java.util.Set<E>>` | `powerSet(java.util.Set<E> set)` Returns the set of all possible subsets of `set`.
    `static <E> Sets.SetView<E>` | `symmetricDifference(java.util.Set<? extends E> set1, java.util.Set<? extends E> set2)` Returns an unmodifiable view of the symmetric difference of two sets.
    `static <E> java.util.NavigableSet<E>` | `synchronizedNavigableSet(java.util.NavigableSet<E> navigableSet)` Returns a synchronized (thread-safe) navigable set backed by the specified navigable set.
    `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.
    `static <E> java.util.NavigableSet<E>` | `unmodifiableNavigableSet(java.util.NavigableSet<E> set)` Returns an unmodifiable view of the specified navigable set.

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### immutableEnumSet

          @GwtCompatible(serializable=true)
          public static <E extends java.lang.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

          @GwtCompatible(serializable=true)
          public static <E extends java.lang.Enum<E>> ImmutableSet<E> immutableEnumSet(java.lang.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 java.lang.Enum<E>> java.util.EnumSet<E> newEnumSet(java.lang.Iterable<E> iterable,
                                                                      java.lang.Class<E> elementType)

      Returns a new, mutable `EnumSet` instance containing the given elements in their natural order. This method behaves identically to `EnumSet.copyOf(Collection)`, but also accepts non-`Collection` iterables and empty iterables.

    - #### newHashSet

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

      Creates a mutable, initially empty `HashSet` instance.

      Note: if mutability is not required, use `ImmutableSet.of()` instead. If `E` is an `Enum` type, use `EnumSet.noneOf(java.lang.Class<E>)` instead. Otherwise, strongly consider using a `LinkedHashSet` instead, at the cost of increased memory footprint, to get deterministic iteration behavior.

      Note for Java 7 and later: this method is now unnecessary and should be treated as deprecated. Instead, use the `HashSet` constructor directly, taking advantage of the new "diamond" syntax.

    - #### newHashSet

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

      Creates a mutable `HashSet` instance initially containing the given elements.

      Note: if elements are non-null and won't be added or removed after this point, use `ImmutableSet.of()` or `ImmutableSet.copyOf(Object[])` instead. If `E` is an `Enum` type, use `EnumSet.of(Enum, Enum[])` instead. Otherwise, strongly consider using a `LinkedHashSet` instead, at the cost of increased memory footprint, to get deterministic iteration behavior.

      This method is just a small convenience, either for `newHashSet(``asList``(...))`, or for creating an empty set then calling `Collections.addAll(java.util.Collection<? super T>, T...)`. This method is not actually very useful and will likely be deprecated in the future.

    - #### newHashSetWithExpectedSize

          public static <E> java.util.HashSet<E> newHashSetWithExpectedSize(int expectedSize)

      Creates a `HashSet` instance, with a high enough initial table size that it should hold `expectedSize` elements without resizing. This behavior cannot be broadly guaranteed, but it is observed to be true for OpenJDK 1.7. It also can't be guaranteed that the method isn't inadvertently oversizing the returned set.
      Parameters:
        `expectedSize` - the number of elements you expect to add to the returned set
      Returns:
        a new, empty `HashSet` with enough capacity to hold `expectedSize` elements without resizing
      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 mutable `HashSet` instance containing the given elements. A very thin convenience for creating an empty set then calling `Collection.addAll(java.util.Collection<? extends E>)` or `Iterables.addAll(java.util.Collection<T>, java.lang.Iterable<? extends T>)`.

      Note: if mutability is not required and the elements are non-null, use `ImmutableSet.copyOf(Iterable)` instead. (Or, change `elements` to be a `FluentIterable` and call `elements.toSet()`.)

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

      Note for Java 7 and later: if `elements` is a `Collection`, you don't need this method. Instead, use the `HashSet` constructor directly, taking advantage of the new "diamond" syntax.

      Overall, this method is not very useful and will likely be deprecated in the future.

    - #### newHashSet

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

      Creates a mutable `HashSet` instance containing the given elements. A very thin convenience for creating an empty set and then calling `Iterators.addAll(java.util.Collection<T>, java.util.Iterator<? extends T>)`.

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

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

      Overall, this method is not very useful and will likely be deprecated in the future.

    - #### 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 new, empty thread-safe `Set`
      Since:
        15.0

    - #### 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 new thread-safe set containing those elements (minus duplicates)
      Throws:
        `java.lang.NullPointerException` - if `elements` or any of its contents is null
      Since:
        15.0

    - #### newLinkedHashSet

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

      Creates a mutable, empty `LinkedHashSet` instance.

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

      Returns:
        a new, empty `LinkedHashSet`

    - #### newLinkedHashSetWithExpectedSize

          public static <E> java.util.LinkedHashSet<E> newLinkedHashSetWithExpectedSize(int expectedSize)

      Creates a `LinkedHashSet` instance, with a high enough "initial capacity" that it should hold `expectedSize` elements without growth. This behavior cannot be broadly guaranteed, but it is observed to be true for OpenJDK 1.6. It also can't be guaranteed that the method isn't inadvertently oversizing the returned set.
      Parameters:
        `expectedSize` - the number of elements you expect to add to the returned set
      Returns:
        a new, empty `LinkedHashSet` with enough capacity to hold `expectedSize` elements without resizing
      Throws:
        `java.lang.IllegalArgumentException` - if `expectedSize` is negative
      Since:
        11.0

    - #### newLinkedHashSet

          public static <E> java.util.LinkedHashSet<E> newLinkedHashSet(java.lang.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 java.lang.Comparable> java.util.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 java.lang.Comparable> java.util.TreeSet<E> newTreeSet(java.lang.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> java.util.TreeSet<E> newTreeSet(java.util.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:
        `java.lang.NullPointerException` - if `comparator` is null

    - #### newIdentityHashSet

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

      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.
      Since:
        8.0

    - #### newCopyOnWriteArraySet

          @GwtIncompatible(value="CopyOnWriteArraySet")
          public static <E> java.util.concurrent.CopyOnWriteArraySet<E> newCopyOnWriteArraySet()

      Creates an empty `CopyOnWriteArraySet` instance.

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

      Returns:
        a new, empty `CopyOnWriteArraySet`
      Since:
        12.0

    - #### newCopyOnWriteArraySet

          @GwtIncompatible(value="CopyOnWriteArraySet")
          public static <E> java.util.concurrent.CopyOnWriteArraySet<E> newCopyOnWriteArraySet(java.lang.Iterable<? extends E> elements)

      Creates a `CopyOnWriteArraySet` instance containing the given elements.
      Parameters:
        `elements` - the elements that the set should contain, in order
      Returns:
        a new `CopyOnWriteArraySet` containing those elements
      Since:
        12.0

    - #### 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<E>)`. 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<E>)`, 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

          @Deprecated
          public static <E> java.util.Set<E> newSetFromMap(java.util.Map<E,java.lang.Boolean> map)

      Deprecated. Use `Collections.newSetFromMap(java.util.Map<E, java.lang.Boolean>)` instead. This method will be removed in August 2017.
      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>());

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

      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.

      Further, note that the current implementation is not suitable for nested `union` views, i.e. the following should be avoided when in a loop: `union = Sets.union(union, anotherSet);`, since iterating over the resulting set has a cubic complexity to the depth of the nesting.

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

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

    - #### symmetricDifference

          public static <E> Sets.SetView<E> symmetricDifference(java.util.Set<? extends E> set1,
                                                java.util.Set<? extends E> set2)

      Returns an unmodifiable view of the symmetric difference of two sets. The returned set contains all elements that are contained in either `set1` or `set2` but not in both. The iteration order of the returned set is undefined.

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

      Since:
        3.0

    - #### filter

          @CheckReturnValue
          public static <E> java.util.Set<E> filter(java.util.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. When given an element that doesn't satisfy the predicate, the set's `add()` and `addAll()` methods throw an `IllegalArgumentException`. 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 set.

      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.

      Warning: `predicate` must be consistent with equals, as documented at `Predicate.apply(T)`. Do not provide a predicate such as `Predicates.instanceOf(ArrayList.class)`, which is inconsistent with equals. (See `Iterables.filter(Iterable, Class)` for related functionality.)

    - #### filter

          @CheckReturnValue
          public static <E> java.util.SortedSet<E> filter(java.util.SortedSet<E> unfiltered,
                                                           Predicate<? super E> predicate)

      Returns the elements of a `SortedSet`, `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. When given an element that doesn't satisfy the predicate, the set's `add()` and `addAll()` methods throw an `IllegalArgumentException`. 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 set.

      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.

      Warning: `predicate` must be consistent with equals, as documented at `Predicate.apply(T)`. Do not provide a predicate such as `Predicates.instanceOf(ArrayList.class)`, which is inconsistent with equals. (See `Iterables.filter(Iterable, Class)` for related functionality.)

      Since:
        11.0

    - #### filter

          @GwtIncompatible(value="NavigableSet")
          @CheckReturnValue
          public static <E> java.util.NavigableSet<E> filter(java.util.NavigableSet<E> unfiltered,
                                                                                   Predicate<? super E> predicate)

      Returns the elements of a `NavigableSet`, `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. When given an element that doesn't satisfy the predicate, the set's `add()` and `addAll()` methods throw an `IllegalArgumentException`. 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 set.

      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.

      Warning: `predicate` must be consistent with equals, as documented at `Predicate.apply(T)`. Do not provide a predicate such as `Predicates.instanceOf(ArrayList.class)`, which is inconsistent with equals. (See `Iterables.filter(Iterable, Class)` for related functionality.)

      Since:
        14.0

    - #### cartesianProduct

          public static <B> java.util.Set<java.util.List<B>> cartesianProduct(java.util.List<? extends java.util.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:

             Sets.cartesianProduct(ImmutableList.of(
                 ImmutableSet.of(1, 2),
                 ImmutableSet.of("A", "B", "C")))

      returns a set containing six lists:

      - `ImmutableList.of(1, "A")`
      - `ImmutableList.of(1, "B")`
      - `ImmutableList.of(1, "C")`
      - `ImmutableList.of(2, "A")`
      - `ImmutableList.of(2, "B")`
      - `ImmutableList.of(2, "C")`

      The result is guaranteed to be in the "traditional", lexicographical order for Cartesian products that you would get from nesting for loops:

             for (B b0 : sets.get(0)) {
               for (B b1 : sets.get(1)) {
                 ...
                 ImmutableList<B> tuple = ImmutableList.of(b0, b1, ...);
                 // operate on tuple
               }
             }

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

      Performance notes: while the cartesian product of sets of size `m, n, p` is a set of size `m x n x p`, its actual memory consumption is much smaller. When the cartesian set is constructed, the input sets are merely copied. Only as the resulting set is iterated are the individual lists created, and these are not retained after iteration.

      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:
        `java.lang.NullPointerException` - if `sets`, any one of the `sets`, or any element of a provided set is null
      Since:
        2.0

    - #### cartesianProduct

          public static <B> java.util.Set<java.util.List<B>> cartesianProduct(java.util.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:

             Sets.cartesianProduct(
                 ImmutableSet.of(1, 2),
                 ImmutableSet.of("A", "B", "C"))

      returns a set containing six lists:

      - `ImmutableList.of(1, "A")`
      - `ImmutableList.of(1, "B")`
      - `ImmutableList.of(1, "C")`
      - `ImmutableList.of(2, "A")`
      - `ImmutableList.of(2, "B")`
      - `ImmutableList.of(2, "C")`

      The result is guaranteed to be in the "traditional", lexicographical order for Cartesian products that you would get from nesting for loops:

             for (B b0 : sets.get(0)) {
               for (B b1 : sets.get(1)) {
                 ...
                 ImmutableList<B> tuple = ImmutableList.of(b0, b1, ...);
                 // operate on tuple
               }
             }

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

      Performance notes: while the cartesian product of sets of size `m, n, p` is a set of size `m x n x p`, its actual memory consumption is much smaller. When the cartesian set is constructed, the input sets are merely copied. Only as the resulting set is iterated are the individual lists created, and these are not retained after iteration.

      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:
        `java.lang.NullPointerException` - if `sets`, any one of the `sets`, or any element of a provided set is null
      Since:
        2.0

    - #### powerSet

          @GwtCompatible(serializable=false)
          public static <E> java.util.Set<java.util.Set<E>> powerSet(java.util.Set<E> set)

      Returns the set of all possible subsets of `set`. For example, `powerSet(ImmutableSet.of(1, 2))` returns the set `{{}, {1}, {2}, {1, 2}}`.

      Elements appear in these subsets in the same iteration order as they appeared in the input set. The order in which these subsets appear in the outer set is undefined. Note that the power set of the empty set is not the empty set, but a one-element set containing the empty set.

      The returned set and its constituent sets use `equals` to decide whether two elements are identical, even if the input set uses a different concept of equivalence.

      Performance notes: while the power set of a set with size `n` is of size `2^n`, its memory usage is only `O(n)`. When the power set is constructed, the input set is merely copied. Only as the power set is iterated are the individual subsets created, and these subsets themselves occupy only a small constant amount of memory.

      Parameters:
        `set` - the set of elements to construct a power set from
      Returns:
        the power set, as an immutable set of immutable sets
      Throws:
        `java.lang.IllegalArgumentException` - if `set` has more than 30 unique elements (causing the power set size to exceed the `int` range)
        `java.lang.NullPointerException` - if `set` is or contains `null`
      Since:
        4.0
      See Also:
        Power set article at Wikipedia

    - #### unmodifiableNavigableSet

          @GwtIncompatible(value="NavigableSet")
          public static <E> java.util.NavigableSet<E> unmodifiableNavigableSet(java.util.NavigableSet<E> set)

      Returns an unmodifiable view of the specified navigable set. This method allows modules to provide users with "read-only" access to internal navigable sets. Query operations on the returned set "read through" to the specified set, and attempts to modify the returned set, whether direct or via its collection views, result in an `UnsupportedOperationException`.

      The returned navigable set will be serializable if the specified navigable set is serializable.

      Parameters:
        `set` - the navigable set for which an unmodifiable view is to be returned
      Returns:
        an unmodifiable view of the specified navigable set
      Since:
        12.0

    - #### synchronizedNavigableSet

          @GwtIncompatible(value="NavigableSet")
          public static <E> java.util.NavigableSet<E> synchronizedNavigableSet(java.util.NavigableSet<E> navigableSet)

      Returns a synchronized (thread-safe) navigable set backed by the specified navigable set. In order to guarantee serial access, it is critical that all access to the backing navigable set is accomplished through the returned navigable set (or its views).

      It is imperative that the user manually synchronize on the returned sorted set when iterating over it or any of its `descendingSet`, `subSet`, `headSet`, or `tailSet` views.

             NavigableSet<E> set = synchronizedNavigableSet(new TreeSet<E>());
              ...
             synchronized (set) {
               // Must be in the synchronized block
               Iterator<E> it = set.iterator();
               while (it.hasNext()) {
                 foo(it.next());
               }
             }

      or:

             NavigableSet<E> set = synchronizedNavigableSet(new TreeSet<E>());
             NavigableSet<E> set2 = set.descendingSet().headSet(foo);
              ...
             synchronized (set) { // Note: set, not set2!!!
               // Must be in the synchronized block
               Iterator<E> it = set2.descendingIterator();
               while (it.hasNext())
                 foo(it.next());
               }
             }

      Failure to follow this advice may result in non-deterministic behavior.

      The returned navigable set will be serializable if the specified navigable set is serializable.

      Parameters:
        `navigableSet` - the navigable set to be "wrapped" in a synchronized navigable set.
      Returns:
        a synchronized view of the specified navigable set.
      Since:
        13.0