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 * <p>This interface is a member of the
67 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
68 * Java Collections Framework</a>.
69 *
70 * @param <E> the type of elements maintained by this set
71 *
72 * @author Josh Bloch
73 * @author Neal Gafter
74 * @see Collection
75 * @see List
76 * @see SortedSet
77 * @see HashSet
78 * @see TreeSet
79 * @see AbstractSet
80 * @see Collections#singleton(java.lang.Object)
81 * @see Collections#EMPTY_SET
82 * @since 1.2
83 */
84
85 public interface Set<E> extends Collection<E> {
393 * @implSpec
394 * The default implementation creates a
395 * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator
396 * from the set's {@code Iterator}. The spliterator inherits the
397 * <em>fail-fast</em> properties of the set's iterator.
398 * <p>
399 * The created {@code Spliterator} additionally reports
400 * {@link Spliterator#SIZED}.
401 *
402 * @implNote
403 * The created {@code Spliterator} additionally reports
404 * {@link Spliterator#SUBSIZED}.
405 *
406 * @return a {@code Spliterator} over the elements in this set
407 * @since 1.8
408 */
409 @Override
410 default Spliterator<E> spliterator() {
411 return Spliterators.spliterator(this, Spliterator.DISTINCT);
412 }
413 }
|
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 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 cannot be modified. Attempts to modify them result in
73 * an {@code UnsupportedOperationException}.
74 * <li>They are truly immutable only if the contained elements are themselves
75 * immutable. If an element is mutated, the behavior of the set is unspecified.
76 * <li>They disallow null elements. Attempts to create them with
77 * null elements result in {@code NullPointerException}.
78 * <li>They are serializable if all elements are serializable.
79 * <li>They reject duplicate elements at creation time. Duplicate elements
80 * passed to a static factory method result in {@code IllegalArgumentException}.
81 * </ul>
82 *
83 * <p>This interface is a member of the
84 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
85 * Java Collections Framework</a>.
86 *
87 * @param <E> the type of elements maintained by this set
88 *
89 * @author Josh Bloch
90 * @author Neal Gafter
91 * @see Collection
92 * @see List
93 * @see SortedSet
94 * @see HashSet
95 * @see TreeSet
96 * @see AbstractSet
97 * @see Collections#singleton(java.lang.Object)
98 * @see Collections#EMPTY_SET
99 * @since 1.2
100 */
101
102 public interface Set<E> extends Collection<E> {
410 * @implSpec
411 * The default implementation creates a
412 * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator
413 * from the set's {@code Iterator}. The spliterator inherits the
414 * <em>fail-fast</em> properties of the set's iterator.
415 * <p>
416 * The created {@code Spliterator} additionally reports
417 * {@link Spliterator#SIZED}.
418 *
419 * @implNote
420 * The created {@code Spliterator} additionally reports
421 * {@link Spliterator#SUBSIZED}.
422 *
423 * @return a {@code Spliterator} over the elements in this set
424 * @since 1.8
425 */
426 @Override
427 default Spliterator<E> spliterator() {
428 return Spliterators.spliterator(this, Spliterator.DISTINCT);
429 }
430
431 /**
432 * Creates an immutable set containing zero elements.
433 * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
434 *
435 * @param <E> the set's element type
436 * @return the newly created set
437 *
438 * @since 9
439 */
440 static <E> Set<E> of() {
441 return Collections.emptySet();
442 }
443
444 /**
445 * Creates an immutable set containing one element.
446 * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
447 *
448 * @param <E> the set's element type
449 * @param e1 the single set element
450 * @return the newly created set
451 * @throws NullPointerException if the element is null
452 *
453 * @since 9
454 */
455 static <E> Set<E> of(E e1) {
456 return Collections.singleton(Objects.requireNonNull(e1));
457 }
458
459 /**
460 * Creates an immutable set containing two elements.
461 * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
462 *
463 * @param <E> the set's element type
464 * @param e1 the first set element
465 * @param e2 the second set element
466 * @return the newly created set
467 * @throws IllegalArgumentException if the elements are duplicates
468 * @throws NullPointerException if an element is null
469 *
470 * @since 9
471 */
472 static <E> Set<E> of(E e1, E e2) {
473 Set<E> set = new HashSet<>(Arrays.asList(Objects.requireNonNull(e1),
474 Objects.requireNonNull(e2)));
475 if (set.size() != 2) {
476 throw new IllegalArgumentException("duplicate elements");
477 }
478 return Collections.unmodifiableSet(set);
479 }
480
481 /**
482 * Creates an immutable set containing three elements.
483 * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
484 *
485 * @param <E> the set's element type
486 * @param e1 the first set element
487 * @param e2 the second set element
488 * @param e3 the third set element
489 * @return the newly created set
490 * @throws IllegalArgumentException if there are any duplicate elements
491 * @throws NullPointerException if an element is null
492 *
493 * @since 9
494 */
495 static <E> Set<E> of(E e1, E e2, E e3) {
496 Set<E> set = new HashSet<>(Arrays.asList(Objects.requireNonNull(e1),
497 Objects.requireNonNull(e2),
498 Objects.requireNonNull(e3)));
499 if (set.size() != 3) {
500 throw new IllegalArgumentException("duplicate elements");
501 }
502 return Collections.unmodifiableSet(set);
503 }
504
505 /**
506 * Creates an immutable set containing four elements.
507 * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
508 *
509 * @param <E> the set's element type
510 * @param e1 the first set element
511 * @param e2 the second set element
512 * @param e3 the third set element
513 * @param e4 the fourth set element
514 * @return the newly created set
515 * @throws IllegalArgumentException if there are any duplicate elements
516 * @throws NullPointerException if an element is null
517 *
518 * @since 9
519 */
520 static <E> Set<E> of(E e1, E e2, E e3, E e4) {
521 Set<E> set = new HashSet<>(Arrays.asList(Objects.requireNonNull(e1),
522 Objects.requireNonNull(e2),
523 Objects.requireNonNull(e3),
524 Objects.requireNonNull(e4)));
525 if (set.size() != 4) {
526 throw new IllegalArgumentException("duplicate elements");
527 }
528 return Collections.unmodifiableSet(set);
529 }
530
531 /**
532 * Creates an immutable set containing five elements.
533 * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
534 *
535 * @param <E> the set's element type
536 * @param e1 the first set element
537 * @param e2 the second set element
538 * @param e3 the third set element
539 * @param e4 the fourth set element
540 * @param e5 the fifth set element
541 * @return the newly created set
542 * @throws IllegalArgumentException if there are any duplicate elements
543 * @throws NullPointerException if an element is null
544 *
545 * @since 9
546 */
547 static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5) {
548 Set<E> set = new HashSet<>(Arrays.asList(Objects.requireNonNull(e1),
549 Objects.requireNonNull(e2),
550 Objects.requireNonNull(e3),
551 Objects.requireNonNull(e4),
552 Objects.requireNonNull(e5)));
553 if (set.size() != 5) {
554 throw new IllegalArgumentException("duplicate elements");
555 }
556 return Collections.unmodifiableSet(set);
557 }
558
559 /**
560 * Creates an immutable set containing six elements.
561 * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
562 *
563 * @param <E> the set's element type
564 * @param e1 the first set element
565 * @param e2 the second set element
566 * @param e3 the third set element
567 * @param e4 the fourth set element
568 * @param e5 the fifth set element
569 * @param e6 the sixth set element
570 * @return the newly created set
571 * @throws IllegalArgumentException if there are any duplicate elements
572 * @throws NullPointerException if an element is null
573 *
574 * @since 9
575 */
576 static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6) {
577 Set<E> set = new HashSet<>(Arrays.asList(Objects.requireNonNull(e1),
578 Objects.requireNonNull(e2),
579 Objects.requireNonNull(e3),
580 Objects.requireNonNull(e4),
581 Objects.requireNonNull(e5),
582 Objects.requireNonNull(e6)));
583 if (set.size() != 6) {
584 throw new IllegalArgumentException("duplicate elements");
585 }
586 return Collections.unmodifiableSet(set);
587 }
588
589 /**
590 * Creates an immutable set containing seven elements.
591 * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
592 *
593 * @param <E> the set's element type
594 * @param e1 the first set element
595 * @param e2 the second set element
596 * @param e3 the third set element
597 * @param e4 the fourth set element
598 * @param e5 the fifth set element
599 * @param e6 the sixth set element
600 * @param e7 the seventh set element
601 * @return the newly created set
602 * @throws IllegalArgumentException if there are any duplicate elements
603 * @throws NullPointerException if an element is null
604 *
605 * @since 9
606 */
607 static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7) {
608 Set<E> set = new HashSet<>(Arrays.asList(Objects.requireNonNull(e1),
609 Objects.requireNonNull(e2),
610 Objects.requireNonNull(e3),
611 Objects.requireNonNull(e4),
612 Objects.requireNonNull(e5),
613 Objects.requireNonNull(e6),
614 Objects.requireNonNull(e7)));
615 if (set.size() != 7) {
616 throw new IllegalArgumentException("duplicate elements");
617 }
618 return Collections.unmodifiableSet(set);
619 }
620
621 /**
622 * Creates an immutable set containing eight elements.
623 * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
624 *
625 * @param <E> the set's element type
626 * @param e1 the first set element
627 * @param e2 the second set element
628 * @param e3 the third set element
629 * @param e4 the fourth set element
630 * @param e5 the fifth set element
631 * @param e6 the sixth set element
632 * @param e7 the seventh set element
633 * @param e8 the eighth set element
634 * @return the newly created set
635 * @throws IllegalArgumentException if there are any duplicate elements
636 * @throws NullPointerException if an element is null
637 *
638 * @since 9
639 */
640 static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) {
641 Set<E> set = new HashSet<>(Arrays.asList(Objects.requireNonNull(e1),
642 Objects.requireNonNull(e2),
643 Objects.requireNonNull(e3),
644 Objects.requireNonNull(e4),
645 Objects.requireNonNull(e5),
646 Objects.requireNonNull(e6),
647 Objects.requireNonNull(e7),
648 Objects.requireNonNull(e8)));
649 if (set.size() != 8) {
650 throw new IllegalArgumentException("duplicate elements");
651 }
652 return Collections.unmodifiableSet(set);
653 }
654
655 /**
656 * Creates an immutable set containing nine elements.
657 * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
658 *
659 * @param <E> the set's element type
660 * @param e1 the first set element
661 * @param e2 the second set element
662 * @param e3 the third set element
663 * @param e4 the fourth set element
664 * @param e5 the fifth set element
665 * @param e6 the sixth set element
666 * @param e7 the seventh set element
667 * @param e8 the eighth set element
668 * @param e9 the ninth set element
669 * @return the newly created set
670 * @throws IllegalArgumentException if there are any duplicate elements
671 * @throws NullPointerException if an element is null
672 *
673 * @since 9
674 */
675 static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) {
676 Set<E> set = new HashSet<>(Arrays.asList(Objects.requireNonNull(e1),
677 Objects.requireNonNull(e2),
678 Objects.requireNonNull(e3),
679 Objects.requireNonNull(e4),
680 Objects.requireNonNull(e5),
681 Objects.requireNonNull(e6),
682 Objects.requireNonNull(e7),
683 Objects.requireNonNull(e8),
684 Objects.requireNonNull(e9)));
685 if (set.size() != 9) {
686 throw new IllegalArgumentException("duplicate elements");
687 }
688 return Collections.unmodifiableSet(set);
689 }
690
691 /**
692 * Creates an immutable set containing ten elements.
693 * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
694 *
695 * @param <E> the set's element type
696 * @param e1 the first set element
697 * @param e2 the second set element
698 * @param e3 the third set element
699 * @param e4 the fourth set element
700 * @param e5 the fifth set element
701 * @param e6 the sixth set element
702 * @param e7 the seventh set element
703 * @param e8 the eighth set element
704 * @param e9 the ninth set element
705 * @param e10 the tenth set element
706 * @return the newly created set
707 * @throws IllegalArgumentException if there are any duplicate elements
708 * @throws NullPointerException if an element is null
709 *
710 * @since 9
711 */
712 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) {
713 Set<E> set = new HashSet<>(Arrays.asList(Objects.requireNonNull(e1),
714 Objects.requireNonNull(e2),
715 Objects.requireNonNull(e3),
716 Objects.requireNonNull(e4),
717 Objects.requireNonNull(e5),
718 Objects.requireNonNull(e6),
719 Objects.requireNonNull(e7),
720 Objects.requireNonNull(e8),
721 Objects.requireNonNull(e9),
722 Objects.requireNonNull(e10)));
723 if (set.size() != 10) {
724 throw new IllegalArgumentException("duplicate elements");
725 }
726 return Collections.unmodifiableSet(set);
727 }
728
729 /**
730 * Creates an immutable set containing an arbitrary number of elements.
731 * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
732 *
733 * @apiNote
734 * This method also accepts a single array as an argument. The element type of
735 * the resulting set will be the component type of the array, and the size of
736 * the set will be equal to the length of the array. To create a set with
737 * a single element that is an array, do the following:
738 *
739 * <pre>{@code
740 * String[] array = ... ;
741 * Set<String[]> list = Set.<String[]>of(array);
742 * }</pre>
743 *
744 * This will cause the {@link Set#of(Object) Set.of(E)} method
745 * to be invoked instead.
746 *
747 * @param <E> the set's element type
748 * @param es the elements to be contained in the set
749 * @return the newly created set
750 * @throws IllegalArgumentException if there are any duplicate elements
751 * @throws NullPointerException if an element is null or if the array is null
752 *
753 * @since 9
754 */
755 @SafeVarargs
756 @SuppressWarnings("varargs")
757 static <E> Set<E> of(E... es) {
758 for (E e : es) { // throws NPE if es is null
759 Objects.requireNonNull(e);
760 }
761 // NOTE: this can allow a null element to slip through
762 Set<E> set = new HashSet<>(Arrays.asList(es));
763 if (set.size() != es.length) {
764 throw new IllegalArgumentException("duplicate elements");
765 }
766 return Collections.unmodifiableSet(set);
767 }
768 }
|