org.docx4j.com.google.common.collect

Class Sets

java.lang.Object

org.docx4j.com.google.common.collect.Sets

@GwtCompatible(emulated=true)
public final class Sets
extends Object

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

See the Guava User Guide article on Sets.

Since:

2.0

Author:

Kevin Bourrillion, Jared Levy, Chris Povirk

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Sets.SetView<E> An unmodifiable view of a set which may be backed by other sets; this view will change as the backing sets do.

Method Summary

Modifier and Type	Method and Description
static <E extends Enum<E>> EnumSet<E>	complementOf(Collection<E> collection) Creates an EnumSet consisting of all enum values that are not in the specified collection.
static <E extends Enum<E>> EnumSet<E>	complementOf(Collection<E> collection, Class<E> type) Creates an EnumSet consisting of all enum values that are not in the specified collection.
static <E> Set<E>	newConcurrentHashSet() Creates a thread-safe set backed by a hash map.
static <E> CopyOnWriteArraySet<E>	newCopyOnWriteArraySet() Creates an empty CopyOnWriteArraySet instance.
static <E> HashSet<E>	newHashSet() Creates a mutable, initially empty HashSet instance.
static <E> HashSet<E>	newHashSet(E... elements) Creates a mutable HashSet instance initially containing the given elements.
static <E> HashSet<E>	newHashSet(Iterator<? extends E> elements) Creates a mutable HashSet instance containing the given elements.
static <E> HashSet<E>	newHashSetWithExpectedSize(int expectedSize) Returns a new hash set using the smallest initial table size that can hold expectedSize elements without resizing.
static <E> Set<E>	newIdentityHashSet() Creates an empty Set that uses identity to determine equality.
static <E> LinkedHashSet<E>	newLinkedHashSet() Creates a mutable, empty LinkedHashSet instance.
static <E> LinkedHashSet<E>	newLinkedHashSetWithExpectedSize(int expectedSize) Creates a LinkedHashSet instance, with a high enough "initial capacity" that it should hold expectedSize elements without growth.
static <E> Set<E>	newSetFromMap(Map<E,Boolean> map) Deprecated. Use Collections.newSetFromMap(java.util.Map<E, java.lang.Boolean>) instead.
static <E extends Comparable> TreeSet<E>	newTreeSet() Creates a mutable, empty TreeSet instance sorted by the natural sort ordering of its elements.
static <E> TreeSet<E>	newTreeSet(Comparator<? super E> comparator) Creates a mutable, empty TreeSet instance with the given comparator.

Methods inherited from class java.lang.Object

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

Method Detail

newHashSet

public static <E> HashSet<E> newHashSet()

Creates a mutable, initially empty HashSet instance.

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

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

newHashSet

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

Creates a mutable HashSet instance initially containing the given elements.

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

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

newHashSet

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

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

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

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

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

newHashSetWithExpectedSize

public static <E> HashSet<E> newHashSetWithExpectedSize(int expectedSize)

Returns a new hash set using the smallest initial table size that can hold expectedSize elements without resizing. Note that this is not what 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.

Parameters:

expectedSize - the number of elements you expect to add to the returned set

Returns:

a new, empty hash set with enough capacity to hold expectedSize elements without resizing

Throws:

IllegalArgumentException - if expectedSize is negative

newConcurrentHashSet

public static <E> Set<E> newConcurrentHashSet()

Creates a thread-safe set backed by a hash map. The set is backed by a ConcurrentHashMap instance, and thus carries the same concurrency guarantees.

Unlike HashSet, this class does NOT allow null to be used as an element. The set is serializable.

Returns:

a new, empty thread-safe Set

Since:

15.0

newLinkedHashSet

public static <E> LinkedHashSet<E> newLinkedHashSet()

Creates a mutable, empty LinkedHashSet instance.

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

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

Returns:

a new, empty LinkedHashSet

newLinkedHashSetWithExpectedSize

public static <E> LinkedHashSet<E> newLinkedHashSetWithExpectedSize(int expectedSize)

Creates a LinkedHashSet instance, with a high enough "initial capacity" that it should hold expectedSize elements without growth. This behavior cannot be broadly guaranteed, but it is observed to be true for OpenJDK 1.7. It also can't be guaranteed that the method isn't inadvertently oversizing the returned set.

