com.google.common.collect.Sets Maven / Gradle / Ivy
Show all versions of guava Show documentation
/*
* Copyright (C) 2007 The Guava Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.google.common.collect;
import static com.google.common.base.Preconditions.checkArgument;
import static com.google.common.base.Preconditions.checkNotNull;
import static com.google.common.collect.CollectPreconditions.checkNonnegative;
import com.google.common.annotations.Beta;
import com.google.common.annotations.GwtCompatible;
import com.google.common.annotations.GwtIncompatible;
import com.google.common.base.Predicate;
import com.google.common.base.Predicates;
import com.google.common.collect.Collections2.FilteredCollection;
import com.google.common.math.IntMath;
import com.google.errorprone.annotations.CanIgnoreReturnValue;
import java.io.Serializable;
import java.util.AbstractSet;
import java.util.Arrays;
import java.util.BitSet;
import java.util.Collection;
import java.util.Collections;
import java.util.Comparator;
import java.util.EnumSet;
import java.util.HashSet;
import java.util.Iterator;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.NavigableSet;
import java.util.NoSuchElementException;
import java.util.Set;
import java.util.SortedSet;
import java.util.TreeSet;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.CopyOnWriteArraySet;
import java.util.function.Consumer;
import java.util.stream.Collector;
import java.util.stream.Stream;
import org.checkerframework.checker.nullness.qual.Nullable;
/**
* Static utility methods pertaining to {@link Set} instances. Also see this class's counterparts
* {@link Lists}, {@link Maps} and {@link Queues}.
*
* See the Guava User Guide article on {@code Sets}.
*
* @author Kevin Bourrillion
* @author Jared Levy
* @author Chris Povirk
* @since 2.0
*/
@GwtCompatible(emulated = true)
public final class Sets {
private Sets() {}
/**
* {@link AbstractSet} substitute without the potentially-quadratic {@code removeAll}
* implementation.
*/
abstract static class ImprovedAbstractSet extends AbstractSet {
@Override
public boolean removeAll(Collection c) {
return removeAllImpl(this, c);
}
@Override
public boolean retainAll(Collection c) {
return super.retainAll(checkNotNull(c)); // GWT compatibility
}
}
/**
* Returns an immutable set instance containing the given enum elements. Internally, the returned
* set will be backed by an {@link 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.
*
* @param anElement one of the elements the set should contain
* @param otherElements the rest of the elements the set should contain
* @return an immutable set containing those elements, minus duplicates
*/
// http://code.google.com/p/google-web-toolkit/issues/detail?id=3028
@GwtCompatible(serializable = true)
public static > ImmutableSet immutableEnumSet(
E anElement, E... otherElements) {
return ImmutableEnumSet.asImmutable(EnumSet.of(anElement, otherElements));
}
/**
* Returns an immutable set instance containing the given enum elements. Internally, the returned
* set will be backed by an {@link 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.
*
* @param elements the elements, all of the same {@code enum} type, that the set should contain
* @return an immutable set containing those elements, minus duplicates
*/
// http://code.google.com/p/google-web-toolkit/issues/detail?id=3028
@GwtCompatible(serializable = true)
public static > ImmutableSet immutableEnumSet(Iterable elements) {
if (elements instanceof ImmutableEnumSet) {
return (ImmutableEnumSet) elements;
} else if (elements instanceof Collection) {
Collection collection = (Collection) elements;
if (collection.isEmpty()) {
return ImmutableSet.of();
} else {
return ImmutableEnumSet.asImmutable(EnumSet.copyOf(collection));
}
} else {
Iterator itr = elements.iterator();
if (itr.hasNext()) {
EnumSet enumSet = EnumSet.of(itr.next());
Iterators.addAll(enumSet, itr);
return ImmutableEnumSet.asImmutable(enumSet);
} else {
return ImmutableSet.of();
}
}
}
/**
* Returns a {@code Collector} that accumulates the input elements into a new {@code ImmutableSet}
* with an implementation specialized for enums. Unlike {@link ImmutableSet#toImmutableSet}, the
* resulting set will iterate over elements in their enum definition order, not encounter order.
*
* @since 21.0
*/
public static > Collector> toImmutableEnumSet() {
return CollectCollectors.toImmutableEnumSet();
}
/**
* Returns a new, mutable {@code EnumSet} instance containing the given elements in their
* natural order. This method behaves identically to {@link EnumSet#copyOf(Collection)}, but also
* accepts non-{@code Collection} iterables and empty iterables.
*/
public static > EnumSet newEnumSet(
Iterable iterable, Class elementType) {
EnumSet set = EnumSet.noneOf(elementType);
Iterables.addAll(set, iterable);
return set;
}
// HashSet
/**
* Creates a mutable, initially empty {@code HashSet} instance.
*
* Note: if mutability is not required, use {@link ImmutableSet#of()} instead. If {@code
* E} is an {@link Enum} type, use {@link EnumSet#noneOf} instead. Otherwise, strongly consider
* using a {@code 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 {@code HashSet} constructor directly, taking advantage of the new
* "diamond" syntax.
*/
public static HashSet newHashSet() {
return new HashSet();
}
/**
* Creates a mutable {@code HashSet} instance initially containing the given elements.
*
* Note: if elements are non-null and won't be added or removed after this point, use
* {@link ImmutableSet#of()} or {@link ImmutableSet#copyOf(Object[])} instead. If {@code E} is an
* {@link Enum} type, use {@link EnumSet#of(Enum, Enum[])} instead. Otherwise, strongly consider
* using a {@code LinkedHashSet} instead, at the cost of increased memory footprint, to get
* deterministic iteration behavior.
*
*
This method is just a small convenience, either for {@code newHashSet(}{@link Arrays#asList
* asList}{@code (...))}, or for creating an empty set then calling {@link Collections#addAll}.
* This method is not actually very useful and will likely be deprecated in the future.
*/
public static HashSet newHashSet(E... elements) {
HashSet set = newHashSetWithExpectedSize(elements.length);
Collections.addAll(set, elements);
return set;
}
/**
* Creates a mutable {@code HashSet} instance containing the given elements. A very thin
* convenience for creating an empty set then calling {@link Collection#addAll} or {@link
* Iterables#addAll}.
*
* Note: if mutability is not required and the elements are non-null, use {@link
* ImmutableSet#copyOf(Iterable)} instead. (Or, change {@code elements} to be a {@link
* FluentIterable} and call {@code elements.toSet()}.)
*
*
Note: if {@code E} is an {@link Enum} type, use {@link #newEnumSet(Iterable, Class)}
* instead.
*
*
Note for Java 7 and later: if {@code elements} is a {@link Collection}, you don't
* need this method. Instead, use the {@code 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 HashSet newHashSet(Iterable elements) {
return (elements instanceof Collection)
? new HashSet((Collection) elements)
: newHashSet(elements.iterator());
}
/**
* Creates a mutable {@code HashSet} instance containing the given elements. A very thin
* convenience for creating an empty set and then calling {@link Iterators#addAll}.
*
* Note: if mutability is not required and the elements are non-null, use {@link
* ImmutableSet#copyOf(Iterator)} instead.
*
*
Note: if {@code E} is an {@link Enum} type, you should create an {@link EnumSet}
* instead.
*
*
Overall, this method is not very useful and will likely be deprecated in the future.
*/
public static HashSet newHashSet(Iterator elements) {
HashSet set = newHashSet();
Iterators.addAll(set, elements);
return set;
}
/**
* Returns a new hash set using the smallest initial table size that can hold {@code expectedSize}
* elements without resizing. Note that this is not what {@link HashSet#HashSet(int)} does, but it
* is what most users want and expect it to do.
*
* This behavior can't be broadly guaranteed, but has been tested with OpenJDK 1.7 and 1.8.
*
* @param expectedSize the number of elements you expect to add to the returned set
* @return a new, empty hash set with enough capacity to hold {@code expectedSize} elements
* without resizing
* @throws IllegalArgumentException if {@code expectedSize} is negative
*/
public static HashSet newHashSetWithExpectedSize(int expectedSize) {
return new HashSet(Maps.capacity(expectedSize));
}
/**
* Creates a thread-safe set backed by a hash map. The set is backed by a {@link
* ConcurrentHashMap} instance, and thus carries the same concurrency guarantees.
*
* Unlike {@code HashSet}, this class does NOT allow {@code null} to be used as an element. The
* set is serializable.
*
* @return a new, empty thread-safe {@code Set}
* @since 15.0
*/
public static Set newConcurrentHashSet() {
return Collections.newSetFromMap(new ConcurrentHashMap());
}
/**
* Creates a thread-safe set backed by a hash map and containing the given elements. The set is
* backed by a {@link ConcurrentHashMap} instance, and thus carries the same concurrency
* guarantees.
*
* Unlike {@code HashSet}, this class does NOT allow {@code null} to be used as an element. The
* set is serializable.
*
* @param elements the elements that the set should contain
* @return a new thread-safe set containing those elements (minus duplicates)
* @throws NullPointerException if {@code elements} or any of its contents is null
* @since 15.0
*/
public static Set newConcurrentHashSet(Iterable elements) {
Set set = newConcurrentHashSet();
Iterables.addAll(set, elements);
return set;
}
// LinkedHashSet
/**
* Creates a mutable, empty {@code LinkedHashSet} instance.
*
* Note: if mutability is not required, use {@link ImmutableSet#of()} instead.
*
*
Note for Java 7 and later: this method is now unnecessary and should be treated as
* deprecated. Instead, use the {@code LinkedHashSet} constructor directly, taking advantage of
* the new "diamond" syntax.
*
* @return a new, empty {@code LinkedHashSet}
*/
public static LinkedHashSet newLinkedHashSet() {
return new LinkedHashSet();
}
/**
* Creates a mutable {@code LinkedHashSet} instance containing the given elements in order.
*
* Note: if mutability is not required and the elements are non-null, use {@link
* ImmutableSet#copyOf(Iterable)} instead.
*
*
Note for Java 7 and later: if {@code elements} is a {@link Collection}, you don't
* need this method. Instead, use the {@code LinkedHashSet} constructor directly, taking advantage
* of the new "diamond" syntax.
*
*
Overall, this method is not very useful and will likely be deprecated in the future.
*
* @param elements the elements that the set should contain, in order
* @return a new {@code LinkedHashSet} containing those elements (minus duplicates)
*/
public static LinkedHashSet newLinkedHashSet(Iterable elements) {
if (elements instanceof Collection) {
return new LinkedHashSet((Collection) elements);
}
LinkedHashSet set = newLinkedHashSet();
Iterables.addAll(set, elements);
return set;
}
/**
* Creates a {@code LinkedHashSet} instance, with a high enough "initial capacity" that it
* should hold {@code expectedSize} elements without growth. 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.
*
* @param expectedSize the number of elements you expect to add to the returned set
* @return a new, empty {@code LinkedHashSet} with enough capacity to hold {@code expectedSize}
* elements without resizing
* @throws IllegalArgumentException if {@code expectedSize} is negative
* @since 11.0
*/
public static LinkedHashSet newLinkedHashSetWithExpectedSize(int expectedSize) {
return new LinkedHashSet(Maps.capacity(expectedSize));
}
// TreeSet
/**
* Creates a mutable, empty {@code TreeSet} instance sorted by the natural sort ordering of
* its elements.
*
* Note: if mutability is not required, use {@link ImmutableSortedSet#of()} instead.
*
*
Note for Java 7 and later: this method is now unnecessary and should be treated as
* deprecated. Instead, use the {@code TreeSet} constructor directly, taking advantage of the new
* "diamond" syntax.
*
* @return a new, empty {@code TreeSet}
*/
public static TreeSet newTreeSet() {
return new TreeSet();
}
/**
* Creates a mutable {@code TreeSet} instance containing the given elements sorted by their
* natural ordering.
*
* Note: if mutability is not required, use {@link ImmutableSortedSet#copyOf(Iterable)}
* instead.
*
*
Note: If {@code elements} is a {@code SortedSet} with an explicit comparator, this
* method has different behavior than {@link TreeSet#TreeSet(SortedSet)}, which returns a {@code
* TreeSet} with that comparator.
*
*
Note for Java 7 and later: this method is now unnecessary and should be treated as
* deprecated. Instead, use the {@code TreeSet} constructor directly, taking advantage of the new
* "diamond" syntax.
*
*
This method is just a small convenience for creating an empty set and then calling {@link
* Iterables#addAll}. This method is not very useful and will likely be deprecated in the future.
*
* @param elements the elements that the set should contain
* @return a new {@code TreeSet} containing those elements (minus duplicates)
*/
public static TreeSet newTreeSet(Iterable elements) {
TreeSet set = newTreeSet();
Iterables.addAll(set, elements);
return set;
}
/**
* Creates a mutable, empty {@code TreeSet} instance with the given comparator.
*
* Note: if mutability is not required, use {@code
* ImmutableSortedSet.orderedBy(comparator).build()} instead.
*
*
Note for Java 7 and later: this method is now unnecessary and should be treated as
* deprecated. Instead, use the {@code TreeSet} constructor directly, taking advantage of the new
* "diamond" syntax. One caveat to this is that the {@code
* TreeSet} constructor uses a null {@code Comparator} to mean "natural ordering," whereas this
* factory rejects null. Clean your code accordingly.
*
* @param comparator the comparator to use to sort the set
* @return a new, empty {@code TreeSet}
* @throws NullPointerException if {@code comparator} is null
*/
public static TreeSet newTreeSet(Comparator comparator) {
return new TreeSet(checkNotNull(comparator));
}
/**
* Creates an empty {@code Set} that uses identity to determine equality. It compares object
* references, instead of calling {@code equals}, to determine whether a provided object matches
* an element in the set. For example, {@code contains} returns {@code false} when passed an
* object that equals a set member, but isn't the same instance. This behavior is similar to the
* way {@code IdentityHashMap} handles key lookups.
*
* @since 8.0
*/
public static Set newIdentityHashSet() {
return Collections.newSetFromMap(Maps.newIdentityHashMap());
}
/**
* Creates an empty {@code CopyOnWriteArraySet} instance.
*
* Note: if you need an immutable empty {@link Set}, use {@link Collections#emptySet}
* instead.
*
* @return a new, empty {@code CopyOnWriteArraySet}
* @since 12.0
*/
@GwtIncompatible // CopyOnWriteArraySet
public static CopyOnWriteArraySet newCopyOnWriteArraySet() {
return new CopyOnWriteArraySet();
}
/**
* Creates a {@code CopyOnWriteArraySet} instance containing the given elements.
*
* @param elements the elements that the set should contain, in order
* @return a new {@code CopyOnWriteArraySet} containing those elements
* @since 12.0
*/
@GwtIncompatible // CopyOnWriteArraySet
public static CopyOnWriteArraySet newCopyOnWriteArraySet(Iterable elements) {
// We copy elements to an ArrayList first, rather than incurring the
// quadratic cost of adding them to the COWAS directly.
Collection elementsCollection =
(elements instanceof Collection)
? (Collection) elements
: Lists.newArrayList(elements);
return new CopyOnWriteArraySet(elementsCollection);
}
/**
* Creates an {@code EnumSet} consisting of all enum values that are not in the specified
* collection. If the collection is an {@link EnumSet}, this method has the same behavior as
* {@link EnumSet#complementOf}. Otherwise, the specified collection must contain at least one
* element, in order to determine the element type. If the collection could be empty, use {@link
* #complementOf(Collection, Class)} instead of this method.
*
* @param collection the collection whose complement should be stored in the enum set
* @return a new, modifiable {@code EnumSet} containing all values of the enum that aren't present
* in the given collection
* @throws IllegalArgumentException if {@code collection} is not an {@code EnumSet} instance and
* contains no elements
*/
public static > EnumSet complementOf(Collection collection) {
if (collection instanceof EnumSet) {
return EnumSet.complementOf((EnumSet) collection);
}
checkArgument(
!collection.isEmpty(), "collection is empty; use the other version of this method");
Class type = collection.iterator().next().getDeclaringClass();
return makeComplementByHand(collection, type);
}
/**
* Creates an {@code EnumSet} consisting of all enum values that are not in the specified
* collection. This is equivalent to {@link EnumSet#complementOf}, but can act on any input
* collection, as long as the elements are of enum type.
*
* @param collection the collection whose complement should be stored in the {@code EnumSet}
* @param type the type of the elements in the set
* @return a new, modifiable {@code EnumSet} initially containing all the values of the enum not
* present in the given collection
*/
public static > EnumSet complementOf(
Collection collection, Class type) {
checkNotNull(collection);
return (collection instanceof EnumSet)
? EnumSet.complementOf((EnumSet) collection)
: makeComplementByHand(collection, type);
}
private static > EnumSet makeComplementByHand(
Collection collection, Class type) {
EnumSet result = EnumSet.allOf(type);
result.removeAll(collection);
return result;
}
/**
* 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 {@link Set} implementation corresponding to any {@link Map} implementation.
* There is no need to use this method on a {@link Map} implementation that already has a
* corresponding {@link Set} implementation (such as {@link java.util.HashMap} or {@link
* java.util.TreeMap}).
*
* Each method invocation on the set returned by this method results in exactly one method
* invocation on the backing map or its {@code keySet} view, with one exception. The {@code
* addAll} method is implemented as a sequence of {@code 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
*
* The returned set is serializable if the backing map is.
*
* @param map the backing map
* @return the set backed by the map
* @throws IllegalArgumentException if {@code map} is not empty
* @deprecated Use {@link Collections#newSetFromMap} instead.
*/
@Deprecated
public static Set newSetFromMap(Map map) {
return Collections.newSetFromMap(map);
}
/**
* An unmodifiable view of a set which may be backed by other sets; this view will change as the
* backing sets do. Contains methods to copy the data into a new set which will then remain
* stable. There is usually no reason to retain a reference of type {@code SetView}; typically,
* you either use it as a plain {@link Set}, or immediately invoke {@link #immutableCopy} or
* {@link #copyInto} and forget the {@code SetView} itself.
*
* @since 2.0
*/
public abstract static class SetView extends AbstractSet {
private SetView() {} // no subclasses but our own
/**
* Returns an immutable copy of the current contents of this set view. Does not support null
* elements.
*
* Warning: this may have unexpected results if a backing set of this view uses a
* nonstandard notion of equivalence, for example if it is a {@link TreeSet} using a comparator
* that is inconsistent with {@link Object#equals(Object)}.
*/
public ImmutableSet immutableCopy() {
return ImmutableSet.copyOf(this);
}
/**
* Copies the current contents of this set view into an existing set. This method has equivalent
* behavior to {@code set.addAll(this)}, assuming that all the sets involved are based on the
* same notion of equivalence.
*
* @return a reference to {@code set}, for convenience
*/
// Note: S should logically extend Set but can't due to either
// some javac bug or some weirdness in the spec, not sure which.
@CanIgnoreReturnValue
public > S copyInto(S set) {
set.addAll(this);
return set;
}
/**
* Guaranteed to throw an exception and leave the collection unmodified.
*
* @throws UnsupportedOperationException always
* @deprecated Unsupported operation.
*/
@CanIgnoreReturnValue
@Deprecated
@Override
public final boolean add(E e) {
throw new UnsupportedOperationException();
}
/**
* Guaranteed to throw an exception and leave the collection unmodified.
*
* @throws UnsupportedOperationException always
* @deprecated Unsupported operation.
*/
@CanIgnoreReturnValue
@Deprecated
@Override
public final boolean remove(Object object) {
throw new UnsupportedOperationException();
}
/**
* Guaranteed to throw an exception and leave the collection unmodified.
*
* @throws UnsupportedOperationException always
* @deprecated Unsupported operation.
*/
@CanIgnoreReturnValue
@Deprecated
@Override
public final boolean addAll(Collection newElements) {
throw new UnsupportedOperationException();
}
/**
* Guaranteed to throw an exception and leave the collection unmodified.
*
* @throws UnsupportedOperationException always
* @deprecated Unsupported operation.
*/
@CanIgnoreReturnValue
@Deprecated
@Override
public final boolean removeAll(Collection oldElements) {
throw new UnsupportedOperationException();
}
/**
* Guaranteed to throw an exception and leave the collection unmodified.
*
* @throws UnsupportedOperationException always
* @deprecated Unsupported operation.
*/
@CanIgnoreReturnValue
@Deprecated
@Override
public final boolean removeIf(java.util.function.Predicate filter) {
throw new UnsupportedOperationException();
}
/**
* Guaranteed to throw an exception and leave the collection unmodified.
*
* @throws UnsupportedOperationException always
* @deprecated Unsupported operation.
*/
@CanIgnoreReturnValue
@Deprecated
@Override
public final boolean retainAll(Collection elementsToKeep) {
throw new UnsupportedOperationException();
}
/**
* Guaranteed to throw an exception and leave the collection unmodified.
*
* @throws UnsupportedOperationException always
* @deprecated Unsupported operation.
*/
@Deprecated
@Override
public final void clear() {
throw new UnsupportedOperationException();
}
/**
* Scope the return type to {@link UnmodifiableIterator} to ensure this is an unmodifiable view.
*
* @since 20.0 (present with return type {@link Iterator} since 2.0)
*/
@Override
public abstract UnmodifiableIterator iterator();
}
/**
* 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 {@code set1}, then over each element of {@code set2}, in order,
* that is not contained in {@code set1}.
*
* Results are undefined if {@code set1} and {@code set2} are sets based on different
* equivalence relations (as {@link HashSet}, {@link TreeSet}, and the {@link Map#keySet} of an
* {@code IdentityHashMap} all are).
*/
public static SetView union(final Set set1, final Set set2) {
checkNotNull(set1, "set1");
checkNotNull(set2, "set2");
return new SetView() {
@Override
public int size() {
int size = set1.size();
for (E e : set2) {
if (!set1.contains(e)) {
size++;
}
}
return size;
}
@Override
public boolean isEmpty() {
return set1.isEmpty() && set2.isEmpty();
}
@Override
public UnmodifiableIterator iterator() {
return new AbstractIterator() {
final Iterator itr1 = set1.iterator();
final Iterator itr2 = set2.iterator();
@Override
protected E computeNext() {
if (itr1.hasNext()) {
return itr1.next();
}
while (itr2.hasNext()) {
E e = itr2.next();
if (!set1.contains(e)) {
return e;
}
}
return endOfData();
}
};
}
@Override
public Stream stream() {
return Stream.concat(set1.stream(), set2.stream().filter(e -> !set1.contains(e)));
}
@Override
public Stream parallelStream() {
return stream().parallel();
}
@Override
public boolean contains(Object object) {
return set1.contains(object) || set2.contains(object);
}
@Override
public > S copyInto(S set) {
set.addAll(set1);
set.addAll(set2);
return set;
}
@Override
public ImmutableSet immutableCopy() {
return new ImmutableSet.Builder().addAll(set1).addAll(set2).build();
}
};
}
/**
* 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 {@code set1}.
*
* Results are undefined if {@code set1} and {@code set2} are sets based on different
* equivalence relations (as {@code HashSet}, {@code TreeSet}, and the keySet of an {@code
* IdentityHashMap} all are).
*
*
Note: The returned view performs slightly better when {@code 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:
*
*
{@code
* Set
*
* This is unfortunate, but should come up only very rarely.
*/
public static SetView intersection(final Set set1, final Set set2) {
checkNotNull(set1, "set1");
checkNotNull(set2, "set2");
return new SetView() {
@Override
public UnmodifiableIterator iterator() {
return new AbstractIterator() {
final Iterator itr = set1.iterator();
@Override
protected E computeNext() {
while (itr.hasNext()) {
E e = itr.next();
if (set2.contains(e)) {
return e;
}
}
return endOfData();
}
};
}
@Override
public Stream stream() {
return set1.stream().filter(set2::contains);
}
@Override
public Stream parallelStream() {
return set1.parallelStream().filter(set2::contains);
}
@Override
public int size() {
int size = 0;
for (E e : set1) {
if (set2.contains(e)) {
size++;
}
}
return size;
}
@Override
public boolean isEmpty() {
return Collections.disjoint(set2, set1);
}
@Override
public boolean contains(Object object) {
return set1.contains(object) && set2.contains(object);
}
@Override
public boolean containsAll(Collection collection) {
return set1.containsAll(collection) && set2.containsAll(collection);
}
};
}
/**
* Returns an unmodifiable view of the difference of two sets. The returned set contains
* all elements that are contained by {@code set1} and not contained by {@code set2}. {@code set2}
* may also contain elements not present in {@code set1}; these are simply ignored. The iteration
* order of the returned set matches that of {@code set1}.
*
* Results are undefined if {@code set1} and {@code set2} are sets based on different
* equivalence relations (as {@code HashSet}, {@code TreeSet}, and the keySet of an {@code
* IdentityHashMap} all are).
*/
public static SetView difference(final Set set1, final Set set2) {
checkNotNull(set1, "set1");
checkNotNull(set2, "set2");
return new SetView() {
@Override
public UnmodifiableIterator iterator() {
return new AbstractIterator() {
final Iterator itr = set1.iterator();
@Override
protected E computeNext() {
while (itr.hasNext()) {
E e = itr.next();
if (!set2.contains(e)) {
return e;
}
}
return endOfData();
}
};
}
@Override
public Stream stream() {
return set1.stream().filter(e -> !set2.contains(e));
}
@Override
public Stream parallelStream() {
return set1.parallelStream().filter(e -> !set2.contains(e));
}
@Override
public int size() {
int size = 0;
for (E e : set1) {
if (!set2.contains(e)) {
size++;
}
}
return size;
}
@Override
public boolean isEmpty() {
return set2.containsAll(set1);
}
@Override
public boolean contains(Object element) {
return set1.contains(element) && !set2.contains(element);
}
};
}
/**
* Returns an unmodifiable view of the symmetric difference of two sets. The returned set
* contains all elements that are contained in either {@code set1} or {@code set2} but not in
* both. The iteration order of the returned set is undefined.
*
* Results are undefined if {@code set1} and {@code set2} are sets based on different
* equivalence relations (as {@code HashSet}, {@code TreeSet}, and the keySet of an {@code
* IdentityHashMap} all are).
*
* @since 3.0
*/
public static SetView symmetricDifference(
final Set set1, final Set set2) {
checkNotNull(set1, "set1");
checkNotNull(set2, "set2");
return new SetView() {
@Override
public UnmodifiableIterator iterator() {
final Iterator itr1 = set1.iterator();
final Iterator itr2 = set2.iterator();
return new AbstractIterator() {
@Override
public E computeNext() {
while (itr1.hasNext()) {
E elem1 = itr1.next();
if (!set2.contains(elem1)) {
return elem1;
}
}
while (itr2.hasNext()) {
E elem2 = itr2.next();
if (!set1.contains(elem2)) {
return elem2;
}
}
return endOfData();
}
};
}
@Override
public int size() {
int size = 0;
for (E e : set1) {
if (!set2.contains(e)) {
size++;
}
}
for (E e : set2) {
if (!set1.contains(e)) {
size++;
}
}
return size;
}
@Override
public boolean isEmpty() {
return set1.equals(set2);
}
@Override
public boolean contains(Object element) {
return set1.contains(element) ^ set2.contains(element);
}
};
}
/**
* Returns the elements of {@code unfiltered} that satisfy a predicate. The returned set is a live
* view of {@code unfiltered}; changes to one affect the other.
*
* The resulting set's iterator does not support {@code remove()}, but all other set methods
* are supported. When given an element that doesn't satisfy the predicate, the set's {@code
* add()} and {@code addAll()} methods throw an {@link IllegalArgumentException}. When methods
* such as {@code removeAll()} and {@code 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 {@code unfiltered} is.
*
*
Many of the filtered set's methods, such as {@code 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 {@code Iterables.filter(unfiltered, predicate)} and
* use the copy.
*
*
Warning: {@code predicate} must be consistent with equals, as documented at
* {@link Predicate#apply}. Do not provide a predicate such as {@code
* Predicates.instanceOf(ArrayList.class)}, which is inconsistent with equals. (See {@link
* Iterables#filter(Iterable, Class)} for related functionality.)
*
*
Java 8 users: many use cases for this method are better addressed by {@link
* java.util.stream.Stream#filter}. This method is not being deprecated, but we gently encourage
* you to migrate to streams.
*/
// TODO(kevinb): how to omit that last sentence when building GWT javadoc?
public static Set filter(Set unfiltered, Predicate predicate) {
if (unfiltered instanceof SortedSet) {
return filter((SortedSet) unfiltered, predicate);
}
if (unfiltered instanceof FilteredSet) {
// Support clear(), removeAll(), and retainAll() when filtering a filtered
// collection.
FilteredSet filtered = (FilteredSet) unfiltered;
Predicate combinedPredicate = Predicates.and(filtered.predicate, predicate);
return new FilteredSet((Set) filtered.unfiltered, combinedPredicate);
}
return new FilteredSet(checkNotNull(unfiltered), checkNotNull(predicate));
}
/**
* Returns the elements of a {@code SortedSet}, {@code unfiltered}, that satisfy a predicate. The
* returned set is a live view of {@code unfiltered}; changes to one affect the other.
*
* The resulting set's iterator does not support {@code remove()}, but all other set methods
* are supported. When given an element that doesn't satisfy the predicate, the set's {@code
* add()} and {@code addAll()} methods throw an {@link IllegalArgumentException}. When methods
* such as {@code removeAll()} and {@code 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 {@code unfiltered} is.
*
*
Many of the filtered set's methods, such as {@code 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 {@code Iterables.filter(unfiltered, predicate)} and
* use the copy.
*
*
Warning: {@code predicate} must be consistent with equals, as documented at
* {@link Predicate#apply}. Do not provide a predicate such as {@code
* Predicates.instanceOf(ArrayList.class)}, which is inconsistent with equals. (See {@link
* Iterables#filter(Iterable, Class)} for related functionality.)
*
* @since 11.0
*/
public static SortedSet filter(SortedSet unfiltered, Predicate predicate) {
if (unfiltered instanceof FilteredSet) {
// Support clear(), removeAll(), and retainAll() when filtering a filtered
// collection.
FilteredSet filtered = (FilteredSet) unfiltered;
Predicate combinedPredicate = Predicates.and(filtered.predicate, predicate);
return new FilteredSortedSet((SortedSet) filtered.unfiltered, combinedPredicate);
}
return new FilteredSortedSet(checkNotNull(unfiltered), checkNotNull(predicate));
}
/**
* Returns the elements of a {@code NavigableSet}, {@code unfiltered}, that satisfy a predicate.
* The returned set is a live view of {@code unfiltered}; changes to one affect the other.
*
* The resulting set's iterator does not support {@code remove()}, but all other set methods
* are supported. When given an element that doesn't satisfy the predicate, the set's {@code
* add()} and {@code addAll()} methods throw an {@link IllegalArgumentException}. When methods
* such as {@code removeAll()} and {@code 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 {@code unfiltered} is.
*
*
Many of the filtered set's methods, such as {@code 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 {@code Iterables.filter(unfiltered, predicate)} and
* use the copy.
*
*
Warning: {@code predicate} must be consistent with equals, as documented at
* {@link Predicate#apply}. Do not provide a predicate such as {@code
* Predicates.instanceOf(ArrayList.class)}, which is inconsistent with equals. (See {@link
* Iterables#filter(Iterable, Class)} for related functionality.)
*
* @since 14.0
*/
@GwtIncompatible // NavigableSet
@SuppressWarnings("unchecked")
public static NavigableSet filter(
NavigableSet unfiltered, Predicate predicate) {
if (unfiltered instanceof FilteredSet) {
// Support clear(), removeAll(), and retainAll() when filtering a filtered
// collection.
FilteredSet filtered = (FilteredSet) unfiltered;
Predicate combinedPredicate = Predicates.and(filtered.predicate, predicate);
return new FilteredNavigableSet((NavigableSet) filtered.unfiltered, combinedPredicate);
}
return new FilteredNavigableSet(checkNotNull(unfiltered), checkNotNull(predicate));
}
private static class FilteredSet extends FilteredCollection implements Set {
FilteredSet(Set unfiltered, Predicate predicate) {
super(unfiltered, predicate);
}
@Override
public boolean equals(@Nullable Object object) {
return equalsImpl(this, object);
}
@Override
public int hashCode() {
return hashCodeImpl(this);
}
}
private static class FilteredSortedSet extends FilteredSet implements SortedSet {
FilteredSortedSet(SortedSet unfiltered, Predicate predicate) {
super(unfiltered, predicate);
}
@Override
public Comparator comparator() {
return ((SortedSet) unfiltered).comparator();
}
@Override
public SortedSet subSet(E fromElement, E toElement) {
return new FilteredSortedSet(
((SortedSet) unfiltered).subSet(fromElement, toElement), predicate);
}
@Override
public SortedSet headSet(E toElement) {
return new FilteredSortedSet(((SortedSet) unfiltered).headSet(toElement), predicate);
}
@Override
public SortedSet tailSet(E fromElement) {
return new FilteredSortedSet(((SortedSet) unfiltered).tailSet(fromElement), predicate);
}
@Override
public E first() {
return Iterators.find(unfiltered.iterator(), predicate);
}
@Override
public E last() {
SortedSet sortedUnfiltered = (SortedSet) unfiltered;
while (true) {
E element = sortedUnfiltered.last();
if (predicate.apply(element)) {
return element;
}
sortedUnfiltered = sortedUnfiltered.headSet(element);
}
}
}
@GwtIncompatible // NavigableSet
private static class FilteredNavigableSet extends FilteredSortedSet
implements NavigableSet {
FilteredNavigableSet(NavigableSet unfiltered, Predicate predicate) {
super(unfiltered, predicate);
}
NavigableSet unfiltered() {
return (NavigableSet) unfiltered;
}
@Override
public @Nullable E lower(E e) {
return Iterators.find(unfiltered().headSet(e, false).descendingIterator(), predicate, null);
}
@Override
public @Nullable E floor(E e) {
return Iterators.find(unfiltered().headSet(e, true).descendingIterator(), predicate, null);
}
@Override
public E ceiling(E e) {
return Iterables.find(unfiltered().tailSet(e, true), predicate, null);
}
@Override
public E higher(E e) {
return Iterables.find(unfiltered().tailSet(e, false), predicate, null);
}
@Override
public E pollFirst() {
return Iterables.removeFirstMatching(unfiltered(), predicate);
}
@Override
public E pollLast() {
return Iterables.removeFirstMatching(unfiltered().descendingSet(), predicate);
}
@Override
public NavigableSet descendingSet() {
return Sets.filter(unfiltered().descendingSet(), predicate);
}
@Override
public Iterator descendingIterator() {
return Iterators.filter(unfiltered().descendingIterator(), predicate);
}
@Override
public E last() {
return Iterators.find(unfiltered().descendingIterator(), predicate);
}
@Override
public NavigableSet subSet(
E fromElement, boolean fromInclusive, E toElement, boolean toInclusive) {
return filter(
unfiltered().subSet(fromElement, fromInclusive, toElement, toInclusive), predicate);
}
@Override
public NavigableSet headSet(E toElement, boolean inclusive) {
return filter(unfiltered().headSet(toElement, inclusive), predicate);
}
@Override
public NavigableSet tailSet(E fromElement, boolean inclusive) {
return filter(unfiltered().tailSet(fromElement, inclusive), predicate);
}
}
/**
* 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:
*
* {@code
* Sets.cartesianProduct(ImmutableList.of(
* ImmutableSet.of(1, 2),
* ImmutableSet.of("A", "B", "C")))
* }
*
* returns a set containing six lists:
*
*
* - {@code ImmutableList.of(1, "A")}
*
- {@code ImmutableList.of(1, "B")}
*
- {@code ImmutableList.of(1, "C")}
*
- {@code ImmutableList.of(2, "A")}
*
- {@code ImmutableList.of(2, "B")}
*
- {@code 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:
*
*
{@code
* for (B b0 : sets.get(0)) {
* for (B b1 : sets.get(1)) {
* ...
* ImmutableList 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 {@code m, n, p} is a
* set of size {@code 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.
*
* @param sets the sets to choose elements from, in the order that the elements chosen from those
* sets should appear in the resulting lists
* @param any common base class shared by all axes (often just {@link Object})
* @return the Cartesian product, as an immutable set containing immutable lists
* @throws NullPointerException if {@code sets}, any one of the {@code sets}, or any element of a
* provided set is null
* @throws IllegalArgumentException if the cartesian product size exceeds the {@code int} range
* @since 2.0
*/
public static Set> cartesianProduct(List> sets) {
return CartesianSet.create(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:
*
* {@code
* Sets.cartesianProduct(
* ImmutableSet.of(1, 2),
* ImmutableSet.of("A", "B", "C"))
* }
*
* returns a set containing six lists:
*
*
* - {@code ImmutableList.of(1, "A")}
*
- {@code ImmutableList.of(1, "B")}
*
- {@code ImmutableList.of(1, "C")}
*
- {@code ImmutableList.of(2, "A")}
*
- {@code ImmutableList.of(2, "B")}
*
- {@code 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:
*
*
{@code
* for (B b0 : sets.get(0)) {
* for (B b1 : sets.get(1)) {
* ...
* ImmutableList 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 {@code m, n, p} is a
* set of size {@code 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.
*
* @param sets the sets to choose elements from, in the order that the elements chosen from those
* sets should appear in the resulting lists
* @param any common base class shared by all axes (often just {@link Object})
* @return the Cartesian product, as an immutable set containing immutable lists
* @throws NullPointerException if {@code sets}, any one of the {@code sets}, or any element of a
* provided set is null
* @throws IllegalArgumentException if the cartesian product size exceeds the {@code int} range
* @since 2.0
*/
@SafeVarargs
public static Set> cartesianProduct(Set... sets) {
return cartesianProduct(Arrays.asList(sets));
}
private static final class CartesianSet extends ForwardingCollection>
implements Set> {
private final transient ImmutableList> axes;
private final transient CartesianList delegate;
static Set> create(List> sets) {
ImmutableList.Builder> axesBuilder = new ImmutableList.Builder<>(sets.size());
for (Set set : sets) {
ImmutableSet copy = ImmutableSet.copyOf(set);
if (copy.isEmpty()) {
return ImmutableSet.of();
}
axesBuilder.add(copy);
}
final ImmutableList> axes = axesBuilder.build();
ImmutableList> listAxes =
new ImmutableList>() {
@Override
public int size() {
return axes.size();
}
@Override
public List get(int index) {
return axes.get(index).asList();
}
@Override
boolean isPartialView() {
return true;
}
};
return new CartesianSet(axes, new CartesianList(listAxes));
}
private CartesianSet(ImmutableList> axes, CartesianList delegate) {
this.axes = axes;
this.delegate = delegate;
}
@Override
protected Collection> delegate() {
return delegate;
}
@Override
public boolean contains(@Nullable Object object) {
if (!(object instanceof List)) {
return false;
}
List list = (List) object;
if (list.size() != axes.size()) {
return false;
}
int i = 0;
for (Object o : list) {
if (!axes.get(i).contains(o)) {
return false;
}
i++;
}
return true;
}
@Override
public boolean equals(@Nullable Object object) {
// Warning: this is broken if size() == 0, so it is critical that we
// substitute an empty ImmutableSet to the user in place of this
if (object instanceof CartesianSet) {
CartesianSet that = (CartesianSet) object;
return this.axes.equals(that.axes);
}
return super.equals(object);
}
@Override
public int hashCode() {
// Warning: this is broken if size() == 0, so it is critical that we
// substitute an empty ImmutableSet to the user in place of this
// It's a weird formula, but tests prove it works.
int adjust = size() - 1;
for (int i = 0; i < axes.size(); i++) {
adjust *= 31;
adjust = ~~adjust;
// in GWT, we have to deal with integer overflow carefully
}
int hash = 1;
for (Set axis : axes) {
hash = 31 * hash + (size() / axis.size() * axis.hashCode());
hash = ~~hash;
}
hash += adjust;
return ~~hash;
}
}
/**
* Returns the set of all possible subsets of {@code set}. For example, {@code
* powerSet(ImmutableSet.of(1, 2))} returns the set {@code {{}, {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 {@code 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 {@code n} is of size {@code
* 2^n}, its memory usage is only {@code 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.
*
* @param set the set of elements to construct a power set from
* @return the power set, as an immutable set of immutable sets
* @throws IllegalArgumentException if {@code set} has more than 30 unique elements (causing the
* power set size to exceed the {@code int} range)
* @throws NullPointerException if {@code set} is or contains {@code null}
* @see Power set article at Wikipedia
* @since 4.0
*/
@GwtCompatible(serializable = false)
public static Set> powerSet(Set set) {
return new PowerSet(set);
}
private static final class SubSet extends AbstractSet {
private final ImmutableMap inputSet;
private final int mask;
SubSet(ImmutableMap inputSet, int mask) {
this.inputSet = inputSet;
this.mask = mask;
}
@Override
public Iterator iterator() {
return new UnmodifiableIterator() {
final ImmutableList elements = inputSet.keySet().asList();
int remainingSetBits = mask;
@Override
public boolean hasNext() {
return remainingSetBits != 0;
}
@Override
public E next() {
int index = Integer.numberOfTrailingZeros(remainingSetBits);
if (index == 32) {
throw new NoSuchElementException();
}
remainingSetBits &= ~(1 << index);
return elements.get(index);
}
};
}
@Override
public int size() {
return Integer.bitCount(mask);
}
@Override
public boolean contains(@Nullable Object o) {
Integer index = inputSet.get(o);
return index != null && (mask & (1 << index)) != 0;
}
}
private static final class PowerSet