|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object com.google.common.collect.Sets
@GwtCompatible(emulated=true) public final class Sets
Static utility methods pertaining to Set
instances. Also see this
class's counterparts Lists
and Maps
.
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
|
cartesianProduct(List<? extends 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
|
cartesianProduct(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
|
complementOf(Collection<E> collection)
Creates an EnumSet consisting of all enum values that are not in
the specified collection. |
|
static
|
complementOf(Collection<E> collection,
Class<E> type)
Creates an EnumSet consisting of all enum values that are not in
the specified collection. |
|
static
|
difference(Set<E> set1,
Set<?> set2)
Returns an unmodifiable view of the difference of two sets. |
|
static
|
filter(Set<E> unfiltered,
Predicate<? super E> predicate)
Returns the elements of unfiltered that satisfy a predicate. |
|
static
|
immutableEnumSet(E anElement,
E... otherElements)
Returns an immutable set instance containing the given enum elements. |
|
static
|
immutableEnumSet(Iterable<E> elements)
Returns an immutable set instance containing the given enum elements. |
|
static
|
intersection(Set<E> set1,
Set<?> set2)
Returns an unmodifiable view of the intersection of two sets. |
|
static
|
newEnumSet(Iterable<E> iterable,
Class<E> elementType)
Returns a new EnumSet instance containing the given elements. |
|
static
|
newHashSet()
Creates a mutable, empty HashSet instance. |
|
static
|
newHashSet(E... elements)
Creates a mutable HashSet instance containing the given
elements in unspecified order. |
|
static
|
newHashSet(Iterable<? extends E> elements)
Creates a mutable HashSet instance containing the given
elements in unspecified order. |
|
static
|
newHashSet(Iterator<? extends E> elements)
Creates a mutable HashSet instance containing the given
elements in unspecified order. |
|
static
|
newHashSetWithExpectedSize(int expectedSize)
Creates an empty HashSet instance with enough capacity to hold the
specified number of elements without rehashing. |
|
static
|
newIdentityHashSet()
Creates an empty Set that uses identity to determine equality. |
|
static
|
newLinkedHashSet()
Creates a mutable, empty LinkedHashSet instance. |
|
static
|
newLinkedHashSet(Iterable<? extends E> elements)
Creates a mutable LinkedHashSet instance containing the
given elements in order. |
|
static
|
newSetFromMap(Map<E,Boolean> map)
Returns a set backed by the specified map. |
|
static
|
newTreeSet()
Creates a mutable, empty TreeSet instance sorted by the
natural sort ordering of its elements. |
|
static
|
newTreeSet(Comparator<? super E> comparator)
Creates a mutable, empty TreeSet instance with the given
comparator. |
|
static
|
newTreeSet(Iterable<? extends E> elements)
Creates a mutable TreeSet instance containing the given
elements sorted by their natural ordering. |
|
static
|
powerSet(Set<E> set)
Returns the set of all possible subsets of set . |
|
static
|
symmetricDifference(Set<? extends E> set1,
Set<? extends E> set2)
Returns an unmodifiable view of the symmetric difference of two sets. |
|
static
|
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 |
---|
@GwtCompatible(serializable=true) public static <E extends Enum<E>> ImmutableSet<E> immutableEnumSet(E anElement, E... otherElements)
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.
anElement
- one of the elements the set should containotherElements
- the rest of the elements the set should contain
@GwtCompatible(serializable=true) public static <E extends Enum<E>> ImmutableSet<E> immutableEnumSet(Iterable<E> elements)
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.
elements
- the elements, all of the same enum
type, that the
set should contain
public static <E extends Enum<E>> EnumSet<E> newEnumSet(Iterable<E> iterable, Class<E> elementType)
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
.
public static <E> HashSet<E> newHashSet()
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.
HashSet
public static <E> HashSet<E> newHashSet(E... elements)
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.
elements
- the elements that the set should contain
HashSet
containing those elements (minus duplicates)public static <E> HashSet<E> newHashSetWithExpectedSize(int expectedSize)
HashSet
instance with enough capacity to hold the
specified number of elements without rehashing.
expectedSize
- the expected size
HashSet
with enough capacity to hold expectedSize
elements without rehashing
IllegalArgumentException
- if expectedSize
is negativepublic static <E> HashSet<E> newHashSet(Iterable<? extends E> elements)
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.
elements
- the elements that the set should contain
HashSet
containing those elements (minus duplicates)public static <E> HashSet<E> newHashSet(Iterator<? extends E> elements)
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.
elements
- the elements that the set should contain
HashSet
containing those elements (minus duplicates)public static <E> LinkedHashSet<E> newLinkedHashSet()
LinkedHashSet
instance.
Note: if mutability is not required, use ImmutableSet.of()
instead.
LinkedHashSet
public static <E> LinkedHashSet<E> newLinkedHashSet(Iterable<? extends E> elements)
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.
elements
- the elements that the set should contain, in order
LinkedHashSet
containing those elements (minus
duplicates)public static <E extends Comparable> TreeSet<E> newTreeSet()
TreeSet
instance sorted by the
natural sort ordering of its elements.
Note: if mutability is not required, use ImmutableSortedSet.of()
instead.
TreeSet
public static <E extends Comparable> TreeSet<E> newTreeSet(Iterable<? extends E> elements)
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.
elements
- the elements that the set should contain
TreeSet
containing those elements (minus duplicates)public static <E> TreeSet<E> newTreeSet(Comparator<? super E> comparator)
TreeSet
instance with the given
comparator.
Note: if mutability is not required, use ImmutableSortedSet.orderedBy(comparator).build()
instead.
comparator
- the comparator to use to sort the set
TreeSet
NullPointerException
- if comparator
is nullpublic static <E> Set<E> newIdentityHashSet()
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.
public static <E extends Enum<E>> EnumSet<E> complementOf(Collection<E> collection)
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.
collection
- the collection whose complement should be stored in the
enum set
EnumSet
containing all values of the enum
that aren't present in the given collection
IllegalArgumentException
- if collection
is not an
EnumSet
instance and contains no elementspublic static <E extends Enum<E>> EnumSet<E> complementOf(Collection<E> collection, Class<E> type)
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.
collection
- the collection whose complement should be stored in the
EnumSet
type
- the type of the elements in the set
EnumSet
initially containing all the
values of the enum not present in the given collectionpublic static <E> Set<E> newSetFromMap(Map<E,Boolean> map)
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.
map
- the backing map
IllegalArgumentException
- if map is not emptypublic static <E> Sets.SetView<E> union(Set<? extends E> set1, Set<? extends E> set2)
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.
public static <E> Sets.SetView<E> intersection(Set<E> set1, Set<?> set2)
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.
public static <E> Sets.SetView<E> difference(Set<E> set1, Set<?> set2)
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).
public static <E> Sets.SetView<E> symmetricDifference(Set<? extends E> set1, Set<? extends E> set2)
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).
public static <E> Set<E> filter(Set<E> unfiltered, Predicate<? super E> predicate)
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.)
public static <B> Set<List<B>> cartesianProduct(List<? extends Set<? extends B>> sets)
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")
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.
B
- any common base class shared by all axes (often just Object
)sets
- the sets to choose elements from, in the order that
the elements chosen from those sets should appear in the resulting
lists
NullPointerException
- if sets
, any one of the sets
,
or any element of a provided set is nullpublic static <B> Set<List<B>> cartesianProduct(Set<? extends B>... sets)
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")
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.
B
- any common base class shared by all axes (often just Object
)sets
- the sets to choose elements from, in the order that
the elements chosen from those sets should appear in the resulting
lists
NullPointerException
- if sets
, any one of the sets
,
or any element of a provided set is null@GwtCompatible(serializable=false) public static <E> Set<Set<E>> powerSet(Set<E> set)
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 few bytes of memory regardless of their size.
set
- the set of elements to construct a power set from
IllegalArgumentException
- if set
has more than 30 unique
elements (causing the power set size to exceed the int
range)
NullPointerException
- if set
or any of its elements is
null
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |