1 /*
2 * Copyright (c) 1997, 2019, 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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
277 boolean remove(Object o);
278
279
280 // Bulk Operations
281
282 /**
283 * Returns {@code true} if this set contains all of the elements
284 * in the specified collection. This operation uses the membership
285 * semantics of this set. If the specified collection is also a set,
286 * this method returns {@code true} if it is a <i>subset</i> of this set.
287 *
288 * @implNote
289 * {@inheritDoc}
290 *
291 * @param c collection to be checked for containment in this set
292 * @return {@code true} if this set contains all of the elements of the
293 * specified collection
294 * @throws ClassCastException if the types of one or more elements
295 * in the specified collection are incompatible with this
296 * set
297 * (<a href="Collection.html#optional-restrictions">optional</a>)
298 * @throws NullPointerException if the specified collection contains one
299 * or more null elements and this set does not permit null
300 * elements
301 * (<a href="Collection.html#optional-restrictions">optional</a>),
302 * or if the specified collection is null
303 * @see #contains(Object)
304 */
305 boolean containsAll(Collection<?> c);
306
307 /**
308 * Adds all of the elements in the specified collection to this set if
309 * they're not already present (optional operation). If the specified
310 * collection is also a set, the {@code addAll} operation effectively
311 * modifies this set so that its value is the <i>union</i> of the two
312 * sets. The behavior of this operation is undefined if the specified
313 * collection is modified while the operation is in progress.
314 *
315 * @param c collection containing elements to be added to this set
316 * @return {@code true} if this set changed as a result of the call
317 *
318 * @throws UnsupportedOperationException if the {@code addAll} operation
319 * is not supported by this set
320 * @throws ClassCastException if the class of an element of the
321 * specified collection prevents it from being added to this set
322 * @throws NullPointerException if the specified collection contains one
323 * or more null elements and this set does not permit null
324 * elements, or if the specified collection is null
325 * @throws IllegalArgumentException if some property of an element of the
326 * specified collection prevents it from being added to this set
327 * @see #add(Object)
328 */
329 boolean addAll(Collection<? extends E> c);
330
331 /**
332 * Retains only the elements in this set that are contained in the
333 * specified collection (optional operation). In other words, removes
334 * from this set all of its elements that are not contained in the
335 * specified collection. This operation uses the membership semantics of the
336 * specified collection. If the specified collection is also a set, this
337 * operation effectively modifies this set so that its value is the
338 * <i>intersection</i> of the two sets.
339 *
340 * @implNote
341 * {@inheritDoc}
342 *
343 * @param c collection containing elements to be retained in this set
344 * @return {@code true} if this set changed as a result of the call
345 * @throws UnsupportedOperationException if the {@code retainAll} operation
346 * is not supported by this set
347 * @throws ClassCastException if the class of an element of this set
348 * is incompatible with the specified collection
349 * (<a href="Collection.html#optional-restrictions">optional</a>)
350 * @throws NullPointerException if this set contains a null element and the
351 * specified collection does not permit null elements
352 * (<a href="Collection.html#optional-restrictions">optional</a>),
353 * or if the specified collection is null
354 * @see #remove(Object)
355 */
356 boolean retainAll(Collection<?> c);
357
358 /**
359 * Removes from this set all of its elements that are contained in the
360 * specified collection (optional operation). After this call returns,
361 * this set will contain no elements in common with the specified
362 * collection. This operation uses the membership semantics of the specified
363 * collection. If the specified collection is also a set, this operation
364 * effectively modifies this set so that its value is the <i>asymmetric
365 * set difference</i> of the two sets.
366 *
367 * @implNote
368 * {@inheritDoc}
369 *
370 * @param c collection containing elements to be removed from this set
371 * @return {@code true} if this set changed as a result of the call
372 * @throws UnsupportedOperationException if the {@code removeAll} operation
373 * is not supported by this set
374 * @throws ClassCastException if the class of an element of this set
375 * is incompatible with the specified collection
376 * (<a href="Collection.html#optional-restrictions">optional</a>)
377 * @throws NullPointerException if this set contains a null element and the
378 * specified collection does not permit null elements
379 * (<a href="Collection.html#optional-restrictions">optional</a>),
380 * or if the specified collection is null
381 * @see #remove(Object)
382 * @see #contains(Object)
383 */
384 boolean removeAll(Collection<?> c);
385
386 /**
387 * Removes all of the elements from this set (optional operation).
388 * The set will be empty after this call returns.
389 *
390 * @throws UnsupportedOperationException if the {@code clear} method
391 * is not supported by this set
392 */
393 void clear();
394
395
396 // Comparison and hashing
397
398 /**
399 * Compares the specified object with this set for equality. Returns
400 * {@code true} if the specified object is also a set, the two sets
401 * have the same size, and every member of the specified set is
402 * contained in this set. This operation uses the membership semantics
403 * of this set. This definition ensures that the {@code equals} method
404 * works properly across different implementations of the
405 * {@code Set} interface.
406 *
407 * @implNote
408 * Most implementations will call this set's {@code contains}
409 * method repeatedly. This may result in performance problems if the
410 * {@code contains} method has linear or worse performance.
411 *
412 * @param o object to be compared for equality with this set
413 * @return {@code true} if the specified object is equal to this set
414 */
415 boolean equals(Object o);
416
417 /**
418 * Returns the hash code value for this set. The hash code of a set is
419 * defined to be the sum of the hash codes of the elements in the set,
420 * where the hash code of a {@code null} element is defined to be zero.
421 * This ensures that {@code s1.equals(s2)} implies that
422 * {@code s1.hashCode()==s2.hashCode()} for any two sets {@code s1}
423 * and {@code s2}, as required by the general contract of
424 * {@link Object#hashCode}.
425 *
426 * @return the hash code value for this set
427 * @see Object#equals(Object)
428 * @see Set#equals(Object)
429 */
430 int hashCode();
431
432 /**
433 * Creates a {@code Spliterator} over the elements in this set.
434 *
435 * <p>The {@code Spliterator} reports {@link Spliterator#DISTINCT}.
436 * Implementations should document the reporting of additional
437 * characteristic values.
438 *
439 * @implSpec
440 * The default implementation creates a
441 * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator
442 * from the set's {@code Iterator}. The spliterator inherits the
443 * <em>fail-fast</em> properties of the set's iterator.
444 * <p>
445 * The created {@code Spliterator} additionally reports
446 * {@link Spliterator#SIZED}.
447 *
448 * @implNote
449 * The created {@code Spliterator} additionally reports
450 * {@link Spliterator#SUBSIZED}.
451 *
452 * @return a {@code Spliterator} over the elements in this set
453 * @since 1.8
454 */
455 @Override
456 default Spliterator<E> spliterator() {
457 return Spliterators.spliterator(this, Spliterator.DISTINCT);
458 }
459
460 /**
461 * Returns an unmodifiable set containing zero elements.
462 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
463 *
464 * @param <E> the {@code Set}'s element type
465 * @return an empty {@code Set}
466 *
467 * @since 9
468 */
469 @SuppressWarnings("unchecked")
470 static <E> Set<E> of() {
471 return (Set<E>) ImmutableCollections.SetN.EMPTY_SET;
472 }
473
474 /**
475 * Returns an unmodifiable set containing one element.
476 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
477 *
478 * @param <E> the {@code Set}'s element type
479 * @param e1 the single element
480 * @return a {@code Set} containing the specified element
481 * @throws NullPointerException if the element is {@code null}
482 *
483 * @since 9
484 */
485 static <E> Set<E> of(E e1) {
486 return new ImmutableCollections.Set12<>(e1);
487 }
488
489 /**
490 * Returns an unmodifiable set containing two elements.
491 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
492 *
493 * @param <E> the {@code Set}'s element type
494 * @param e1 the first element
495 * @param e2 the second element
496 * @return a {@code Set} containing the specified elements
497 * @throws IllegalArgumentException if the elements are duplicates
498 * @throws NullPointerException if an element is {@code null}
499 *
500 * @since 9
501 */
502 static <E> Set<E> of(E e1, E e2) {
503 return new ImmutableCollections.Set12<>(e1, e2);
504 }
505
506 /**
507 * Returns an unmodifiable set containing three elements.
508 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
509 *
510 * @param <E> the {@code Set}'s element type
511 * @param e1 the first element
512 * @param e2 the second element
513 * @param e3 the third 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 */
520 static <E> Set<E> of(E e1, E e2, E e3) {
521 return new ImmutableCollections.SetN<>(e1, e2, e3);
522 }
523
524 /**
525 * Returns an unmodifiable set containing four 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 * @return a {@code Set} containing the specified elements
534 * @throws IllegalArgumentException if there are any duplicate elements
535 * @throws NullPointerException if an element is {@code null}
536 *
537 * @since 9
538 */
539 static <E> Set<E> of(E e1, E e2, E e3, E e4) {
540 return new ImmutableCollections.SetN<>(e1, e2, e3, e4);
541 }
542
543 /**
544 * Returns an unmodifiable set containing five elements.
545 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
546 *
547 * @param <E> the {@code Set}'s element type
548 * @param e1 the first element
549 * @param e2 the second element
550 * @param e3 the third element
551 * @param e4 the fourth element
552 * @param e5 the fifth element
553 * @return a {@code Set} containing the specified elements
554 * @throws IllegalArgumentException if there are any duplicate elements
555 * @throws NullPointerException if an element is {@code null}
556 *
557 * @since 9
558 */
559 static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5) {
560 return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5);
561 }
562
563 /**
564 * Returns an unmodifiable set containing six elements.
565 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
566 *
567 * @param <E> the {@code Set}'s element type
568 * @param e1 the first element
569 * @param e2 the second element
570 * @param e3 the third element
571 * @param e4 the fourth element
572 * @param e5 the fifth element
573 * @param e6 the sixth element
574 * @return a {@code Set} containing the specified elements
575 * @throws IllegalArgumentException if there are any duplicate elements
576 * @throws NullPointerException if an element is {@code null}
577 *
578 * @since 9
579 */
580 static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6) {
581 return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
582 e6);
583 }
584
585 /**
586 * Returns an unmodifiable set containing seven elements.
587 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
588 *
589 * @param <E> the {@code Set}'s element type
590 * @param e1 the first element
591 * @param e2 the second element
592 * @param e3 the third element
593 * @param e4 the fourth element
594 * @param e5 the fifth element
595 * @param e6 the sixth element
596 * @param e7 the seventh element
597 * @return a {@code Set} containing the specified elements
598 * @throws IllegalArgumentException if there are any duplicate elements
599 * @throws NullPointerException if an element is {@code null}
600 *
601 * @since 9
602 */
603 static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7) {
604 return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
605 e6, e7);
606 }
607
608 /**
609 * Returns an unmodifiable set containing eight elements.
610 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
611 *
612 * @param <E> the {@code Set}'s element type
613 * @param e1 the first element
614 * @param e2 the second element
615 * @param e3 the third element
616 * @param e4 the fourth element
617 * @param e5 the fifth element
618 * @param e6 the sixth element
619 * @param e7 the seventh element
620 * @param e8 the eighth element
621 * @return a {@code Set} containing the specified elements
622 * @throws IllegalArgumentException if there are any duplicate elements
623 * @throws NullPointerException if an element is {@code null}
624 *
625 * @since 9
626 */
627 static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) {
628 return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
629 e6, e7, e8);
630 }
631
632 /**
633 * Returns an unmodifiable set containing nine elements.
634 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
635 *
636 * @param <E> the {@code Set}'s element type
637 * @param e1 the first element
638 * @param e2 the second element
639 * @param e3 the third element
640 * @param e4 the fourth element
641 * @param e5 the fifth element
642 * @param e6 the sixth element
643 * @param e7 the seventh element
644 * @param e8 the eighth element
645 * @param e9 the ninth element
646 * @return a {@code Set} containing the specified elements
647 * @throws IllegalArgumentException if there are any duplicate elements
648 * @throws NullPointerException if an element is {@code null}
649 *
650 * @since 9
651 */
652 static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) {
653 return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
654 e6, e7, e8, e9);
655 }
656
657 /**
658 * Returns an unmodifiable set containing ten elements.
659 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
660 *
661 * @param <E> the {@code Set}'s element type
662 * @param e1 the first element
663 * @param e2 the second element
664 * @param e3 the third element
665 * @param e4 the fourth element
666 * @param e5 the fifth element
667 * @param e6 the sixth element
668 * @param e7 the seventh element
669 * @param e8 the eighth element
670 * @param e9 the ninth element
671 * @param e10 the tenth element
672 * @return a {@code Set} containing the specified elements
673 * @throws IllegalArgumentException if there are any duplicate elements
674 * @throws NullPointerException if an element is {@code null}
675 *
676 * @since 9
677 */
678 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) {
679 return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
680 e6, e7, e8, e9, e10);
681 }
682
683 /**
684 * Returns an unmodifiable set containing an arbitrary number of elements.
685 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
686 *
687 * @apiNote
688 * This method also accepts a single array as an argument. The element type of
689 * the resulting set will be the component type of the array, and the size of
690 * the set will be equal to the length of the array. To create a set with
691 * a single element that is an array, do the following:
692 *
693 * <pre>{@code
694 * String[] array = ... ;
695 * Set<String[]> list = Set.<String[]>of(array);
696 * }</pre>
697 *
698 * This will cause the {@link Set#of(Object) Set.of(E)} method
699 * to be invoked instead.
700 *
701 * @param <E> the {@code Set}'s element type
702 * @param elements the elements to be contained in the set
703 * @return a {@code Set} containing the specified elements
704 * @throws IllegalArgumentException if there are any duplicate elements
705 * @throws NullPointerException if an element is {@code null} or if the array is {@code null}
706 *
707 * @since 9
708 */
709 @SafeVarargs
710 @SuppressWarnings("varargs")
711 static <E> Set<E> of(E... elements) {
712 switch (elements.length) { // implicit null check of elements
713 case 0:
714 @SuppressWarnings("unchecked")
715 var set = (Set<E>) ImmutableCollections.SetN.EMPTY_SET;
716 return set;
717 case 1:
718 return new ImmutableCollections.Set12<>(elements[0]);
719 case 2:
720 return new ImmutableCollections.Set12<>(elements[0], elements[1]);
721 default:
722 return new ImmutableCollections.SetN<>(elements);
723 }
724 }
725
726 /**
727 * Returns an <a href="#unmodifiable">unmodifiable Set</a> containing the elements
728 * of the given Collection. The given Collection must not be null, and it must not
729 * contain any null elements. If the given Collection contains duplicate elements,
730 * an arbitrary element of the duplicates is preserved. If the given Collection is
731 * subsequently modified, the returned Set will not reflect such modifications.
732 *
733 * @implNote
734 * If the given Collection is an <a href="#unmodifiable">unmodifiable Set</a>,
735 * calling copyOf will generally not create a copy.
736 *
737 * @param <E> the {@code Set}'s element type
738 * @param coll a {@code Collection} from which elements are drawn, must be non-null
739 * @return a {@code Set} containing the elements of the given {@code Collection}
740 * @throws NullPointerException if coll is null, or if it contains any nulls
741 * @since 10
742 */
743 @SuppressWarnings("unchecked")
744 static <E> Set<E> copyOf(Collection<? extends E> coll) {
745 if (coll instanceof ImmutableCollections.AbstractImmutableSet) {
746 return (Set<E>)coll;
747 } else {
748 return (Set<E>)Set.of(new HashSet<>(coll).toArray());
749 }
750 }
751 }