@GwtCompatible(serializable=true, emulated=true) public abstract class ImmutableSet<E> extends ImmutableCollection<E> implements java.util.Set<E>
Set
with reliable, user-specified
iteration order. Does not permit null elements.
Unlike Collections.unmodifiableSet(java.util.Set<? extends T>)
, which is a view of a
separate collection that can still change, an instance of this class contains
its own private data and will never change. This class is convenient
for public static final
sets ("constant sets") and also lets you
easily make a "defensive copy" of a set provided to your class by a caller.
Warning: Like most sets, an ImmutableSet
will not function
correctly if an element is modified after being placed in the set. For this
reason, and to avoid general confusion, it is strongly recommended to place
only immutable objects into this collection.
This class has been observed to perform significantly better than HashSet
for objects with very fast Object.hashCode()
implementations
(as a well-behaved immutable object should). While this class's factory
methods create hash-based instances, the ImmutableSortedSet
subclass
performs binary searches instead.
Note: Although this class is not final, it cannot be subclassed outside its package as it has no public or protected constructors. Thus, instances of this type are guaranteed to be immutable.
See the Guava User Guide article on immutable collections.
ImmutableList
,
ImmutableMap
,
Serialized FormModifier and Type | Class and Description |
---|---|
static class |
ImmutableSet.Builder<E>
A builder for creating immutable set instances, especially
public
static final sets ("constant sets"). |
private static class |
ImmutableSet.SerializedForm |
ImmutableCollection.ArrayBasedBuilder<E>
Modifier and Type | Field and Description |
---|---|
private static int |
CUTOFF |
private static double |
DESIRED_LOAD_FACTOR |
(package private) static int |
MAX_TABLE_SIZE |
Constructor and Description |
---|
ImmutableSet() |
Modifier and Type | Method and Description |
---|---|
static <E> ImmutableSet.Builder<E> |
builder()
Returns a new builder.
|
(package private) static int |
chooseTableSize(int setSize)
Returns an array size suitable for the backing array of a hash table that
uses open addressing with linear probing in its implementation.
|
private static <E> ImmutableSet<E> |
construct(int n,
java.lang.Object... elements)
Constructs an
ImmutableSet from the first n elements of the specified array. |
static <E> ImmutableSet<E> |
copyOf(java.util.Collection<? extends E> elements)
Returns an immutable set containing the given elements, in order.
|
static <E> ImmutableSet<E> |
copyOf(E[] elements)
Returns an immutable set containing the given elements, in order.
|
static <E> ImmutableSet<E> |
copyOf(java.lang.Iterable<? extends E> elements)
Returns an immutable set containing the given elements, in order.
|
static <E> ImmutableSet<E> |
copyOf(java.util.Iterator<? extends E> elements)
Returns an immutable set containing the given elements, in order.
|
private static <E extends java.lang.Enum<E>> |
copyOfEnumSet(java.util.EnumSet<E> enumSet) |
boolean |
equals(java.lang.Object object) |
int |
hashCode() |
(package private) boolean |
isHashCodeFast()
Returns
true if the hashCode() method runs quickly. |
abstract UnmodifiableIterator<E> |
iterator()
Returns an unmodifiable iterator across the elements in this collection.
|
static <E> ImmutableSet<E> |
of()
Returns the empty immutable set.
|
static <E> ImmutableSet<E> |
of(E element)
Returns an immutable set containing a single element.
|
static <E> ImmutableSet<E> |
of(E e1,
E e2)
Returns an immutable set containing the given elements, in order.
|
static <E> ImmutableSet<E> |
of(E e1,
E e2,
E e3)
Returns an immutable set containing the given elements, in order.
|
static <E> ImmutableSet<E> |
of(E e1,
E e2,
E e3,
E e4)
Returns an immutable set containing the given elements, in order.
|
static <E> ImmutableSet<E> |
of(E e1,
E e2,
E e3,
E e4,
E e5)
Returns an immutable set containing the given elements, in order.
|
static <E> ImmutableSet<E> |
of(E e1,
E e2,
E e3,
E e4,
E e5,
E e6,
E... others)
Returns an immutable set containing the given elements, in order.
|
(package private) java.lang.Object |
writeReplace() |
add, addAll, asList, clear, contains, copyIntoArray, createAsList, isPartialView, remove, removeAll, retainAll, toArray, toArray
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
static final int MAX_TABLE_SIZE
private static final double DESIRED_LOAD_FACTOR
private static final int CUTOFF
public static <E> ImmutableSet<E> of()
Collections.emptySet()
, and is preferable mainly for consistency
and maintainability of your code.public static <E> ImmutableSet<E> of(E element)
Collections.singleton(T)
, but will not accept
a null element. It is preferable mainly for consistency and
maintainability of your code.public static <E> ImmutableSet<E> of(E e1, E e2)
Object.equals(java.lang.Object)
) after the
first are ignored.java.lang.NullPointerException
- if any element is nullpublic static <E> ImmutableSet<E> of(E e1, E e2, E e3)
Object.equals(java.lang.Object)
) after the
first are ignored.java.lang.NullPointerException
- if any element is nullpublic static <E> ImmutableSet<E> of(E e1, E e2, E e3, E e4)
Object.equals(java.lang.Object)
) after the
first are ignored.java.lang.NullPointerException
- if any element is nullpublic static <E> ImmutableSet<E> of(E e1, E e2, E e3, E e4, E e5)
Object.equals(java.lang.Object)
) after the
first are ignored.java.lang.NullPointerException
- if any element is nullpublic static <E> ImmutableSet<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E... others)
Object.equals(java.lang.Object)
) after the
first are ignored.java.lang.NullPointerException
- if any element is nullprivate static <E> ImmutableSet<E> construct(int n, java.lang.Object... elements)
ImmutableSet
from the first n
elements of the specified array.
If k
is the size of the returned ImmutableSet
, then the unique elements of
elements
will be in the first k
positions, and elements[i] == null
for
k <= i < n
.
This may modify elements
. Additionally, if n == elements.length
and
elements
contains no duplicates, elements
may be used without copying in the
returned ImmutableSet
, in which case it may no longer be modified.
elements
may contain only values of type E
.
java.lang.NullPointerException
- if any of the first n
elements of elements
is
nullstatic int chooseTableSize(int setSize)
Do not call this method with setSize < 2.
public static <E> ImmutableSet<E> copyOf(E[] elements)
Object.equals(java.lang.Object)
) after the
first are ignored.java.lang.NullPointerException
- if any of elements
is nullpublic static <E> ImmutableSet<E> copyOf(java.lang.Iterable<? extends E> elements)
Object.equals(java.lang.Object)
) after the
first are ignored. This method iterates over elements
at most once.
Note that if s
is a Set<String>
, then ImmutableSet.copyOf(s)
returns an ImmutableSet<String>
containing
each of the strings in s
, while ImmutableSet.of(s)
returns
a ImmutableSet<Set<String>>
containing one element (the given set
itself).
Despite the method name, this method attempts to avoid actually copying the data when it is safe to do so. The exact circumstances under which a copy will or will not be performed are undocumented and subject to change.
java.lang.NullPointerException
- if any of elements
is nullpublic static <E> ImmutableSet<E> copyOf(java.util.Iterator<? extends E> elements)
Object.equals(java.lang.Object)
) after the
first are ignored.java.lang.NullPointerException
- if any of elements
is nullpublic static <E> ImmutableSet<E> copyOf(java.util.Collection<? extends E> elements)
Object.equals(java.lang.Object)
) after the
first are ignored. This method iterates over elements
at most
once.
Note that if s
is a Set<String>
, then ImmutableSet.copyOf(s)
returns an ImmutableSet<String>
containing
each of the strings in s
, while ImmutableSet.of(s)
returns
a ImmutableSet<Set<String>>
containing one element (the given set
itself).
Note: Despite what the method name suggests, copyOf
will
return constant-space views, rather than linear-space copies, of some
inputs known to be immutable. For some other immutable inputs, such as key
sets of an ImmutableMap
, it still performs a copy in order to avoid
holding references to the values of the map. The heuristics used in this
decision are undocumented and subject to change except that:
ImmutableSortedSet
.ImmutableSet.copyOf()
is idempotent with respect to pointer
equality.This method is safe to use even when elements
is a synchronized
or concurrent collection that is currently being modified by another
thread.
java.lang.NullPointerException
- if any of elements
is nullprivate static <E extends java.lang.Enum<E>> ImmutableSet<E> copyOfEnumSet(java.util.EnumSet<E> enumSet)
boolean isHashCodeFast()
true
if the hashCode()
method runs quickly.public boolean equals(@Nullable java.lang.Object object)
public int hashCode()
public abstract UnmodifiableIterator<E> iterator()
ImmutableCollection
java.lang.Object writeReplace()
writeReplace
in class ImmutableCollection<E>
public static <E> ImmutableSet.Builder<E> builder()
ImmutableSet.Builder
constructor.