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}/../technotes/guides/collections/index.html"> 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 */ size()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 */ isEmpty()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 */ contains(Object o)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 */ iterator()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 */ toArray()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 */ toArray(T[] a)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 */ add(E e)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 */ remove(Object o)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 */ containsAll(Collection<?> c)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 */ addAll(Collection<? extends E> c)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 */ retainAll(Collection<?> c)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 */ removeAll(Collection<?> c)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 */ clear()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 */ equals(Object o)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 */ hashCode()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 spliterator()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 */ of()450 static <E> Set<E> of() { 451 return ImmutableCollections.Set0.instance(); 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 */ of(E e1)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 */ of(E e1, E e2)482 static <E> Set<E> of(E e1, E e2) { 483 return new ImmutableCollections.Set2<>(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 */ of(E e1, E e2, E e3)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 */ of(E e1, E e2, E e3, E e4)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 */ of(E e1, E e2, E e3, E e4, E e5)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 */ of(E e1, E e2, E e3, E e4, E e5, E e6)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 */ of(E e1, E e2, E e3, E e4, E e5, E e6, E e7)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 */ of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8)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 */ of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9)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 */ of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10)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") of(E... elements)691 static <E> Set<E> of(E... elements) { 692 switch (elements.length) { // implicit null check of elements 693 case 0: 694 return ImmutableCollections.Set0.instance(); 695 case 1: 696 return new ImmutableCollections.Set1<>(elements[0]); 697 case 2: 698 return new ImmutableCollections.Set2<>(elements[0], elements[1]); 699 default: 700 return new ImmutableCollections.SetN<>(elements); 701 } 702 } 703 704 /** 705 * Returns an <a href="#unmodifiable">unmodifiable Set</a> containing the elements 706 * of the given Collection. The given Collection must not be null, and it must not 707 * contain any null elements. If the given Collection contains duplicate elements, 708 * an arbitrary element of the duplicates is preserved. If the given Collection is 709 * subsequently modified, the returned Set will not reflect such modifications. 710 * 711 * @implNote 712 * If the given Collection is an <a href="#unmodifiable">unmodifiable Set</a>, 713 * calling copyOf will generally not create a copy. 714 * 715 * @param <E> the {@code Set}'s element type 716 * @param coll a {@code Collection} from which elements are drawn, must be non-null 717 * @return a {@code Set} containing the elements of the given {@code Collection} 718 * @throws NullPointerException if coll is null, or if it contains any nulls 719 * @since 10 720 */ 721 @SuppressWarnings("unchecked") copyOf(Collection<? extends E> coll)722 static <E> Set<E> copyOf(Collection<? extends E> coll) { 723 if (coll instanceof ImmutableCollections.AbstractImmutableSet) { 724 return (Set<E>)coll; 725 } else { 726 return (Set<E>)Set.of(new HashSet<>(coll).toArray()); 727 } 728 } 729 } 730