< prev index next >

## src/java.base/share/classes/java/util/Set.java

Print this page

    rev 47953 : 8177290: add copy factory methods for unmodifiable List, Set, Map
    8184690: add Collectors for collecting into unmodifiable List, Set, and Map
    Reviewed-by: alanb, briangoetz, dholmes, jrose, rriggs, scolebourne

    *** 61,79 ****
       * the insertion of an ineligible element into the set may throw an
       * exception or it may succeed, at the option of the implementation.
       * Such exceptions are marked as "optional" in the specification for this
       * interface.
       *
    !  * <h2><a id="immutable">Immutable Set Static Factory Methods</a></h2>
    !  * <p>The {@link Set#of(Object...) Set.of()} static factory methods
    !  * provide a convenient way to create immutable sets. The {@code Set}
       * instances created by these methods have the following characteristics:
       *
       * <ul>
    !  * <li>They are <em>structurally immutable</em>. Elements cannot be added or
    !  * removed. Calling any mutator method will always cause
    !  * {@code UnsupportedOperationException} to be thrown.
       * However, if the contained elements are themselves mutable, this may cause the
       * Set to behave inconsistently or its contents to appear to change.
       * <li>They disallow {@code null} elements. Attempts to create them with
       * {@code null} elements result in {@code NullPointerException}.
       * <li>They are serializable if all elements are serializable.
    --- 61,80 ----
       * the insertion of an ineligible element into the set may throw an
       * exception or it may succeed, at the option of the implementation.
       * Such exceptions are marked as "optional" in the specification for this
       * interface.
       *
    !  * <h2><a id="unmodifiable">Unmodifiable Sets</a></h2>
    !  * <p>The {@link Set#of(Object...) Set.of} and
    !  * {@link Set#copyOf Set.copyOf} static factory methods
    !  * provide a convenient way to create unmodifiable sets. The {@code Set}
       * instances created by these methods have the following characteristics:
       *
       * <ul>
    !  * <li>They are <a href="Collection.html#unmodifiable"><i>unmodifiable</i></a>. Elements cannot
    !  * be added or removed. Calling any mutator method on the Set
    !  * will always cause {@code UnsupportedOperationException} to be thrown.
       * However, if the contained elements are themselves mutable, this may cause the
       * Set to behave inconsistently or its contents to appear to change.
       * <li>They disallow {@code null} elements. Attempts to create them with
       * {@code null} elements result in {@code NullPointerException}.
       * <li>They are serializable if all elements are serializable.
    *** 437,448 ****
          default Spliterator<E> spliterator() {
              return Spliterators.spliterator(this, Spliterator.DISTINCT);
          }

          /**
    !      * Returns an immutable set containing zero elements.
    !      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @return an empty {@code Set}
           *
           * @since 9
    --- 438,449 ----
          default Spliterator<E> spliterator() {
              return Spliterators.spliterator(this, Spliterator.DISTINCT);
          }

          /**
    !      * Returns an unmodifiable set containing zero elements.
    !      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @return an empty {@code Set}
           *
           * @since 9
    *** 450,461 ****
          static <E> Set<E> of() {
              return ImmutableCollections.Set0.instance();
          }

          /**
    !      * Returns an immutable set containing one element.
    !      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the single element
           * @return a {@code Set} containing the specified element
           * @throws NullPointerException if the element is {@code null}
    --- 451,462 ----
          static <E> Set<E> of() {
              return ImmutableCollections.Set0.instance();
          }

          /**
    !      * Returns an unmodifiable set containing one element.
    !      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the single element
           * @return a {@code Set} containing the specified element
           * @throws NullPointerException if the element is {@code null}
    *** 465,476 ****
          static <E> Set<E> of(E e1) {
              return new ImmutableCollections.Set1<>(e1);
          }

          /**
    !      * Returns an immutable set containing two elements.
    !      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @return a {@code Set} containing the specified elements
    --- 466,477 ----
          static <E> Set<E> of(E e1) {
              return new ImmutableCollections.Set1<>(e1);
          }

          /**
    !      * Returns an unmodifiable set containing two elements.
    !      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @return a {@code Set} containing the specified elements
    *** 482,493 ****
          static <E> Set<E> of(E e1, E e2) {
              return new ImmutableCollections.Set2<>(e1, e2);
          }

          /**
    !      * Returns an immutable set containing three elements.
    !      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @param e3 the third element
    --- 483,494 ----
          static <E> Set<E> of(E e1, E e2) {
              return new ImmutableCollections.Set2<>(e1, e2);
          }

          /**
    !      * Returns an unmodifiable set containing three elements.
    !      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @param e3 the third element
    *** 500,511 ****
          static <E> Set<E> of(E e1, E e2, E e3) {
              return new ImmutableCollections.SetN<>(e1, e2, e3);
          }

          /**
    !      * Returns an immutable set containing four elements.
    !      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @param e3 the third element
    --- 501,512 ----
          static <E> Set<E> of(E e1, E e2, E e3) {
              return new ImmutableCollections.SetN<>(e1, e2, e3);
          }

          /**
    !      * Returns an unmodifiable set containing four elements.
    !      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @param e3 the third element
    *** 519,530 ****
          static <E> Set<E> of(E e1, E e2, E e3, E e4) {
              return new ImmutableCollections.SetN<>(e1, e2, e3, e4);
          }

          /**
    !      * Returns an immutable set containing five elements.
    !      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @param e3 the third element
    --- 520,531 ----
          static <E> Set<E> of(E e1, E e2, E e3, E e4) {
              return new ImmutableCollections.SetN<>(e1, e2, e3, e4);
          }

          /**
    !      * Returns an unmodifiable set containing five elements.
    !      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @param e3 the third element
    *** 539,550 ****
          static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5) {
              return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5);
          }

          /**
    !      * Returns an immutable set containing six elements.
    !      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @param e3 the third element
    --- 540,551 ----
          static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5) {
              return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5);
          }

          /**
    !      * Returns an unmodifiable set containing six elements.
    !      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @param e3 the third element
    *** 561,572 ****
              return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
                                                     e6);
          }

          /**
    !      * Returns an immutable set containing seven elements.
    !      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @param e3 the third element
    --- 562,573 ----
              return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
                                                     e6);
          }

          /**
    !      * Returns an unmodifiable set containing seven elements.
    !      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @param e3 the third element
    *** 584,595 ****
              return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
                                                     e6, e7);
          }

          /**
    !      * Returns an immutable set containing eight elements.
    !      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @param e3 the third element
    --- 585,596 ----
              return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
                                                     e6, e7);
          }

          /**
    !      * Returns an unmodifiable set containing eight elements.
    !      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @param e3 the third element
    *** 608,619 ****
              return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
                                                     e6, e7, e8);
          }

          /**
    !      * Returns an immutable set containing nine elements.
    !      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @param e3 the third element
    --- 609,620 ----
              return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
                                                     e6, e7, e8);
          }

          /**
    !      * Returns an unmodifiable set containing nine elements.
    !      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @param e3 the third element
    *** 633,644 ****
              return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
                                                     e6, e7, e8, e9);
          }

          /**
    !      * Returns an immutable set containing ten elements.
    !      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @param e3 the third element
    --- 634,645 ----
              return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
                                                     e6, e7, e8, e9);
          }

          /**
    !      * Returns an unmodifiable set containing ten elements.
    !      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
           *
           * @param <E> the {@code Set}'s element type
           * @param e1 the first element
           * @param e2 the second element
           * @param e3 the third element
    *** 659,670 ****
              return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
                                                     e6, e7, e8, e9, e10);
          }

          /**
    !      * Returns an immutable set containing an arbitrary number of elements.
    !      * See <a href="#immutable">Immutable Set Static Factory Methods</a> for details.
           *
           * @apiNote
           * This method also accepts a single array as an argument. The element type of
           * the resulting set will be the component type of the array, and the size of
           * the set will be equal to the length of the array. To create a set with
    --- 660,671 ----
              return new ImmutableCollections.SetN<>(e1, e2, e3, e4, e5,
                                                     e6, e7, e8, e9, e10);
          }

          /**
    !      * Returns an unmodifiable set containing an arbitrary number of elements.
    !      * See <a href="#unmodifiable">Unmodifiable Sets</a> for details.
           *
           * @apiNote
           * This method also accepts a single array as an argument. The element type of
           * the resulting set will be the component type of the array, and the size of
           * the set will be equal to the length of the array. To create a set with
    *** 698,703 ****
    --- 699,730 ----
                      return new ImmutableCollections.Set2<>(elements[0], elements[1]);
                  default:
                      return new ImmutableCollections.SetN<>(elements);
              }
          }
    +
    +     /**
    +      * Returns an <a href="#unmodifiable">unmodifiable Set</a> containing the elements
    +      * of the given Collection. The given Collection must not be null, and it must not
    +      * contain any null elements. If the given Collection contains duplicate elements,
    +      * an arbitrary element of the duplicates is preserved. If the given Collection is
    +      * subsequently modified, the returned Set will not reflect such modifications.
    +      *
    +      * @implNote
    +      * If the given Collection is an <a href="#unmodifiable">unmodifiable Set</a>,
    +      * calling copyOf will generally not create a copy.
    +      *
    +      * @param <E> the {@code Set}'s element type
    +      * @param coll a {@code Collection} from which elements are drawn, must be non-null
    +      * @return a {@code Set} containing the elements of the given {@code Collection}
    +      * @throws NullPointerException if coll is null, or if it contains any nulls
    +      * @since 10
    +      */
    +     @SuppressWarnings("unchecked")
    +     static <E> Set<E> copyOf(Collection<? extends E> coll) {
    +         if (coll instanceof ImmutableCollections.AbstractImmutableSet) {
    +             return (Set<E>)coll;
    +         } else {
    +             return (Set<E>)Set.of(new HashSet<>(coll).toArray());
    +         }
    +     }
      }

< prev index next >