Parameters:

expectedSize - the number of elements you expect to add to the returned set

Returns:

a new, empty LinkedHashSet with enough capacity to hold expectedSize elements without resizing

Throws:

IllegalArgumentException - if expectedSize is negative

Since:

11.0

newTreeSet

public static <E extends Comparable> TreeSet<E> newTreeSet()

Creates a mutable, empty TreeSet instance sorted by the natural sort ordering of its elements.

Note: if mutability is not required, use ImmutableSortedSet#of() instead.

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

Returns:

a new, empty TreeSet

newTreeSet

public static <E> TreeSet<E> newTreeSet(Comparator<? super E> comparator)

Creates a mutable, empty TreeSet instance with the given comparator.

Note: if mutability is not required, use ImmutableSortedSet.orderedBy(comparator).build() instead.

Note for Java 7 and later: this method is now unnecessary and should be treated as deprecated. Instead, use the TreeSet constructor directly, taking advantage of the new "diamond" syntax. One caveat to this is that the TreeSet constructor uses a null Comparator to mean "natural ordering," whereas this factory rejects null. Clean your code accordingly.

Parameters:

comparator - the comparator to use to sort the set

Returns:

a new, empty TreeSet

Throws:

NullPointerException - if comparator is null

newIdentityHashSet

public static <E> Set<E> newIdentityHashSet()

Creates an empty Set that uses identity to determine equality. It compares object references, instead of calling equals, to determine whether a provided object matches an element in the set. For example, contains returns false when passed an object that equals a set member, but isn't the same instance. This behavior is similar to the way IdentityHashMap handles key lookups.

Since:

8.0

newCopyOnWriteArraySet

@GwtIncompatible
public static <E> CopyOnWriteArraySet<E> newCopyOnWriteArraySet()

Creates an empty CopyOnWriteArraySet instance.

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

Returns:

a new, empty CopyOnWriteArraySet

Since:

12.0

complementOf

public static <E extends Enum<E>> EnumSet<E> complementOf(Collection<E> collection)

Creates an EnumSet consisting of all enum values that are not in the specified collection. If the collection is an EnumSet, this method has the same behavior as EnumSet.complementOf(java.util.EnumSet<E>). Otherwise, the specified collection must contain at least one element, in order to determine the element type. If the collection could be empty, use complementOf(Collection, Class) instead of this method.

Parameters:

collection - the collection whose complement should be stored in the enum set

Returns:

a new, modifiable EnumSet containing all values of the enum that aren't present in the given collection

Throws:

IllegalArgumentException - if collection is not an EnumSet instance and contains no elements

complementOf

public static <E extends Enum<E>> EnumSet<E> complementOf(Collection<E> collection,
                                                          Class<E> type)

Creates an EnumSet consisting of all enum values that are not in the specified collection. This is equivalent to EnumSet.complementOf(java.util.EnumSet<E>), but can act on any input collection, as long as the elements are of enum type.

Parameters:

collection - the collection whose complement should be stored in the EnumSet

type - the type of the elements in the set

Returns:

a new, modifiable EnumSet initially containing all the values of the enum not present in the given collection

newSetFromMap

@Deprecated
public static <E> Set<E> newSetFromMap(Map<E,Boolean> map)

Deprecated. Use Collections.newSetFromMap(java.util.Map<E, java.lang.Boolean>) instead.

Returns a set backed by the specified map. The resulting set displays the same ordering, concurrency, and performance characteristics as the backing map. In essence, this factory method provides a Set implementation corresponding to any Map implementation. There is no need to use this method on a Map implementation that already has a corresponding Set implementation (such as HashMap or TreeMap).

Each method invocation on the set returned by this method results in exactly one method invocation on the backing map or its keySet view, with one exception. The addAll method is implemented as a sequence of put invocations on the backing map.

The specified map must be empty at the time this method is invoked, and should not be accessed directly after this method returns. These conditions are ensured if the map is created empty, passed directly to this method, and no reference to the map is retained, as illustrated in the following code fragment:

 Set<Object> identityHashSet = Sets.newSetFromMap(
     new IdentityHashMap<Object, Boolean>());
 

The returned set is serializable if the backing map is.

Parameters:

map - the backing map

Returns:

the set backed by the map

Throws:

IllegalArgumentException - if map is not empty