1 /* 2 * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.util; 27 28 /** 29 * A collection that contains no duplicate elements. More formally, sets 30 * contain no pair of elements {@code e1} and {@code e2} such that 31 * {@code e1.equals(e2)}, and at most one null element. As implied by 32 * its name, this interface models the mathematical <i>set</i> abstraction. 33 * 34 * <p>The {@code Set} interface places additional stipulations, beyond those 35 * inherited from the {@code Collection} interface, on the contracts of all 36 * constructors and on the contracts of the {@code add}, {@code equals} and 37 * {@code hashCode} methods. Declarations for other inherited methods are 38 * also included here for convenience. (The specifications accompanying these 39 * declarations have been tailored to the {@code Set} interface, but they do 40 * not contain any additional stipulations.) 41 * 42 * <p>The additional stipulation on constructors is, not surprisingly, 43 * that all constructors must create a set that contains no duplicate elements 44 * (as defined above). 45 * 46 * <p>Note: Great care must be exercised if mutable objects are used as set 47 * elements. The behavior of a set is not specified if the value of an object 48 * is changed in a manner that affects {@code equals} comparisons while the 49 * object is an element in the set. A special case of this prohibition is 50 * that it is not permissible for a set to contain itself as an element. 51 * 52 * <p>Some set implementations have restrictions on the elements that 53 * they may contain. For example, some implementations prohibit null elements, 54 * and some have restrictions on the types of their elements. Attempting to 55 * add an ineligible element throws an unchecked exception, typically 56 * {@code NullPointerException} or {@code ClassCastException}. Attempting 57 * to query the presence of an ineligible element may throw an exception, 58 * or it may simply return false; some implementations will exhibit the former 59 * behavior and some will exhibit the latter. More generally, attempting an 60 * operation on an ineligible element whose completion would not result in 61 * the insertion of an ineligible element into the set may throw an 62 * exception or it may succeed, at the option of the implementation. 63 * Such exceptions are marked as "optional" in the specification for this 64 * interface. 65 * 66 * <h2><a id="unmodifiable">Unmodifiable Sets</a></h2> 67 * <p>The {@link Set#of(Object...) Set.of} and 68 * {@link Set#copyOf Set.copyOf} static factory methods 69 * provide a convenient way to create unmodifiable sets. The {@code Set} 70 * instances created by these methods have the following characteristics: 71 * 72 * <ul> 73 * <li>They are <a href="Collection.html#unmodifiable"><i>unmodifiable</i></a>. Elements cannot 74 * be added or removed. Calling any mutator method on the Set 75 * will always cause {@code UnsupportedOperationException} to be thrown. 76 * However, if the contained elements are themselves mutable, this may cause the 77 * Set to behave inconsistently or its contents to appear to change. 78 * <li>They disallow {@code null} elements. Attempts to create them with 79 * {@code null} elements result in {@code NullPointerException}. 80 * <li>They are serializable if all elements are serializable. 81 * <li>They reject duplicate elements at creation time. Duplicate elements 82 * passed to a static factory method result in {@code IllegalArgumentException}. 83 * <li>The iteration order of set elements is unspecified and is subject to change. 84 * <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>. 85 * Callers should make no assumptions about the identity of the returned instances. 86 * Factories are free to create new instances or reuse existing ones. Therefore, 87 * identity-sensitive operations on these instances (reference equality ({@code ==}), 88 * identity hash code, and synchronization) are unreliable and should be avoided. 89 * <li>They are serialized as specified on the 90 * <a href="{@docRoot}/serialized-form.html#java.util.CollSer">Serialized Form</a> 91 * page. 92 * </ul> 93 * 94 * <p>This interface is a member of the 95 * <a href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework"> 96 * Java Collections Framework</a>. 97 * 98 * @param <E> the type of elements maintained by this set 99 * 100 * @author Josh Bloch 101 * @author Neal Gafter 102 * @see Collection 103 * @see List 104 * @see SortedSet 105 * @see HashSet 106 * @see TreeSet 107 * @see AbstractSet 108 * @see Collections#singleton(java.lang.Object) 109 * @see Collections#EMPTY_SET 110 * @since 1.2 111 */ 112 113 public interface Set<E> extends Collection<E> { 114 // Query Operations 115 116 /** 117 * Returns the number of elements in this set (its cardinality). If this 118 * set contains more than {@code Integer.MAX_VALUE} elements, returns 119 * {@code Integer.MAX_VALUE}. 120 * 121 * @return the number of elements in this set (its cardinality) 122 */ 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 @SuppressWarnings("unchecked") 452 static <E> Set<E> of() { 453 return (Set<E>) ImmutableCollections.SetN.EMPTY_SET; 454 } 455 456 /** 457 * Returns an unmodifiable set containing one element. 458 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details. 459 * 460 * @param <E> the {@code Set}'s element type 461 * @param e1 the single element 462 * @return a {@code Set} containing the specified element 463 * @throws NullPointerException if the element is {@code null} 464 * 465 * @since 9 466 */ 467 static <E> Set<E> of(E e1) { 468 return new ImmutableCollections.Set12<>(e1); 469 } 470 471 /** 472 * Returns an unmodifiable set containing two elements. 473 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details. 474 * 475 * @param <E> the {@code Set}'s element type 476 * @param e1 the first element 477 * @param e2 the second element 478 * @return a {@code Set} containing the specified elements 479 * @throws IllegalArgumentException if the elements are duplicates 480 * @throws NullPointerException if an element is {@code null} 481 * 482 * @since 9 483 */ 484 static <E> Set<E> of(E e1, E e2) { 485 return new ImmutableCollections.Set12<>(e1, e2); 486 } 487 488 /** 489 * Returns an unmodifiable set containing three elements. 490 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details. 491 * 492 * @param <E> the {@code Set}'s element type 493 * @param e1 the first element 494 * @param e2 the second element 495 * @param e3 the third element 496 * @return a {@code Set} containing the specified elements 497 * @throws IllegalArgumentException if there are any duplicate elements 498 * @throws NullPointerException if an element is {@code null} 499 * 500 * @since 9 501 */ 502 static <E> Set<E> of(E e1, E e2, E e3) { 503 return new ImmutableCollections.SetN<>(e1, e2, e3); 504 } 505 506 /** 507 * Returns an unmodifiable set containing four elements. 508 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details. 509 * 510 * @param <E> the {@code Set}'s element type 511 * @param e1 the first element 512 * @param e2 the second element 513 * @param e3 the third element 514 * @param e4 the fourth element 515 * @return a {@code Set} containing the specified elements 516 * @throws IllegalArgumentException if there are any duplicate elements 517 * @throws NullPointerException if an element is {@code null} 518 * 519 * @since 9 520 */ 521 static <E> Set<E> of(E e1, E e2, E e3, E e4) { 522 return new ImmutableCollections.SetN<>(e1, e2, e3, e4); 523 } 524 525 /** 526 * Returns an unmodifiable set containing five elements. 527 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details. 528 * 529 * @param <E> the {@code Set}'s element type 530 * @param e1 the first element 531 * @param e2 the second element 532 * @param e3 the third element 533 * @param e4 the fourth element 534 * @param e5 the fifth element 535 * @return a {@code Set} containing the specified elements 536 * @throws IllegalArgumentException if there are any duplicate elements 537 * @throws NullPointerException if an element is {@code null} 538 * 539 * @since 9 540 */ 541 static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5) { 542 return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5); 543 } 544 545 /** 546 * Returns an unmodifiable set containing six elements. 547 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details. 548 * 549 * @param <E> the {@code Set}'s element type 550 * @param e1 the first element 551 * @param e2 the second element 552 * @param e3 the third element 553 * @param e4 the fourth element 554 * @param e5 the fifth element 555 * @param e6 the sixth element 556 * @return a {@code Set} containing the specified elements 557 * @throws IllegalArgumentException if there are any duplicate elements 558 * @throws NullPointerException if an element is {@code null} 559 * 560 * @since 9 561 */ 562 static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6) { 563 return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5, 564 e6); 565 } 566 567 /** 568 * Returns an unmodifiable set containing seven elements. 569 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details. 570 * 571 * @param <E> the {@code Set}'s element type 572 * @param e1 the first element 573 * @param e2 the second element 574 * @param e3 the third element 575 * @param e4 the fourth element 576 * @param e5 the fifth element 577 * @param e6 the sixth element 578 * @param e7 the seventh element 579 * @return a {@code Set} containing the specified elements 580 * @throws IllegalArgumentException if there are any duplicate elements 581 * @throws NullPointerException if an element is {@code null} 582 * 583 * @since 9 584 */ 585 static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7) { 586 return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5, 587 e6, e7); 588 } 589 590 /** 591 * Returns an unmodifiable set containing eight elements. 592 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details. 593 * 594 * @param <E> the {@code Set}'s element type 595 * @param e1 the first element 596 * @param e2 the second element 597 * @param e3 the third element 598 * @param e4 the fourth element 599 * @param e5 the fifth element 600 * @param e6 the sixth element 601 * @param e7 the seventh element 602 * @param e8 the eighth element 603 * @return a {@code Set} containing the specified elements 604 * @throws IllegalArgumentException if there are any duplicate elements 605 * @throws NullPointerException if an element is {@code null} 606 * 607 * @since 9 608 */ 609 static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) { 610 return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5, 611 e6, e7, e8); 612 } 613 614 /** 615 * Returns an unmodifiable set containing nine elements. 616 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details. 617 * 618 * @param <E> the {@code Set}'s element type 619 * @param e1 the first element 620 * @param e2 the second element 621 * @param e3 the third element 622 * @param e4 the fourth element 623 * @param e5 the fifth element 624 * @param e6 the sixth element 625 * @param e7 the seventh element 626 * @param e8 the eighth element 627 * @param e9 the ninth element 628 * @return a {@code Set} containing the specified elements 629 * @throws IllegalArgumentException if there are any duplicate elements 630 * @throws NullPointerException if an element is {@code null} 631 * 632 * @since 9 633 */ 634 static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) { 635 return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5, 636 e6, e7, e8, e9); 637 } 638 639 /** 640 * Returns an unmodifiable set containing ten elements. 641 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details. 642 * 643 * @param <E> the {@code Set}'s element type 644 * @param e1 the first element 645 * @param e2 the second element 646 * @param e3 the third element 647 * @param e4 the fourth element 648 * @param e5 the fifth element 649 * @param e6 the sixth element 650 * @param e7 the seventh element 651 * @param e8 the eighth element 652 * @param e9 the ninth element 653 * @param e10 the tenth element 654 * @return a {@code Set} containing the specified elements 655 * @throws IllegalArgumentException if there are any duplicate elements 656 * @throws NullPointerException if an element is {@code null} 657 * 658 * @since 9 659 */ 660 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) { 661 return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5, 662 e6, e7, e8, e9, e10); 663 } 664 665 /** 666 * Returns an unmodifiable set containing an arbitrary number of elements. 667 * See <a href="#unmodifiable">Unmodifiable Sets</a> for details. 668 * 669 * @apiNote 670 * This method also accepts a single array as an argument. The element type of 671 * the resulting set will be the component type of the array, and the size of 672 * the set will be equal to the length of the array. To create a set with 673 * a single element that is an array, do the following: 674 * 675 * <pre>{@code 676 * String[] array = ... ; 677 * Set<String[]> list = Set.<String[]>of(array); 678 * }</pre> 679 * 680 * This will cause the {@link Set#of(Object) Set.of(E)} method 681 * to be invoked instead. 682 * 683 * @param <E> the {@code Set}'s element type 684 * @param elements the elements to be contained in the set 685 * @return a {@code Set} containing the specified elements 686 * @throws IllegalArgumentException if there are any duplicate elements 687 * @throws NullPointerException if an element is {@code null} or if the array is {@code null} 688 * 689 * @since 9 690 */ 691 @SafeVarargs 692 @SuppressWarnings("varargs") 693 static <E> Set<E> of(E... elements) { 694 switch (elements.length) { // implicit null check of elements 695 case 0: 696 @SuppressWarnings("unchecked") 697 var set = (Set<E>) ImmutableCollections.SetN.EMPTY_SET; 698 return set; 699 case 1: 700 return new ImmutableCollections.Set12<>(elements[0]); 701 case 2: 702 return new ImmutableCollections.Set12<>(elements[0], elements[1]); 703 default: 704 return new ImmutableCollections.SetN<>(elements); 705 } 706 } 707 708 /** 709 * Returns an <a href="#unmodifiable">unmodifiable Set</a> containing the elements 710 * of the given Collection. The given Collection must not be null, and it must not 711 * contain any null elements. If the given Collection contains duplicate elements, 712 * an arbitrary element of the duplicates is preserved. If the given Collection is 713 * subsequently modified, the returned Set will not reflect such modifications. 714 * 715 * @implNote 716 * If the given Collection is an <a href="#unmodifiable">unmodifiable Set</a>, 717 * calling copyOf will generally not create a copy. 718 * 719 * @param <E> the {@code Set}'s element type 720 * @param coll a {@code Collection} from which elements are drawn, must be non-null 721 * @return a {@code Set} containing the elements of the given {@code Collection} 722 * @throws NullPointerException if coll is null, or if it contains any nulls 723 * @since 10 724 */ 725 @SuppressWarnings("unchecked") 726 static <E> Set<E> copyOf(Collection<? extends E> coll) { 727 if (coll instanceof ImmutableCollections.AbstractImmutableSet) { 728 return (Set<E>)coll; 729 } else { 730 return (Set<E>)Set.of(new HashSet<>(coll).toArray()); 731 } 732 } 733 }