1 /*
2  * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4  *
5  * This code is free software; you can redistribute it and/or modify it
6  * under the terms of the GNU General Public License version 2 only, as
7  * published by the Free Software Foundation.  Oracle designates this
8  * particular file as subject to the "Classpath" exception as provided
9  * by Oracle in the LICENSE file that accompanied this code.
10  *
11  * This code is distributed in the hope that it will be useful, but WITHOUT
12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14  * version 2 for more details (a copy is included in the LICENSE file that
15  * accompanied this code).
16  *
17  * You should have received a copy of the GNU General Public License version
18  * 2 along with this work; if not, write to the Free Software Foundation,
19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20  *
21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22  * or visit www.oracle.com if you need additional information or have any
23  * questions.
24  */
25 
26 package java.util;
27 
28 /**
29  * A collection that contains no duplicate elements.  More formally, sets
30  * contain no pair of elements {@code e1} and {@code e2} such that
31  * {@code e1.equals(e2)}, and at most one null element.  As implied by
32  * its name, this interface models the mathematical <i>set</i> abstraction.
33  *
34  * <p>The {@code Set} interface places additional stipulations, beyond those
35  * inherited from the {@code Collection} interface, on the contracts of all
36  * constructors and on the contracts of the {@code add}, {@code equals} and
37  * {@code hashCode} methods.  Declarations for other inherited methods are
38  * also included here for convenience.  (The specifications accompanying these
39  * declarations have been tailored to the {@code Set} interface, but they do
40  * not contain any additional stipulations.)
41  *
42  * <p>The additional stipulation on constructors is, not surprisingly,
43  * that all constructors must create a set that contains no duplicate elements
44  * (as defined above).
45  *
46  * <p>Note: Great care must be exercised if mutable objects are used as set
47  * elements.  The behavior of a set is not specified if the value of an object
48  * is changed in a manner that affects {@code equals} comparisons while the
49  * object is an element in the set.  A special case of this prohibition is
50  * that it is not permissible for a set to contain itself as an element.
51  *
52  * <p>Some set implementations have restrictions on the elements that
53  * they may contain.  For example, some implementations prohibit null elements,
54  * and some have restrictions on the types of their elements.  Attempting to
55  * add an ineligible element throws an unchecked exception, typically
56  * {@code NullPointerException} or {@code ClassCastException}.  Attempting
57  * to query the presence of an ineligible element may throw an exception,
58  * or it may simply return false; some implementations will exhibit the former
59  * behavior and some will exhibit the latter.  More generally, attempting an
60  * operation on an ineligible element whose completion would not result in
61  * the insertion of an ineligible element into the set may throw an
62  * exception or it may succeed, at the option of the implementation.
63  * Such exceptions are marked as "optional" in the specification for this
64  * interface.
65  *
66  * <h2><a id="unmodifiable">Unmodifiable Sets</a></h2>
67  * <p>The {@link Set#of(Object...) Set.of} and
68  * {@link Set#copyOf Set.copyOf} static factory methods
69  * provide a convenient way to create unmodifiable sets. The {@code Set}
70  * instances created by these methods have the following characteristics:
71  *
72  * <ul>
73  * <li>They are <a href="Collection.html#unmodifiable"><i>unmodifiable</i></a>. Elements cannot
74  * be added or removed. Calling any mutator method on the Set
75  * will always cause {@code UnsupportedOperationException} to be thrown.
76  * However, if the contained elements are themselves mutable, this may cause the
77  * Set to behave inconsistently or its contents to appear to change.
78  * <li>They disallow {@code null} elements. Attempts to create them with
79  * {@code null} elements result in {@code NullPointerException}.
80  * <li>They are serializable if all elements are serializable.
81  * <li>They reject duplicate elements at creation time. Duplicate elements
82  * passed to a static factory method result in {@code IllegalArgumentException}.
83  * <li>The iteration order of set elements is unspecified and is subject to change.
84  * <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
85  * Callers should make no assumptions about the identity of the returned instances.
86  * Factories are free to create new instances or reuse existing ones. Therefore,
87  * identity-sensitive operations on these instances (reference equality ({@code ==}),
88  * identity hash code, and synchronization) are unreliable and should be avoided.
89  * <li>They are serialized as specified on the
90  * <a href="{@docRoot}/serialized-form.html#java.util.CollSer">Serialized Form</a>
91  * page.
92  * </ul>
93  *
94  * <p>This interface is a member of the
95  * <a href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework">
96  * Java Collections Framework</a>.
97  *
98  * @param <E> the type of elements maintained by this set
99  *
100  * @author  Josh Bloch
101  * @author  Neal Gafter
102  * @see Collection
103  * @see List
104  * @see SortedSet
105  * @see HashSet
106  * @see TreeSet
107  * @see AbstractSet
108  * @see Collections#singleton(java.lang.Object)
109  * @see Collections#EMPTY_SET
110  * @since 1.2
111  */
112 
113 public interface Set<E> extends Collection<E> {
114     // Query Operations
115 
116     /**
117      * Returns the number of elements in this set (its cardinality).  If this
118      * set contains more than {@code Integer.MAX_VALUE} elements, returns
119      * {@code Integer.MAX_VALUE}.
120      *
121      * @return the number of elements in this set (its cardinality)
122      */
size()123     int size();
124 
125     /**
126      * Returns {@code true} if this set contains no elements.
127      *
128      * @return {@code true} if this set contains no elements
129      */
isEmpty()130     boolean isEmpty();
131 
132     /**
133      * Returns {@code true} if this set contains the specified element.
134      * More formally, returns {@code true} if and only if this set
135      * contains an element {@code e} such that
136      * {@code Objects.equals(o, e)}.
137      *
138      * @param o element whose presence in this set is to be tested
139      * @return {@code true} if this set contains the specified element
140      * @throws ClassCastException if the type of the specified element
141      *         is incompatible with this set
142      * (<a href="Collection.html#optional-restrictions">optional</a>)
143      * @throws NullPointerException if the specified element is null and this
144      *         set does not permit null elements
145      * (<a href="Collection.html#optional-restrictions">optional</a>)
146      */
contains(Object o)147     boolean contains(Object o);
148 
149     /**
150      * Returns an iterator over the elements in this set.  The elements are
151      * returned in no particular order (unless this set is an instance of some
152      * class that provides a guarantee).
153      *
154      * @return an iterator over the elements in this set
155      */
iterator()156     Iterator<E> iterator();
157 
158     /**
159      * Returns an array containing all of the elements in this set.
160      * If this set makes any guarantees as to what order its elements
161      * are returned by its iterator, this method must return the
162      * elements in the same order.
163      *
164      * <p>The returned array will be "safe" in that no references to it
165      * are maintained by this set.  (In other words, this method must
166      * allocate a new array even if this set is backed by an array).
167      * The caller is thus free to modify the returned array.
168      *
169      * <p>This method acts as bridge between array-based and collection-based
170      * APIs.
171      *
172      * @return an array containing all the elements in this set
173      */
toArray()174     Object[] toArray();
175 
176     /**
177      * Returns an array containing all of the elements in this set; the
178      * runtime type of the returned array is that of the specified array.
179      * If the set fits in the specified array, it is returned therein.
180      * Otherwise, a new array is allocated with the runtime type of the
181      * specified array and the size of this set.
182      *
183      * <p>If this set fits in the specified array with room to spare
184      * (i.e., the array has more elements than this set), the element in
185      * the array immediately following the end of the set is set to
186      * {@code null}.  (This is useful in determining the length of this
187      * set <i>only</i> if the caller knows that this set does not contain
188      * any null elements.)
189      *
190      * <p>If this set makes any guarantees as to what order its elements
191      * are returned by its iterator, this method must return the elements
192      * in the same order.
193      *
194      * <p>Like the {@link #toArray()} method, this method acts as bridge between
195      * array-based and collection-based APIs.  Further, this method allows
196      * precise control over the runtime type of the output array, and may,
197      * under certain circumstances, be used to save allocation costs.
198      *
199      * <p>Suppose {@code x} is a set known to contain only strings.
200      * The following code can be used to dump the set into a newly allocated
201      * array of {@code String}:
202      *
203      * <pre>
204      *     String[] y = x.toArray(new String[0]);</pre>
205      *
206      * Note that {@code toArray(new Object[0])} is identical in function to
207      * {@code toArray()}.
208      *
209      * @param a the array into which the elements of this set are to be
210      *        stored, if it is big enough; otherwise, a new array of the same
211      *        runtime type is allocated for this purpose.
212      * @return an array containing all the elements in this set
213      * @throws ArrayStoreException if the runtime type of the specified array
214      *         is not a supertype of the runtime type of every element in this
215      *         set
216      * @throws NullPointerException if the specified array is null
217      */
toArray(T[] a)218     <T> T[] toArray(T[] a);
219 
220 
221     // Modification Operations
222 
223     /**
224      * Adds the specified element to this set if it is not already present
225      * (optional operation).  More formally, adds the specified element
226      * {@code e} to this set if the set contains no element {@code e2}
227      * such that
228      * {@code Objects.equals(e, e2)}.
229      * If this set already contains the element, the call leaves the set
230      * unchanged and returns {@code false}.  In combination with the
231      * restriction on constructors, this ensures that sets never contain
232      * duplicate elements.
233      *
234      * <p>The stipulation above does not imply that sets must accept all
235      * elements; sets may refuse to add any particular element, including
236      * {@code null}, and throw an exception, as described in the
237      * specification for {@link Collection#add Collection.add}.
238      * Individual set implementations should clearly document any
239      * restrictions on the elements that they may contain.
240      *
241      * @param e element to be added to this set
242      * @return {@code true} if this set did not already contain the specified
243      *         element
244      * @throws UnsupportedOperationException if the {@code add} operation
245      *         is not supported by this set
246      * @throws ClassCastException if the class of the specified element
247      *         prevents it from being added to this set
248      * @throws NullPointerException if the specified element is null and this
249      *         set does not permit null elements
250      * @throws IllegalArgumentException if some property of the specified element
251      *         prevents it from being added to this set
252      */
add(E e)253     boolean add(E e);
254 
255 
256     /**
257      * Removes the specified element from this set if it is present
258      * (optional operation).  More formally, removes an element {@code e}
259      * such that
260      * {@code Objects.equals(o, e)}, if
261      * this set contains such an element.  Returns {@code true} if this set
262      * contained the element (or equivalently, if this set changed as a
263      * result of the call).  (This set will not contain the element once the
264      * call returns.)
265      *
266      * @param o object to be removed from this set, if present
267      * @return {@code true} if this set contained the specified element
268      * @throws ClassCastException if the type of the specified element
269      *         is incompatible with this set
270      * (<a href="Collection.html#optional-restrictions">optional</a>)
271      * @throws NullPointerException if the specified element is null and this
272      *         set does not permit null elements
273      * (<a href="Collection.html#optional-restrictions">optional</a>)
274      * @throws UnsupportedOperationException if the {@code remove} operation
275      *         is not supported by this set
276      */
remove(Object o)277     boolean remove(Object o);
278 
279 
280     // Bulk Operations
281 
282     /**
283      * Returns {@code true} if this set contains all of the elements of the
284      * specified collection.  If the specified collection is also a set, this
285      * method returns {@code true} if it is a <i>subset</i> of this set.
286      *
287      * @param  c collection to be checked for containment in this set
288      * @return {@code true} if this set contains all of the elements of the
289      *         specified collection
290      * @throws ClassCastException if the types of one or more elements
291      *         in the specified collection are incompatible with this
292      *         set
293      * (<a href="Collection.html#optional-restrictions">optional</a>)
294      * @throws NullPointerException if the specified collection contains one
295      *         or more null elements and this set does not permit null
296      *         elements
297      * (<a href="Collection.html#optional-restrictions">optional</a>),
298      *         or if the specified collection is null
299      * @see    #contains(Object)
300      */
containsAll(Collection<?> c)301     boolean containsAll(Collection<?> c);
302 
303     /**
304      * Adds all of the elements in the specified collection to this set if
305      * they're not already present (optional operation).  If the specified
306      * collection is also a set, the {@code addAll} operation effectively
307      * modifies this set so that its value is the <i>union</i> of the two
308      * sets.  The behavior of this operation is undefined if the specified
309      * collection is modified while the operation is in progress.
310      *
311      * @param  c collection containing elements to be added to this set
312      * @return {@code true} if this set changed as a result of the call
313      *
314      * @throws UnsupportedOperationException if the {@code addAll} operation
315      *         is not supported by this set
316      * @throws ClassCastException if the class of an element of the
317      *         specified collection prevents it from being added to this set
318      * @throws NullPointerException if the specified collection contains one
319      *         or more null elements and this set does not permit null
320      *         elements, or if the specified collection is null
321      * @throws IllegalArgumentException if some property of an element of the
322      *         specified collection prevents it from being added to this set
323      * @see #add(Object)
324      */
addAll(Collection<? extends E> c)325     boolean addAll(Collection<? extends E> c);
326 
327     /**
328      * Retains only the elements in this set that are contained in the
329      * specified collection (optional operation).  In other words, removes
330      * from this set all of its elements that are not contained in the
331      * specified collection.  If the specified collection is also a set, this
332      * operation effectively modifies this set so that its value is the
333      * <i>intersection</i> of the two sets.
334      *
335      * @param  c collection containing elements to be retained in this set
336      * @return {@code true} if this set changed as a result of the call
337      * @throws UnsupportedOperationException if the {@code retainAll} operation
338      *         is not supported by this set
339      * @throws ClassCastException if the class of an element of this set
340      *         is incompatible with the specified collection
341      * (<a href="Collection.html#optional-restrictions">optional</a>)
342      * @throws NullPointerException if this set contains a null element and the
343      *         specified collection does not permit null elements
344      *         (<a href="Collection.html#optional-restrictions">optional</a>),
345      *         or if the specified collection is null
346      * @see #remove(Object)
347      */
retainAll(Collection<?> c)348     boolean retainAll(Collection<?> c);
349 
350     /**
351      * Removes from this set all of its elements that are contained in the
352      * specified collection (optional operation).  If the specified
353      * collection is also a set, this operation effectively modifies this
354      * set so that its value is the <i>asymmetric set difference</i> of
355      * the two sets.
356      *
357      * @param  c collection containing elements to be removed from this set
358      * @return {@code true} if this set changed as a result of the call
359      * @throws UnsupportedOperationException if the {@code removeAll} operation
360      *         is not supported by this set
361      * @throws ClassCastException if the class of an element of this set
362      *         is incompatible with the specified collection
363      * (<a href="Collection.html#optional-restrictions">optional</a>)
364      * @throws NullPointerException if this set contains a null element and the
365      *         specified collection does not permit null elements
366      *         (<a href="Collection.html#optional-restrictions">optional</a>),
367      *         or if the specified collection is null
368      * @see #remove(Object)
369      * @see #contains(Object)
370      */
removeAll(Collection<?> c)371     boolean removeAll(Collection<?> c);
372 
373     /**
374      * Removes all of the elements from this set (optional operation).
375      * The set will be empty after this call returns.
376      *
377      * @throws UnsupportedOperationException if the {@code clear} method
378      *         is not supported by this set
379      */
clear()380     void clear();
381 
382 
383     // Comparison and hashing
384 
385     /**
386      * Compares the specified object with this set for equality.  Returns
387      * {@code true} if the specified object is also a set, the two sets
388      * have the same size, and every member of the specified set is
389      * contained in this set (or equivalently, every member of this set is
390      * contained in the specified set).  This definition ensures that the
391      * equals method works properly across different implementations of the
392      * set interface.
393      *
394      * @param o object to be compared for equality with this set
395      * @return {@code true} if the specified object is equal to this set
396      */
equals(Object o)397     boolean equals(Object o);
398 
399     /**
400      * Returns the hash code value for this set.  The hash code of a set is
401      * defined to be the sum of the hash codes of the elements in the set,
402      * where the hash code of a {@code null} element is defined to be zero.
403      * This ensures that {@code s1.equals(s2)} implies that
404      * {@code s1.hashCode()==s2.hashCode()} for any two sets {@code s1}
405      * and {@code s2}, as required by the general contract of
406      * {@link Object#hashCode}.
407      *
408      * @return the hash code value for this set
409      * @see Object#equals(Object)
410      * @see Set#equals(Object)
411      */
hashCode()412     int hashCode();
413 
414     /**
415      * Creates a {@code Spliterator} over the elements in this set.
416      *
417      * <p>The {@code Spliterator} reports {@link Spliterator#DISTINCT}.
418      * Implementations should document the reporting of additional
419      * characteristic values.
420      *
421      * @implSpec
422      * The default implementation creates a
423      * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator
424      * from the set's {@code Iterator}.  The spliterator inherits the
425      * <em>fail-fast</em> properties of the set's iterator.
426      * <p>
427      * The created {@code Spliterator} additionally reports
428      * {@link Spliterator#SIZED}.
429      *
430      * @implNote
431      * The created {@code Spliterator} additionally reports
432      * {@link Spliterator#SUBSIZED}.
433      *
434      * @return a {@code Spliterator} over the elements in this set
435      * @since 1.8
436      */
437     @Override
spliterator()438     default Spliterator<E> spliterator() {
439         return Spliterators.spliterator(this, Spliterator.DISTINCT);
440     }
441 
442     /**
443      * Returns an unmodifiable set containing zero elements.
444      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
445      *
446      * @param <E> the {@code Set}'s element type
447      * @return an empty {@code Set}
448      *
449      * @since 9
450      */
of()451     static <E> Set<E> of() {
452         return ImmutableCollections.emptySet();
453     }
454 
455     /**
456      * Returns an unmodifiable set containing one element.
457      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
458      *
459      * @param <E> the {@code Set}'s element type
460      * @param e1 the single element
461      * @return a {@code Set} containing the specified element
462      * @throws NullPointerException if the element is {@code null}
463      *
464      * @since 9
465      */
of(E e1)466     static <E> Set<E> of(E e1) {
467         return new ImmutableCollections.Set12<>(e1);
468     }
469 
470     /**
471      * Returns an unmodifiable set containing two elements.
472      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
473      *
474      * @param <E> the {@code Set}'s element type
475      * @param e1 the first element
476      * @param e2 the second element
477      * @return a {@code Set} containing the specified elements
478      * @throws IllegalArgumentException if the elements are duplicates
479      * @throws NullPointerException if an element is {@code null}
480      *
481      * @since 9
482      */
of(E e1, E e2)483     static <E> Set<E> of(E e1, E e2) {
484         return new ImmutableCollections.Set12<>(e1, e2);
485     }
486 
487     /**
488      * Returns an unmodifiable set containing three elements.
489      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
490      *
491      * @param <E> the {@code Set}'s element type
492      * @param e1 the first element
493      * @param e2 the second element
494      * @param e3 the third element
495      * @return a {@code Set} containing the specified elements
496      * @throws IllegalArgumentException if there are any duplicate elements
497      * @throws NullPointerException if an element is {@code null}
498      *
499      * @since 9
500      */
of(E e1, E e2, E e3)501     static <E> Set<E> of(E e1, E e2, E e3) {
502         return new ImmutableCollections.SetN<>(e1, e2, e3);
503     }
504 
505     /**
506      * Returns an unmodifiable set containing four elements.
507      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
508      *
509      * @param <E> the {@code Set}'s element type
510      * @param e1 the first element
511      * @param e2 the second element
512      * @param e3 the third element
513      * @param e4 the fourth element
514      * @return a {@code Set} containing the specified elements
515      * @throws IllegalArgumentException if there are any duplicate elements
516      * @throws NullPointerException if an element is {@code null}
517      *
518      * @since 9
519      */
of(E e1, E e2, E e3, E e4)520     static <E> Set<E> of(E e1, E e2, E e3, E e4) {
521         return new ImmutableCollections.SetN<>(e1, e2, e3, e4);
522     }
523 
524     /**
525      * Returns an unmodifiable set containing five elements.
526      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
527      *
528      * @param <E> the {@code Set}'s element type
529      * @param e1 the first element
530      * @param e2 the second element
531      * @param e3 the third element
532      * @param e4 the fourth element
533      * @param e5 the fifth element
534      * @return a {@code Set} containing the specified elements
535      * @throws IllegalArgumentException if there are any duplicate elements
536      * @throws NullPointerException if an element is {@code null}
537      *
538      * @since 9
539      */
of(E e1, E e2, E e3, E e4, E e5)540     static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5) {
541         return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5);
542     }
543 
544     /**
545      * Returns an unmodifiable set containing six elements.
546      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
547      *
548      * @param <E> the {@code Set}'s element type
549      * @param e1 the first element
550      * @param e2 the second element
551      * @param e3 the third element
552      * @param e4 the fourth element
553      * @param e5 the fifth element
554      * @param e6 the sixth element
555      * @return a {@code Set} containing the specified elements
556      * @throws IllegalArgumentException if there are any duplicate elements
557      * @throws NullPointerException if an element is {@code null}
558      *
559      * @since 9
560      */
of(E e1, E e2, E e3, E e4, E e5, E e6)561     static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6) {
562         return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
563                                                e6);
564     }
565 
566     /**
567      * Returns an unmodifiable set containing seven elements.
568      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
569      *
570      * @param <E> the {@code Set}'s element type
571      * @param e1 the first element
572      * @param e2 the second element
573      * @param e3 the third element
574      * @param e4 the fourth element
575      * @param e5 the fifth element
576      * @param e6 the sixth element
577      * @param e7 the seventh element
578      * @return a {@code Set} containing the specified elements
579      * @throws IllegalArgumentException if there are any duplicate elements
580      * @throws NullPointerException if an element is {@code null}
581      *
582      * @since 9
583      */
of(E e1, E e2, E e3, E e4, E e5, E e6, E e7)584     static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7) {
585         return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
586                                                e6, e7);
587     }
588 
589     /**
590      * Returns an unmodifiable set containing eight elements.
591      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
592      *
593      * @param <E> the {@code Set}'s element type
594      * @param e1 the first element
595      * @param e2 the second element
596      * @param e3 the third element
597      * @param e4 the fourth element
598      * @param e5 the fifth element
599      * @param e6 the sixth element
600      * @param e7 the seventh element
601      * @param e8 the eighth element
602      * @return a {@code Set} containing the specified elements
603      * @throws IllegalArgumentException if there are any duplicate elements
604      * @throws NullPointerException if an element is {@code null}
605      *
606      * @since 9
607      */
of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8)608     static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) {
609         return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
610                                                e6, e7, e8);
611     }
612 
613     /**
614      * Returns an unmodifiable set containing nine elements.
615      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
616      *
617      * @param <E> the {@code Set}'s element type
618      * @param e1 the first element
619      * @param e2 the second element
620      * @param e3 the third element
621      * @param e4 the fourth element
622      * @param e5 the fifth element
623      * @param e6 the sixth element
624      * @param e7 the seventh element
625      * @param e8 the eighth element
626      * @param e9 the ninth element
627      * @return a {@code Set} containing the specified elements
628      * @throws IllegalArgumentException if there are any duplicate elements
629      * @throws NullPointerException if an element is {@code null}
630      *
631      * @since 9
632      */
of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9)633     static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) {
634         return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
635                                                e6, e7, e8, e9);
636     }
637 
638     /**
639      * Returns an unmodifiable set containing ten elements.
640      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
641      *
642      * @param <E> the {@code Set}'s element type
643      * @param e1 the first element
644      * @param e2 the second element
645      * @param e3 the third element
646      * @param e4 the fourth element
647      * @param e5 the fifth element
648      * @param e6 the sixth element
649      * @param e7 the seventh element
650      * @param e8 the eighth element
651      * @param e9 the ninth element
652      * @param e10 the tenth element
653      * @return a {@code Set} containing the specified elements
654      * @throws IllegalArgumentException if there are any duplicate elements
655      * @throws NullPointerException if an element is {@code null}
656      *
657      * @since 9
658      */
of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10)659     static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10) {
660         return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
661                                                e6, e7, e8, e9, e10);
662     }
663 
664     /**
665      * Returns an unmodifiable set containing an arbitrary number of elements.
666      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
667      *
668      * @apiNote
669      * This method also accepts a single array as an argument. The element type of
670      * the resulting set will be the component type of the array, and the size of
671      * the set will be equal to the length of the array. To create a set with
672      * a single element that is an array, do the following:
673      *
674      * <pre>{@code
675      *     String[] array = ... ;
676      *     Set<String[]> list = Set.<String[]>of(array);
677      * }</pre>
678      *
679      * This will cause the {@link Set#of(Object) Set.of(E)} method
680      * to be invoked instead.
681      *
682      * @param <E> the {@code Set}'s element type
683      * @param elements the elements to be contained in the set
684      * @return a {@code Set} containing the specified elements
685      * @throws IllegalArgumentException if there are any duplicate elements
686      * @throws NullPointerException if an element is {@code null} or if the array is {@code null}
687      *
688      * @since 9
689      */
690     @SafeVarargs
691     @SuppressWarnings("varargs")
of(E... elements)692     static <E> Set<E> of(E... elements) {
693         switch (elements.length) { // implicit null check of elements
694             case 0:
695                 return ImmutableCollections.emptySet();
696             case 1:
697                 return new ImmutableCollections.Set12<>(elements[0]);
698             case 2:
699                 return new ImmutableCollections.Set12<>(elements[0], elements[1]);
700             default:
701                 return new ImmutableCollections.SetN<>(elements);
702         }
703     }
704 
705     /**
706      * Returns an <a href="#unmodifiable">unmodifiable Set</a> containing the elements
707      * of the given Collection. The given Collection must not be null, and it must not
708      * contain any null elements. If the given Collection contains duplicate elements,
709      * an arbitrary element of the duplicates is preserved. If the given Collection is
710      * subsequently modified, the returned Set will not reflect such modifications.
711      *
712      * @implNote
713      * If the given Collection is an <a href="#unmodifiable">unmodifiable Set</a>,
714      * calling copyOf will generally not create a copy.
715      *
716      * @param <E> the {@code Set}'s element type
717      * @param coll a {@code Collection} from which elements are drawn, must be non-null
718      * @return a {@code Set} containing the elements of the given {@code Collection}
719      * @throws NullPointerException if coll is null, or if it contains any nulls
720      * @since 10
721      */
722     @SuppressWarnings("unchecked")
copyOf(Collection<? extends E> coll)723     static <E> Set<E> copyOf(Collection<? extends E> coll) {
724         if (coll instanceof ImmutableCollections.AbstractImmutableSet) {
725             return (Set<E>)coll;
726         } else {
727             return (Set<E>)Set.of(new HashSet<>(coll).toArray());
728         }
729     }
730 }
731