Modifier and Type | Class and Description |
---|---|
static class |
Sets
An unmodifiable view of a set which may be backed by other sets; this view will change as the backing sets do.
|
Modifier and Type | Method and Description |
---|---|
static <B> Set |
cartesianProduct(List
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> Set |
cartesianProduct(Set
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 Enum |
complementOf(Collection
Creates an
EnumSet consisting of all enum values that are not in the specified collection.
|
static <E extends Enum |
complementOf(Collection
Creates an
EnumSet consisting of all enum values that are not in the specified collection.
|
static <E> Sets |
difference(Set
Returns an unmodifiable
view of the difference of two sets.
|
static <E> NavigableSet |
filter(NavigableSet
Returns the elements of a
NavigableSet ,
unfiltered , that satisfy a predicate.
|
static <E> Set |
filter(Set
Returns the elements of
unfiltered that satisfy a predicate.
|
static <E> SortedSet |
filter(SortedSet
Returns the elements of a
SortedSet ,
unfiltered , that satisfy a predicate.
|
static <E extends Enum |
immutableEnumSet(E anElement, E... otherElements)
Returns an immutable set instance containing the given enum elements.
|
static <E extends Enum |
immutableEnumSet(Iterable
Returns an immutable set instance containing the given enum elements.
|
static <E> Sets |
intersection(Set
Returns an unmodifiable
view of the intersection of two sets.
|
static <E> Set |
newConcurrentHashSet()
Creates a thread-safe set backed by a hash map.
|
static <E> Set |
newConcurrentHashSet(Iterable
Creates a thread-safe set backed by a hash map and containing the given elements.
|
static <E> CopyOnWriteArraySet |
newCopyOnWriteArraySet()
Creates an empty
CopyOnWriteArraySet instance.
|
static <E> CopyOnWriteArraySet |
newCopyOnWriteArraySet(Iterable
Creates a
CopyOnWriteArraySet instance containing the given elements.
|
static <E extends Enum |
newEnumSet(Iterable
Returns a new,
mutable
EnumSet instance containing the given elements in their natural order.
|
static <E> HashSet |
newHashSet()
Creates a
mutable, initially empty
HashSet instance.
|
static <E> HashSet |
newHashSet(E... elements)
Creates a
mutable
HashSet instance initially containing the given elements.
|
static <E> HashSet |
newHashSet(Iterable
Creates a
mutable
HashSet instance containing the given elements.
|
static <E> HashSet |
newHashSet(Iterator
Creates a
mutable
HashSet instance containing the given elements.
|
static <E> HashSet |
newHashSetWithExpectedSize(int expectedSize)
Creates a
HashSet instance, with a high enough initial table size that it
should hold
expectedSize elements without resizing.
|
static <E> Set |
newIdentityHashSet()
Creates an empty
Set that uses identity to determine equality.
|
static <E> LinkedHashSet |
newLinkedHashSet()
Creates a
mutable, empty
LinkedHashSet instance.
|
static <E> LinkedHashSet |
newLinkedHashSet(Iterable
Creates a
mutable
LinkedHashSet instance containing the given elements in order.
|
static <E> LinkedHashSet |
newLinkedHashSetWithExpectedSize(int expectedSize)
Creates a
LinkedHashSet instance, with a high enough "initial capacity" that it
should hold
expectedSize elements without growth.
|
static <E> Set |
newSetFromMap(Map
Deprecated.
Use
Collections instead. This method will be removed in August 2017.
|
static <E extends Comparable |
newTreeSet()
Creates a
mutable, empty
TreeSet instance sorted by the natural sort ordering of its elements.
|
static <E> TreeSet |
newTreeSet(Comparator
Creates a
mutable, empty
TreeSet instance with the given comparator.
|
static <E extends Comparable |
newTreeSet(Iterable
Creates a
mutable
TreeSet instance containing the given elements sorted by their natural ordering.
|
static <E> Set |
powerSet(Set
Returns the set of all possible subsets of
set .
|
static <E> Sets |
symmetricDifference(Set
Returns an unmodifiable
view of the symmetric difference of two sets.
|
static <E> NavigableSet |
synchronizedNavigableSet(NavigableSet
Returns a synchronized (thread-safe) navigable set backed by the specified navigable set.
|
static <E> Sets |
union(Set
Returns an unmodifiable
view of the union of two sets.
|
static <E> NavigableSet |
unmodifiableNavigableSet(NavigableSet
Returns an unmodifiable view of the specified navigable set.
|
@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 contain
otherElements
- 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 in their natural order. This method behaves identically to
EnumSet.copyOf(Collection)
, but also accepts non-
Collection
iterables and empty iterables.
public static <E> HashSet<E> newHashSet()
HashSet
instance.
Note: if mutability is not required, use ImmutableSet
instead. If E
is an Enum
type, use EnumSet
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.
public static <E> HashSet<E> newHashSet(E... elements)
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
or ImmutableSet
instead. If E
is an Enum
type, use EnumSet
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
. This method is not actually very useful and will likely be deprecated in the future.
public static <E> HashSet<E> newHashSetWithExpectedSize(int expectedSize)
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.
expectedSize
- the number of elements you expect to add to the returned set
HashSet
with enough capacity to hold
expectedSize
elements without resizing
IllegalArgumentException
- if
expectedSize
is negative
public static <E> HashSet<E> newHashSet(Iterable <? extends E> elements)
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
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.
public static <E> HashSet<E> newHashSet(Iterator <? extends E> elements)
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
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.
public static <E> Set<E> newConcurrentHashSet()
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.
Set
public static <E> Set<E> newConcurrentHashSet(Iterable <? extends E> elements)
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.
elements
- the elements that the set should contain
NullPointerException
- if
elements
or any of its contents is null
public static <E> LinkedHashSet<E> newLinkedHashSet()
LinkedHashSet
instance.
Note: if mutability is not required, use ImmutableSet
instead.
LinkedHashSet
public static <E> LinkedHashSet<E> newLinkedHashSetWithExpectedSize(int expectedSize)
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.
expectedSize
- the number of elements you expect to add to the returned set
LinkedHashSet
with enough capacity to hold
expectedSize
elements without resizing
IllegalArgumentException
- if
expectedSize
is negative
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
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
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
instead.
Note: If elements
is a SortedSet
with an explicit comparator, this method has different behavior than TreeSet
, 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 null
public 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.
@GwtIncompatible(value="CopyOnWriteArraySet") public static <E> CopyOnWriteArraySet<E> newCopyOnWriteArraySet()
CopyOnWriteArraySet
instance.
Note: if you need an immutable empty Set
, use Collections
instead.
CopyOnWriteArraySet
@GwtIncompatible(value="CopyOnWriteArraySet") public static <E> CopyOnWriteArraySet<E> newCopyOnWriteArraySet(Iterable <? extends E> elements)
CopyOnWriteArraySet
instance containing the given elements.
elements
- the elements that the set should contain, in order
CopyOnWriteArraySet
containing those elements
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<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.
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 elements
public 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<E>)
, 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 collection
@Deprecated public static <E> Set<E> newSetFromMap(Map <E ,Boolean > map)
Collections.newSetFromMap(java.util.Map<E, java.lang.Boolean>)
instead. This method will be removed in August 2017.
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.
map
- the backing map
IllegalArgumentException
- if
map
is not empty
public 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
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.
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
. Do not provide a predicate such as Predicates.instanceOf(ArrayList.class)
, which is inconsistent with equals. (See Iterables
for related functionality.)
public static <E> SortedSet<E> filter(SortedSet <E> unfiltered, Predicate <? super E> predicate)
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
. Do not provide a predicate such as Predicates.instanceOf(ArrayList.class)
, which is inconsistent with equals. (See Iterables
for related functionality.)
@GwtIncompatible(value="NavigableSet") public static <E> NavigableSet<E> filter(NavigableSet <E> unfiltered, Predicate <? super E> predicate)
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
. Do not provide a predicate such as Predicates.instanceOf(ArrayList.class)
, which is inconsistent with equals. (See Iterables
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")
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.
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
public 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")
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.
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 small constant amount of memory.
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
is or contains
null
@GwtIncompatible(value="NavigableSet") public static <E> NavigableSet<E> unmodifiableNavigableSet(NavigableSet <E> set)
UnsupportedOperationException
.
The returned navigable set will be serializable if the specified navigable set is serializable.
set
- the navigable set for which an unmodifiable view is to be returned
@GwtIncompatible(value="NavigableSet") public static <E> NavigableSet<E> synchronizedNavigableSet(NavigableSet <E> navigableSet)
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.
navigableSet
- the navigable set to be "wrapped" in a synchronized navigable set.