< 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,19 +61,20 @@
      * 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}
    + * <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 <em>structurally immutable</em>. Elements cannot be added or
    - * removed. Calling any mutator method will always cause
    - * {@code UnsupportedOperationException} to be thrown.
    + * <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,12 +438,12 @@
         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.
    +     * 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,12 +451,12 @@
         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.
    +     * 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,12 +466,12 @@
         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.
    +     * 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,12 +483,12 @@
         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.
    +     * 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,12 +501,12 @@
         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.
    +     * 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,12 +520,12 @@
         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.
    +     * 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,12 +540,12 @@
         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.
    +     * 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,12 +562,12 @@
             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.
    +     * 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,12 +585,12 @@
             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.
    +     * 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,12 +609,12 @@
             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.
    +     * 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,12 +634,12 @@
             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.
    +     * 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,12 +660,12 @@
             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.
    +     * 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,6 +699,32 @@
                     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 >