1 /*
   2  * Copyright (c) 1997, 2017, 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/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 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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
 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      */
 451     static <E> Set<E> of() {
 452         return ImmutableCollections.Set0.instance();
 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      */
 466     static <E> Set<E> of(E e1) {
 467         return new ImmutableCollections.Set1<>(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      */
 483     static <E> Set<E> of(E e1, E e2) {
 484         return new ImmutableCollections.Set2<>(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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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      */
 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")
 692     static <E> Set<E> of(E... elements) {
 693         switch (elements.length) { // implicit null check of elements
 694             case 0:
 695                 return ImmutableCollections.Set0.instance();
 696             case 1:
 697                 return new ImmutableCollections.Set1<>(elements[0]);
 698             case 2:
 699                 return new ImmutableCollections.Set2<>(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. Duplicate elements are permitted, in which case an
 709      * 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      * @param <E> the {@code Set}'s element type
 713      * @param coll the collection from which elements are drawn, must be non-null
 714      * @return the new {@code Set}
 715      * @throws NullPointerException if coll is null, or if it contains any nulls
 716      * @since 10
 717      */
 718     @SuppressWarnings("unchecked")
 719     static <E> Set<E> copyOf(Collection<? extends E> coll) {
 720         if (coll instanceof ImmutableCollections.AbstractImmutableSet) {
 721             return (Set<E>)coll;
 722         } else {
 723             return (Set<E>)Set.of(coll.stream().distinct().toArray());
 724         }
 725     }
 726 }