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="immutable">Immutable Set Static Factory Methods</a></h2>
  67  * <p>The {@link Set#of(Object...) Set.of()} static factory methods
  68  * provide a convenient way to create immutable sets. The {@code Set}
  69  * instances created by these methods have the following characteristics:
  70  *
  71  * <ul>
  72  * <li>They are <em>structurally immutable</em>. Elements cannot be added or
  73  * removed. Calling any mutator method will always cause
  74  * {@code UnsupportedOperationException} to be thrown.
  75  * However, if the contained elements are themselves mutable, this may cause the
  76  * Set to behave inconsistently or its contents to appear to change.
  77  * <li>They disallow {@code null} elements. Attempts to create them with
  78  * {@code null} elements result in {@code NullPointerException}.
  79  * <li>They are serializable if all elements are serializable.
  80  * <li>They reject duplicate elements at creation time. Duplicate elements
  81  * passed to a static factory method result in {@code IllegalArgumentException}.
  82  * <li>The iteration order of set elements is unspecified and is subject to change.
  83  * <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
  84  * Callers should make no assumptions about the identity of the returned instances.
  85  * Factories are free to create new instances or reuse existing ones. Therefore,
  86  * identity-sensitive operations on these instances (reference equality ({@code ==}),
  87  * identity hash code, and synchronization) are unreliable and should be avoided.
  88  * <li>They are serialized as specified on the
  89  * <a href="{@docRoot}/serialized-form.html#java.util.CollSer">Serialized Form</a>
  90  * page.
  91  * </ul>
  92  *
  93  * <p>This interface is a member of the
  94  * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
  95  * Java Collections Framework</a>.
  96  *
  97  * @param <E> the type of elements maintained by this set
  98  *
  99  * @author  Josh Bloch
 100  * @author  Neal Gafter
 101  * @see Collection
 102  * @see List
 103  * @see SortedSet
 104  * @see HashSet
 105  * @see TreeSet
 106  * @see AbstractSet
 107  * @see Collections#singleton(java.lang.Object)
 108  * @see Collections#EMPTY_SET
 109  * @since 1.2
 110  */
 111 
 112 public interface Set<E> extends Collection<E> {
 113     // Query Operations
 114 
 115     /**
 116      * Returns the number of elements in this set (its cardinality).  If this
 117      * set contains more than {@code Integer.MAX_VALUE} elements, returns
 118      * {@code Integer.MAX_VALUE}.
 119      *
 120      * @return the number of elements in this set (its cardinality)
 121      */
 122     int size();
 123 
 124     /**
 125      * Returns {@code true} if this set contains no elements.
 126      *
 127      * @return {@code true} if this set contains no elements
 128      */
 129     boolean isEmpty();
 130 
 131     /**
 132      * Returns {@code true} if this set contains the specified element.
 133      * More formally, returns {@code true} if and only if this set
 134      * contains an element {@code e} such that
 135      * {@code Objects.equals(o, e)}.
 136      *
 137      * @param o element whose presence in this set is to be tested
 138      * @return {@code true} if this set contains the specified element
 139      * @throws ClassCastException if the type of the specified element
 140      *         is incompatible with this set
 141      * (<a href="Collection.html#optional-restrictions">optional</a>)
 142      * @throws NullPointerException if the specified element is null and this
 143      *         set does not permit null elements
 144      * (<a href="Collection.html#optional-restrictions">optional</a>)
 145      */
 146     boolean contains(Object o);
 147 
 148     /**
 149      * Returns an iterator over the elements in this set.  The elements are
 150      * returned in no particular order (unless this set is an instance of some
 151      * class that provides a guarantee).
 152      *
 153      * @return an iterator over the elements in this set
 154      */
 155     Iterator<E> iterator();
 156 
 157     /**
 158      * Returns an array containing all of the elements in this set.
 159      * If this set makes any guarantees as to what order its elements
 160      * are returned by its iterator, this method must return the
 161      * elements in the same order.
 162      *
 163      * <p>The returned array will be "safe" in that no references to it
 164      * are maintained by this set.  (In other words, this method must
 165      * allocate a new array even if this set is backed by an array).
 166      * The caller is thus free to modify the returned array.
 167      *
 168      * <p>This method acts as bridge between array-based and collection-based
 169      * APIs.
 170      *
 171      * @return an array containing all the elements in this set
 172      */
 173     Object[] toArray();
 174 
 175     /**
 176      * Returns an array containing all of the elements in this set; the
 177      * runtime type of the returned array is that of the specified array.
 178      * If the set fits in the specified array, it is returned therein.
 179      * Otherwise, a new array is allocated with the runtime type of the
 180      * specified array and the size of this set.
 181      *
 182      * <p>If this set fits in the specified array with room to spare
 183      * (i.e., the array has more elements than this set), the element in
 184      * the array immediately following the end of the set is set to
 185      * {@code null}.  (This is useful in determining the length of this
 186      * set <i>only</i> if the caller knows that this set does not contain
 187      * any null elements.)
 188      *
 189      * <p>If this set makes any guarantees as to what order its elements
 190      * are returned by its iterator, this method must return the elements
 191      * in the same order.
 192      *
 193      * <p>Like the {@link #toArray()} method, this method acts as bridge between
 194      * array-based and collection-based APIs.  Further, this method allows
 195      * precise control over the runtime type of the output array, and may,
 196      * under certain circumstances, be used to save allocation costs.
 197      *
 198      * <p>Suppose {@code x} is a set known to contain only strings.
 199      * The following code can be used to dump the set into a newly allocated
 200      * array of {@code String}:
 201      *
 202      * <pre>
 203      *     String[] y = x.toArray(new String[0]);</pre>
 204      *
 205      * Note that {@code toArray(new Object[0])} is identical in function to
 206      * {@code toArray()}.
 207      *
 208      * @param a the array into which the elements of this set are to be
 209      *        stored, if it is big enough; otherwise, a new array of the same
 210      *        runtime type is allocated for this purpose.
 211      * @return an array containing all the elements in this set
 212      * @throws ArrayStoreException if the runtime type of the specified array
 213      *         is not a supertype of the runtime type of every element in this
 214      *         set
 215      * @throws NullPointerException if the specified array is null
 216      */
 217     <T> T[] toArray(T[] a);
 218 
 219 
 220     // Modification Operations
 221 
 222     /**
 223      * Adds the specified element to this set if it is not already present
 224      * (optional operation).  More formally, adds the specified element
 225      * {@code e} to this set if the set contains no element {@code e2}
 226      * such that
 227      * {@code Objects.equals(e, e2)}.
 228      * If this set already contains the element, the call leaves the set
 229      * unchanged and returns {@code false}.  In combination with the
 230      * restriction on constructors, this ensures that sets never contain
 231      * duplicate elements.
 232      *
 233      * <p>The stipulation above does not imply that sets must accept all
 234      * elements; sets may refuse to add any particular element, including
 235      * {@code null}, and throw an exception, as described in the
 236      * specification for {@link Collection#add Collection.add}.
 237      * Individual set implementations should clearly document any
 238      * restrictions on the elements that they may contain.
 239      *
 240      * @param e element to be added to this set
 241      * @return {@code true} if this set did not already contain the specified
 242      *         element
 243      * @throws UnsupportedOperationException if the {@code add} operation
 244      *         is not supported by this set
 245      * @throws ClassCastException if the class of the specified element
 246      *         prevents it from being added to this set
 247      * @throws NullPointerException if the specified element is null and this
 248      *         set does not permit null elements
 249      * @throws IllegalArgumentException if some property of the specified element
 250      *         prevents it from being added to this set
 251      */
 252     boolean add(E e);
 253 
 254 
 255     /**
 256      * Removes the specified element from this set if it is present
 257      * (optional operation).  More formally, removes an element {@code e}
 258      * such that
 259      * {@code Objects.equals(o, e)}, if
 260      * this set contains such an element.  Returns {@code true} if this set
 261      * contained the element (or equivalently, if this set changed as a
 262      * result of the call).  (This set will not contain the element once the
 263      * call returns.)
 264      *
 265      * @param o object to be removed from this set, if present
 266      * @return {@code true} if this set contained the specified element
 267      * @throws ClassCastException if the type of the specified element
 268      *         is incompatible with this set
 269      * (<a href="Collection.html#optional-restrictions">optional</a>)
 270      * @throws NullPointerException if the specified element is null and this
 271      *         set does not permit null elements
 272      * (<a href="Collection.html#optional-restrictions">optional</a>)
 273      * @throws UnsupportedOperationException if the {@code remove} operation
 274      *         is not supported by this set
 275      */
 276     boolean remove(Object o);
 277 
 278 
 279     // Bulk Operations
 280 
 281     /**
 282      * Returns {@code true} if this set contains all of the elements of the
 283      * specified collection.  If the specified collection is also a set, this
 284      * method returns {@code true} if it is a <i>subset</i> of this set.
 285      *
 286      * @param  c collection to be checked for containment in this set
 287      * @return {@code true} if this set contains all of the elements of the
 288      *         specified collection
 289      * @throws ClassCastException if the types of one or more elements
 290      *         in the specified collection are incompatible with this
 291      *         set
 292      * (<a href="Collection.html#optional-restrictions">optional</a>)
 293      * @throws NullPointerException if the specified collection contains one
 294      *         or more null elements and this set does not permit null
 295      *         elements
 296      * (<a href="Collection.html#optional-restrictions">optional</a>),
 297      *         or if the specified collection is null
 298      * @see    #contains(Object)
 299      */
 300     boolean containsAll(Collection<?> c);
 301 
 302     /**
 303      * Adds all of the elements in the specified collection to this set if
 304      * they're not already present (optional operation).  If the specified
 305      * collection is also a set, the {@code addAll} operation effectively
 306      * modifies this set so that its value is the <i>union</i> of the two
 307      * sets.  The behavior of this operation is undefined if the specified
 308      * collection is modified while the operation is in progress.
 309      *
 310      * @param  c collection containing elements to be added to this set
 311      * @return {@code true} if this set changed as a result of the call
 312      *
 313      * @throws UnsupportedOperationException if the {@code addAll} operation
 314      *         is not supported by this set
 315      * @throws ClassCastException if the class of an element of the
 316      *         specified collection prevents it from being added to this set
 317      * @throws NullPointerException if the specified collection contains one
 318      *         or more null elements and this set does not permit null
 319      *         elements, or if the specified collection is null
 320      * @throws IllegalArgumentException if some property of an element of the
 321      *         specified collection prevents it from being added to this set
 322      * @see #add(Object)
 323      */
 324     boolean addAll(Collection<? extends E> c);
 325 
 326     /**
 327      * Retains only the elements in this set that are contained in the
 328      * specified collection (optional operation).  In other words, removes
 329      * from this set all of its elements that are not contained in the
 330      * specified collection.  If the specified collection is also a set, this
 331      * operation effectively modifies this set so that its value is the
 332      * <i>intersection</i> of the two sets.
 333      *
 334      * @param  c collection containing elements to be retained in this set
 335      * @return {@code true} if this set changed as a result of the call
 336      * @throws UnsupportedOperationException if the {@code retainAll} operation
 337      *         is not supported by this set
 338      * @throws ClassCastException if the class of an element of this set
 339      *         is incompatible with the specified collection
 340      * (<a href="Collection.html#optional-restrictions">optional</a>)
 341      * @throws NullPointerException if this set contains a null element and the
 342      *         specified collection does not permit null elements
 343      *         (<a href="Collection.html#optional-restrictions">optional</a>),
 344      *         or if the specified collection is null
 345      * @see #remove(Object)
 346      */
 347     boolean retainAll(Collection<?> c);
 348 
 349     /**
 350      * Removes from this set all of its elements that are contained in the
 351      * specified collection (optional operation).  If the specified
 352      * collection is also a set, this operation effectively modifies this
 353      * set so that its value is the <i>asymmetric set difference</i> of
 354      * the two sets.
 355      *
 356      * @param  c collection containing elements to be removed from this set
 357      * @return {@code true} if this set changed as a result of the call
 358      * @throws UnsupportedOperationException if the {@code removeAll} operation
 359      *         is not supported by this set
 360      * @throws ClassCastException if the class of an element of this set
 361      *         is incompatible with the specified collection
 362      * (<a href="Collection.html#optional-restrictions">optional</a>)
 363      * @throws NullPointerException if this set contains a null element and the
 364      *         specified collection does not permit null elements
 365      *         (<a href="Collection.html#optional-restrictions">optional</a>),
 366      *         or if the specified collection is null
 367      * @see #remove(Object)
 368      * @see #contains(Object)
 369      */
 370     boolean removeAll(Collection<?> c);
 371 
 372     /**
 373      * Removes all of the elements from this set (optional operation).
 374      * The set will be empty after this call returns.
 375      *
 376      * @throws UnsupportedOperationException if the {@code clear} method
 377      *         is not supported by this set
 378      */
 379     void clear();
 380 
 381 
 382     // Comparison and hashing
 383 
 384     /**
 385      * Compares the specified object with this set for equality.  Returns
 386      * {@code true} if the specified object is also a set, the two sets
 387      * have the same size, and every member of the specified set is
 388      * contained in this set (or equivalently, every member of this set is
 389      * contained in the specified set).  This definition ensures that the
 390      * equals method works properly across different implementations of the
 391      * set interface.
 392      *
 393      * @param o object to be compared for equality with this set
 394      * @return {@code true} if the specified object is equal to this set
 395      */
 396     boolean equals(Object o);
 397 
 398     /**
 399      * Returns the hash code value for this set.  The hash code of a set is
 400      * defined to be the sum of the hash codes of the elements in the set,
 401      * where the hash code of a {@code null} element is defined to be zero.
 402      * This ensures that {@code s1.equals(s2)} implies that
 403      * {@code s1.hashCode()==s2.hashCode()} for any two sets {@code s1}
 404      * and {@code s2}, as required by the general contract of
 405      * {@link Object#hashCode}.
 406      *
 407      * @return the hash code value for this set
 408      * @see Object#equals(Object)
 409      * @see Set#equals(Object)
 410      */
 411     int hashCode();
 412 
 413     /**
 414      * Creates a {@code Spliterator} over the elements in this set.
 415      *
 416      * <p>The {@code Spliterator} reports {@link Spliterator#DISTINCT}.
 417      * Implementations should document the reporting of additional
 418      * characteristic values.
 419      *
 420      * @implSpec
 421      * The default implementation creates a
 422      * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator
 423      * from the set's {@code Iterator}.  The spliterator inherits the
 424      * <em>fail-fast</em> properties of the set's iterator.
 425      * <p>
 426      * The created {@code Spliterator} additionally reports
 427      * {@link Spliterator#SIZED}.
 428      *
 429      * @implNote
 430      * The created {@code Spliterator} additionally reports
 431      * {@link Spliterator#SUBSIZED}.
 432      *
 433      * @return a {@code Spliterator} over the elements in this set
 434      * @since 1.8
 435      */
 436     @Override
 437     default Spliterator<E> spliterator() {
 438         return Spliterators.spliterator(this, Spliterator.DISTINCT);
 439     }
 440 
 441     /**
 442      * Returns an immutable set containing zero elements.
 443      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
 444      *
 445      * @param <E> the {@code Set}'s element type
 446      * @return an empty {@code Set}
 447      *
 448      * @since 9
 449      */
 450     static <E> Set<E> of() {
 451         return ImmutableCollections.emptySet();
 452     }
 453 
 454     /**
 455      * Returns an immutable set containing one element.
 456      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
 457      *
 458      * @param <E> the {@code Set}'s element type
 459      * @param e1 the single element
 460      * @return a {@code Set} containing the specified element
 461      * @throws NullPointerException if the element is {@code null}
 462      *
 463      * @since 9
 464      */
 465     static <E> Set<E> of(E e1) {
 466         return new ImmutableCollections.Set1<>(e1);
 467     }
 468 
 469     /**
 470      * Returns an immutable set containing two elements.
 471      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
 472      *
 473      * @param <E> the {@code Set}'s element type
 474      * @param e1 the first element
 475      * @param e2 the second element
 476      * @return a {@code Set} containing the specified elements
 477      * @throws IllegalArgumentException if the elements are duplicates
 478      * @throws NullPointerException if an element is {@code null}
 479      *
 480      * @since 9
 481      */
 482     static <E> Set<E> of(E e1, E e2) {
 483         return new ImmutableCollections.SetN<>(e1, e2);
 484     }
 485 
 486     /**
 487      * Returns an immutable set containing three elements.
 488      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
 489      *
 490      * @param <E> the {@code Set}'s element type
 491      * @param e1 the first element
 492      * @param e2 the second element
 493      * @param e3 the third element
 494      * @return a {@code Set} containing the specified elements
 495      * @throws IllegalArgumentException if there are any duplicate elements
 496      * @throws NullPointerException if an element is {@code null}
 497      *
 498      * @since 9
 499      */
 500     static <E> Set<E> of(E e1, E e2, E e3) {
 501         return new ImmutableCollections.SetN<>(e1, e2, e3);
 502     }
 503 
 504     /**
 505      * Returns an immutable set containing four elements.
 506      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
 507      *
 508      * @param <E> the {@code Set}'s element type
 509      * @param e1 the first element
 510      * @param e2 the second element
 511      * @param e3 the third element
 512      * @param e4 the fourth element
 513      * @return a {@code Set} containing the specified elements
 514      * @throws IllegalArgumentException if there are any duplicate elements
 515      * @throws NullPointerException if an element is {@code null}
 516      *
 517      * @since 9
 518      */
 519     static <E> Set<E> of(E e1, E e2, E e3, E e4) {
 520         return new ImmutableCollections.SetN<>(e1, e2, e3, e4);
 521     }
 522 
 523     /**
 524      * Returns an immutable set containing five elements.
 525      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
 526      *
 527      * @param <E> the {@code Set}'s element type
 528      * @param e1 the first element
 529      * @param e2 the second element
 530      * @param e3 the third element
 531      * @param e4 the fourth element
 532      * @param e5 the fifth 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, E e5) {
 540         return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5);
 541     }
 542 
 543     /**
 544      * Returns an immutable set containing six elements.
 545      * See <a href="#immutable">Immutable Set Static Factory Methods</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      * @param e6 the sixth element
 554      * @return a {@code Set} containing the specified elements
 555      * @throws IllegalArgumentException if there are any duplicate elements
 556      * @throws NullPointerException if an element is {@code null}
 557      *
 558      * @since 9
 559      */
 560     static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6) {
 561         return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
 562                                                e6);
 563     }
 564 
 565     /**
 566      * Returns an immutable set containing seven elements.
 567      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
 568      *
 569      * @param <E> the {@code Set}'s element type
 570      * @param e1 the first element
 571      * @param e2 the second element
 572      * @param e3 the third element
 573      * @param e4 the fourth element
 574      * @param e5 the fifth element
 575      * @param e6 the sixth element
 576      * @param e7 the seventh element
 577      * @return a {@code Set} containing the specified elements
 578      * @throws IllegalArgumentException if there are any duplicate elements
 579      * @throws NullPointerException if an element is {@code null}
 580      *
 581      * @since 9
 582      */
 583     static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7) {
 584         return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
 585                                                e6, e7);
 586     }
 587 
 588     /**
 589      * Returns an immutable set containing eight elements.
 590      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
 591      *
 592      * @param <E> the {@code Set}'s element type
 593      * @param e1 the first element
 594      * @param e2 the second element
 595      * @param e3 the third element
 596      * @param e4 the fourth element
 597      * @param e5 the fifth element
 598      * @param e6 the sixth element
 599      * @param e7 the seventh element
 600      * @param e8 the eighth element
 601      * @return a {@code Set} containing the specified elements
 602      * @throws IllegalArgumentException if there are any duplicate elements
 603      * @throws NullPointerException if an element is {@code null}
 604      *
 605      * @since 9
 606      */
 607     static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) {
 608         return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
 609                                                e6, e7, e8);
 610     }
 611 
 612     /**
 613      * Returns an immutable set containing nine elements.
 614      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
 615      *
 616      * @param <E> the {@code Set}'s element type
 617      * @param e1 the first element
 618      * @param e2 the second element
 619      * @param e3 the third element
 620      * @param e4 the fourth element
 621      * @param e5 the fifth element
 622      * @param e6 the sixth element
 623      * @param e7 the seventh element
 624      * @param e8 the eighth element
 625      * @param e9 the ninth element
 626      * @return a {@code Set} containing the specified elements
 627      * @throws IllegalArgumentException if there are any duplicate elements
 628      * @throws NullPointerException if an element is {@code null}
 629      *
 630      * @since 9
 631      */
 632     static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) {
 633         return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
 634                                                e6, e7, e8, e9);
 635     }
 636 
 637     /**
 638      * Returns an immutable set containing ten elements.
 639      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
 640      *
 641      * @param <E> the {@code Set}'s element type
 642      * @param e1 the first element
 643      * @param e2 the second element
 644      * @param e3 the third element
 645      * @param e4 the fourth element
 646      * @param e5 the fifth element
 647      * @param e6 the sixth element
 648      * @param e7 the seventh element
 649      * @param e8 the eighth element
 650      * @param e9 the ninth element
 651      * @param e10 the tenth element
 652      * @return a {@code Set} containing the specified elements
 653      * @throws IllegalArgumentException if there are any duplicate elements
 654      * @throws NullPointerException if an element is {@code null}
 655      *
 656      * @since 9
 657      */
 658     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) {
 659         return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
 660                                                e6, e7, e8, e9, e10);
 661     }
 662 
 663     /**
 664      * Returns an immutable set containing an arbitrary number of elements.
 665      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
 666      *
 667      * @apiNote
 668      * This method also accepts a single array as an argument. The element type of
 669      * the resulting set will be the component type of the array, and the size of
 670      * the set will be equal to the length of the array. To create a set with
 671      * a single element that is an array, do the following:
 672      *
 673      * <pre>{@code
 674      *     String[] array = ... ;
 675      *     Set<String[]> list = Set.<String[]>of(array);
 676      * }</pre>
 677      *
 678      * This will cause the {@link Set#of(Object) Set.of(E)} method
 679      * to be invoked instead.
 680      *
 681      * @param <E> the {@code Set}'s element type
 682      * @param elements the elements to be contained in the set
 683      * @return a {@code Set} containing the specified elements
 684      * @throws IllegalArgumentException if there are any duplicate elements
 685      * @throws NullPointerException if an element is {@code null} or if the array is {@code null}
 686      *
 687      * @since 9
 688      */
 689     @SafeVarargs
 690     @SuppressWarnings("varargs")
 691     static <E> Set<E> of(E... elements) {
 692         switch (elements.length) { // implicit null check of elements
 693             case 0:
 694                 return ImmutableCollections.emptySet();
 695             case 1:
 696                 return new ImmutableCollections.Set1<>(elements[0]);
 697             default:
 698                 return new ImmutableCollections.SetN<>(elements);
 699         }
 700     }
 701 }