< prev index next >
src/java.base/share/classes/java/util/Set.java
Print this page
rev 17661 : 8177290: add copy factory methods for unmodifiable List, Set, Map
8184690: add Collectors for collecting into unmodifiable List, Set, and Map
Reviewed-by: XXX
*** 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,726 ----
return new ImmutableCollections.Set2<>(elements[0], elements[1]);
default:
return new ImmutableCollections.SetN<>(elements);
}
}
+
+ /**
+ * Returns an unmodifiable Set containing the elements of the given Collection.
+ * Duplicate elements are permitted. If the Collection has a defined iteration order,
+ * the first element of any duplicates is preserved, and the rest are discarded.
+ * Otherwise, an arbitrary element is preserved.
+ * See <a href="#unmodifiable">Unmodifiable Sets</a> for
+ * information about the characteristics of the returned Set.
+ *
+ * @param <E> the {@code Set}'s element type
+ * @param coll the collection from which elements are drawn
+ * @return the new Set
+ * @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(coll.stream().distinct().toArray());
+ }
+ }
}
< prev index next >