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