Package com.google.common.collect

Class 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 (imported from Google Collections Library)

    • Nested Class Summary

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

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method 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 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 a mutable, empty HashSet instance.
      static <E> java.util.HashSet<E> newHashSet​(E... elements)
      Creates a mutable HashSet instance containing the given elements in unspecified order.
      static <E> java.util.HashSet<E> newHashSet​(java.lang.Iterable<? extends E> elements)
      Creates a mutable HashSet instance containing the given elements in unspecified order.
      static <E> java.util.HashSet<E> newHashSet​(java.util.Iterator<? extends E> elements)
      Creates a mutable HashSet instance containing the given elements in unspecified order.
      static <E> java.util.HashSet<E> newHashSetWithExpectedSize​(int expectedSize)
      Creates a HashSet instance, with a high enough "initial capacity" that it should hold expectedSize elements without growth.
      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)
      Returns a set backed by the specified map.
      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 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.TreeSet<E> newTreeSet​(java.util.Comparator<? super E> comparator)
      Creates a mutable, empty TreeSet instance with the given comparator.
      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 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 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<E>) instead.

        Returns:
        a new, empty HashSet

      • newHashSet

        public static <E> java.util.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 an overload of ImmutableSet.of() (for varargs) or ImmutableSet.copyOf(Object[]) (for an array) 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> java.util.HashSet<E> newHashSetWithExpectedSize​(int expectedSize)
        Creates a HashSet 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 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 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> java.util.HashSet<E> newHashSet​(java.util.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> 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(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

      • 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

        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: 

         {
        @code

        Set identityHashSet = Sets.newSetFromMap(new IdentityHashMap());
 }
 

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

 
          
 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
          

          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
          

          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("NavigableSet")
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("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("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
          

          

          •