e1 and e2 such that
e1.equals(e2), and at most one null element. As implied by
its name, this interface models the mathematical set abstraction.
The Set interface places additional stipulations, beyond those
inherited from the Collection interface, on the contracts of all
constructors and on the contracts of the add, equals and
hashCode methods. Declarations for other inherited methods are
also included here for convenience. (The specifications accompanying these
declarations have been tailored to the Set interface, but they do
not contain any additional stipulations.)
The additional stipulation on constructors is, not surprisingly, that all constructors must create a set that contains no duplicate elements (as defined above).
Note
Great care must be exercised if mutable objects are used as set
elements. The behavior of a set is not specified if the value of an object
is changed in a manner that affects equals comparisons while the
object is an element in the set. A special case of this prohibition is
that it is not permissible for a set to contain itself as an element.
Some set implementations have restrictions on the elements that
they may contain. For example, some implementations prohibit null elements,
and some have restrictions on the types of their elements. Attempting to
add an ineligible element throws an unchecked exception, typically
NullPointerException or ClassCastException. Attempting
to query the presence of an ineligible element may throw an exception,
or it may simply return false; some implementations will exhibit the former
behavior and some will exhibit the latter. More generally, attempting an
operation on an ineligible element whose completion would not result in
the insertion of an ineligible element into the set may throw an
exception or it may succeed, at the option of the implementation.
Such exceptions are marked as "optional" in the specification for this
interface.
The Set. and
Set. static factory methods
provide a convenient way to create unmodifiable sets. The Set
instances created by these methods have the following characteristics:
UnsupportedOperationException to be thrown.
However, if the contained elements are themselves mutable, this may cause the
Set to behave inconsistently or its contents to appear to change.
null elements. Attempts to create them with
null elements result in NullPointerException.
IllegalArgumentException.
This interface is a member of the Java Collections Framework.
Collection, List, SortedSet, HashSet, TreeSet, AbstractSet, Collections#singleton(java.lang.Object) , Collections#EMPTY_SET
| Modifier and Type | Method and Description |
|---|---|
| public boolean | Returns: true if this set did not already contain the specified
elementelement to be added to this set e)Redeclares java. Adds the specified element to this set if it is not already present (optional operation). |
| public boolean | Returns: true if this set changed as a result of the callcollection containing elements to be added to this set c)Redeclares java. Adds all of the elements in the specified collection to this set if they're not already present (optional operation). |
| public void | clear()
Redeclares java. Removes all of the elements from this set (optional operation). |
| public boolean | Returns: true if this set contains the specified elementelement whose presence in this set is to be tested o)Redeclares java. Returns |
| public boolean | Returns: true if this set contains all of the elements of the
specified collectioncollection to be checked for containment in this set c)Redeclares java. Returns |
| public static < the E> SetSet's element type | Returns: aSet containing the elements of the given Collectiona coll)Collection from which elements are drawn, must be non-nullReturns an unmodifiable Set containing the elements of the given Collection. |
| public boolean | Returns: true if the specified object is equal to this setobject to be compared for equality with this set o)Redeclares java. Compares the specified object with this set for equality. |
| public int | Returns: the hash code value for this setRedeclares java. Returns the hash code value for this set. |
| public boolean | Returns: true if this set contains no elementsRedeclares java. Returns |
| public Iterator | Returns: an iterator over the elements in this setRedeclares java. Returns an iterator over the elements in this set. |
| public static < the E> SetSet's element type | |
| public static < the E> SetSet's element type | Returns: aSet containing the specified elementthe single element e1)Returns an unmodifiable set containing one element. |
| public static < the E> SetSet's element type | Returns: aSet containing the specified elementsthe first element e1, E the second element e2)Returns an unmodifiable set containing two elements. |
| public static < the E> SetSet's element type | Returns: aSet containing the specified elementsthe first element e1, E the second element e2, E the third element e3)Returns an unmodifiable set containing three elements. |
| public static < the E> SetSet's element type | Returns: aSet containing the specified elementsthe first element e1, E the second element e2, E the third element e3, E the fourth element e4)Returns an unmodifiable set containing four elements. |
| public static < the E> SetSet's element type | Returns: aSet containing the specified elementsthe first element e1, E the second element e2, E the third element e3, E the fourth element e4, E the fifth element e5)Returns an unmodifiable set containing five elements. |
| public static < the E> SetSet's element type | Returns: aSet containing the specified elementsthe first element e1, E the second element e2, E the third element e3, E the fourth element e4, E the fifth element e5, E the sixth element e6)Returns an unmodifiable set containing six elements. |
| public static < the E> SetSet's element type | Returns: aSet containing the specified elementsthe first element e1, E the second element e2, E the third element e3, E the fourth element e4, E the fifth element e5, E the sixth element e6, E the seventh element e7)Returns an unmodifiable set containing seven elements. |
| public static < the E> SetSet's element type | Returns: aSet containing the specified elementsthe first element e1, E the second element e2, E the third element e3, E the fourth element e4, E the fifth element e5, E the sixth element e6, E the seventh element e7, E the eighth element e8)Returns an unmodifiable set containing eight elements. |
| public static < the E> SetSet's element type | Returns: aSet containing the specified elementsthe first element e1, E the second element e2, E the third element e3, E the fourth element e4, E the fifth element e5, E the sixth element e6, E the seventh element e7, E the eighth element e8, E the ninth element e9)Returns an unmodifiable set containing nine elements. |
| public static < the E> SetSet's element type | Returns: aSet containing the specified elementsthe first element e1, E the second element e2, E the third element e3, E the fourth element e4, E the fifth element e5, E the sixth element e6, E the seventh element e7, E the eighth element e8, E the ninth element e9, E the tenth element e10)Returns an unmodifiable set containing ten elements. |
| public static < the E> SetSet's element type | Returns: aSet containing the specified elementsthe elements to be contained in the set elements)Returns an unmodifiable set containing an arbitrary number of elements. |
| public static < the type of elements maintained by the returned set E> Set | Returns: a new lazily computed set whose logical membership for each distinct element candidate in the set ofelementCandidates is
computed via the provided computingFunction on demandthe (non-null) element candidates to be evaluated elementCandidates, Predicate<? super E> to invoke whenever the membership status of an element
candidate is first computed computingFunction)
Preview
Third Preview of Lazy Constants (JEP 531).
Returns a new lazily computed set whose logical membership for each distinct
element candidate in the set of |
| public boolean | Returns: true if this set contained the specified elementobject to be removed from this set, if present o)Redeclares java. Removes the specified element from this set if it is present (optional operation). |
| public boolean | Returns: true if this set changed as a result of the callcollection containing elements to be removed from this set c)Redeclares java. Removes from this set all of its elements that are contained in the specified collection (optional operation). |
| public boolean | Returns: true if this set changed as a result of the callcollection containing elements to be retained in this set c)Redeclares java. Retains only the elements in this set that are contained in the specified collection (optional operation). |
| public int | Returns: the number of elements in this set (its cardinality)Redeclares java. Returns the number of elements in this set (its cardinality). |
| public default Spliterator | Returns: aSpliterator over the elements in this setOverrides default java. Creates a |
| public Object[] | Returns: an array containing all the elements in this setRedeclares java. Returns an array containing all of the elements in this set. |
| public <T> T[] | Returns: an array containing all the elements in this setthe array into which the elements of this set are to be
stored, if it is big enough; otherwise, a new array of the same
runtime type is allocated for this purpose. a)Redeclares java. Returns an array containing all of the elements in this set; the runtime type of the returned array is that of the specified array. |
| add | back to summary |
|---|---|
| public boolean add(E e) Redeclares java. Adds the specified element to this set if it is not already present
(optional operation). More formally, adds the specified element
The stipulation above does not imply that sets must accept all
elements; sets may refuse to add any particular element, including
| |
| addAll | back to summary |
|---|---|
| public boolean addAll(Collection<? extends E> c) Redeclares java. Adds all of the elements in the specified collection to this set if
they're not already present (optional operation). If the specified
collection is also a set, the
| |
| clear | back to summary |
|---|---|
| public void clear() Redeclares java. Removes all of the elements from this set (optional operation). The set will be empty after this call returns.
| |
| contains | back to summary |
|---|---|
| public boolean contains(Object o) Redeclares java. Returns
| |
| containsAll | back to summary |
|---|---|
| public boolean containsAll(Collection<?> c) Redeclares java. Returns
| |
| copyOf | back to summary |
|---|---|
| public static <E> Set Returns an unmodifiable Set containing the elements of the given Collection. The given Collection must not be null, and it must not contain any null elements. If the given Collection contains duplicate elements, an arbitrary element of the duplicates is preserved. If the given Collection is subsequently modified, the returned Set will not reflect such modifications. Implementation Note If the given Collection is an unmodifiable Set, calling copyOf will generally not create a copy.
| |
| equals | back to summary |
|---|---|
| public boolean equals(Object o) Redeclares java. Compares the specified object with this set for equality. Returns
| |
| hashCode | back to summary |
|---|---|
| public int hashCode() Redeclares java. Returns the hash code value for this set. The hash code of a set is
defined to be the sum of the hash codes of the elements in the set,
where the hash code of a
| |
| isEmpty | back to summary |
|---|---|
| public boolean isEmpty() Redeclares java. Returns
| |
| iterator | back to summary |
|---|---|
| public Iterator Redeclares java. Returns an iterator over the elements in this set. The elements are returned in no particular order (unless this set is an instance of some class that provides a guarantee).
| |
| of | back to summary |
|---|---|
| public static <E> Set Returns an unmodifiable set containing zero elements. See Unmodifiable Sets for details.
| |
| of | back to summary |
|---|---|
| public static <E> Set Returns an unmodifiable set containing one element. See Unmodifiable Sets for details.
| |
| of | back to summary |
|---|---|
| public static <E> Set Returns an unmodifiable set containing two elements. See Unmodifiable Sets for details.
| |
| of | back to summary |
|---|---|
| public static <E> Set Returns an unmodifiable set containing three elements. See Unmodifiable Sets for details.
| |
| of | back to summary |
|---|---|
| public static <E> Set Returns an unmodifiable set containing four elements. See Unmodifiable Sets for details.
| |
| of | back to summary |
|---|---|
| public static <E> Set Returns an unmodifiable set containing five elements. See Unmodifiable Sets for details.
| |
| of | back to summary |
|---|---|
| public static <E> Set Returns an unmodifiable set containing six elements. See Unmodifiable Sets for details.
| |
| of | back to summary |
|---|---|
| public static <E> Set Returns an unmodifiable set containing seven elements. See Unmodifiable Sets for details.
| |
| of | back to summary |
|---|---|
| public static <E> Set Returns an unmodifiable set containing eight elements. See Unmodifiable Sets for details.
| |
| of | back to summary |
|---|---|
| public static <E> Set Returns an unmodifiable set containing nine elements. See Unmodifiable Sets for details.
| |
| of | back to summary |
|---|---|
| public static <E> Set Returns an unmodifiable set containing ten elements. See Unmodifiable Sets for details.
| |
| of | back to summary |
|---|---|
| public static <E> Set Returns an unmodifiable set containing an arbitrary number of elements. See Unmodifiable Sets for details. API Note This method also accepts a single array as an argument. The element type of the resulting set will be the component type of the array, and the size of the set will be equal to the length of the array. To create a set with a single element that is an array, do the following: Set. method
to be invoked instead.
| |
| ofLazy | back to summary |
|---|---|
| public static <E> Set Preview Third Preview of Lazy Constants (JEP 531). Programs can only use Returns a new lazily computed set whose logical membership for each distinct
element candidate in the set of
In the following, the term membership status is used to indicate whether
an element belongs to the returned set or not. That is, if the membership status
for element
The returned set is an unmodifiable set. The
elements in the returned set are derived from the element candidates given at
construction in combination with evaluating each element's membership status. The
set's element membership statuses are lazily computed via the provided
The provided computing function is guaranteed to be invoked at most once per element candidate, even in a multi-threaded environment. Competing threads accessing an element candidate already under membership status computation will block until the membership status of the element candidate is computed or the computing function completes abnormally. If evaluation of the provided computing function throws an unchecked exception (for an element candidate), the lazy membership status is not initialized but instead transitions to an error state whereafter a NoSuchElementException is thrown with the unchecked exception as a cause. Subsequent Set::contains calls for the same membership candidate throw NoSuchElementException (without ever invoking the computing function again) with no cause and with a message that includes the name of the original unchecked exception's class. All failures are handled in this way. There is a special case that causes unchecked exceptions to be thrown: If the computing function recursively invokes itself (for the same membership candidate) via the returned lazy set, a NoSuchElementException (with an IllegalStateException as a cause) will be thrown. The returned set's Object methods; equals(), hashCode(), and toString() methods may trigger initialization of one or more lazy elements. If initialization fails for at least one element, the hashCode() and toString() methods throw NoSuchElementException, and the Object#equals(Object) throw NoSuchElementException if attempting to compare an element that could not be computed. The returned lazy set strongly references its underlying computing function used to compute membership status at least as long as there are uncomputed element candidates. The returned Set is not Serializable.
If the provided
The Here is an example involving an application that manages various configurable options -- commonly referred to as "switches" -- that control its behavior. The state of these switches can be determined through the command line, a configuration file, or even a database connection. By using a lazy set, we ensure that the states of these switches are evaluated only once. Once computed, the results are eligible for constant folding by the JVM: class Application { enum Option {VERBOSE, DRY_RUN, STRICT} // Lazily initialized Set of Options static final Set<Option> OPTIONS = Set.ofLazy(EnumSet.allOf(Option.class), Application::isEnabled); // Return true when the given Option is enabled private static boolean isEnabled(Option option) { // Parse command line, read configuration file, load database ... } public static void process() { // The if condition (and subsequent eliminated branch) is // eligible for constant folding (and code elimination). if (OPTIONS.contains(Option.DRY_RUN)) { // Skip processing in DRY_RUN mode return; } // Actual processing logic } }
The returned class LazySet<E> extends AbstractCollection<E> implements Set<E> { private final Map<E, LazyConstant<Boolean>> backingMap; public LazySet(Set<E> elementCandidates, Predicate<E> computingFunction) { this.backingMap = elementCandidates.stream() .collect(Collectors.toUnmodifiableMap( Function.identity(), k -> LazyConstant.of(() -> computingFunction.test(k)))); } @Override public boolean contains(Object o) { var lazyConstant = backingMap.get(o); return lazyConstant == null ? false : lazyConstant.get(); } } Elements in the returned set are eligible for certain performance optimizations such as constant folding as described in LazyConstant. Implementation Note after all element membership statuses have been initialized successfully or transitioned to an error state, the computing function is no longer strongly referenced and becomes eligible for garbage collection.
| |
| remove | back to summary |
|---|---|
| public boolean remove(Object o) Redeclares java. Removes the specified element from this set if it is present
(optional operation). More formally, removes an element
| |
| removeAll | back to summary |
|---|---|
| public boolean removeAll(Collection<?> c) Redeclares java. Removes from this set all of its elements that are contained in the specified collection (optional operation). If the specified collection is also a set, this operation effectively modifies this set so that its value is the asymmetric set difference of the two sets.
| |
| retainAll | back to summary |
|---|---|
| public boolean retainAll(Collection<?> c) Redeclares java. Retains only the elements in this set that are contained in the specified collection (optional operation). In other words, removes from this set all of its elements that are not contained in the specified collection. If the specified collection is also a set, this operation effectively modifies this set so that its value is the intersection of the two sets.
| |
| size | back to summary |
|---|---|
| public int size() Redeclares java. Returns the number of elements in this set (its cardinality). If this
set contains more than
| |
| spliterator | back to summary |
|---|---|
| public default Spliterator Overrides default java. Creates a The Implementation Specification The default implementation creates a
late-binding spliterator
from the set's
The created Implementation Note The created
| |
| toArray | back to summary |
|---|---|
| public Object[] toArray() Redeclares java. Returns an array containing all of the elements in this set. If this set makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order. The returned array will be "safe" in that no references to it are maintained by this set. (In other words, this method must allocate a new array even if this set is backed by an array). The caller is thus free to modify the returned array. This method acts as bridge between array-based and collection-based APIs.
| |
| toArray | back to summary |
|---|---|
| public <T> T[] toArray(T[] a) Redeclares java. Returns an array containing all of the elements in this set; the runtime type of the returned array is that of the specified array. If the set fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this set. If this set fits in the specified array with room to spare
(i.e., the array has more elements than this set), the element in
the array immediately following the end of the set is set to
If this set makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order. Like the Suppose
String[] y = x.toArray(new String[0]);
Note that toArray(new Object[0]) is identical in function to
toArray().
| |