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