< prev index next >
src/java.base/share/classes/java/util/List.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
*** 85,103 ****
* the insertion of an ineligible element into the list 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 List Static Factory Methods</a></h2>
! * <p>The {@link List#of(Object...) List.of()} static factory methods
! * provide a convenient way to create immutable lists. The {@code List}
* instances created by these methods have the following characteristics:
*
* <ul>
! * <li>They are <em>structurally immutable</em>. Elements cannot be added, removed,
! * or replaced. Calling any mutator method will always cause
! * {@code UnsupportedOperationException} to be thrown.
* However, if the contained elements are themselves mutable,
* this may cause the List's 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.
--- 85,104 ----
* the insertion of an ineligible element into the list 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 Lists</a></h2>
! * <p>The {@link List#of(Object...) List.of} and
! * {@link List#copyOf List.copyOf} static factory methods
! * provide a convenient way to create unmodifiable lists. The {@code List}
* 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, removed, or replaced. Calling any mutator method on the List
! * will always cause {@code UnsupportedOperationException} to be thrown.
* However, if the contained elements are themselves mutable,
* this may cause the List's 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.
*** 775,787 ****
return Spliterators.spliterator(this, Spliterator.ORDERED);
}
}
/**
! * Returns an immutable list containing zero elements.
*
! * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
*
* @param <E> the {@code List}'s element type
* @return an empty {@code List}
*
* @since 9
--- 776,788 ----
return Spliterators.spliterator(this, Spliterator.ORDERED);
}
}
/**
! * Returns an unmodifiable list containing zero elements.
*
! * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
*
* @param <E> the {@code List}'s element type
* @return an empty {@code List}
*
* @since 9
*** 789,801 ****
static <E> List<E> of() {
return ImmutableCollections.List0.instance();
}
/**
! * Returns an immutable list containing one element.
*
! * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the single element
* @return a {@code List} containing the specified element
* @throws NullPointerException if the element is {@code null}
--- 790,802 ----
static <E> List<E> of() {
return ImmutableCollections.List0.instance();
}
/**
! * Returns an unmodifiable list containing one element.
*
! * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the single element
* @return a {@code List} containing the specified element
* @throws NullPointerException if the element is {@code null}
*** 805,817 ****
static <E> List<E> of(E e1) {
return new ImmutableCollections.List1<>(e1);
}
/**
! * Returns an immutable list containing two elements.
*
! * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @return a {@code List} containing the specified elements
--- 806,818 ----
static <E> List<E> of(E e1) {
return new ImmutableCollections.List1<>(e1);
}
/**
! * Returns an unmodifiable list containing two elements.
*
! * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @return a {@code List} containing the specified elements
*** 822,834 ****
static <E> List<E> of(E e1, E e2) {
return new ImmutableCollections.List2<>(e1, e2);
}
/**
! * Returns an immutable list containing three elements.
*
! * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
--- 823,835 ----
static <E> List<E> of(E e1, E e2) {
return new ImmutableCollections.List2<>(e1, e2);
}
/**
! * Returns an unmodifiable list containing three elements.
*
! * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
*** 840,852 ****
static <E> List<E> of(E e1, E e2, E e3) {
return new ImmutableCollections.ListN<>(e1, e2, e3);
}
/**
! * Returns an immutable list containing four elements.
*
! * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
--- 841,853 ----
static <E> List<E> of(E e1, E e2, E e3) {
return new ImmutableCollections.ListN<>(e1, e2, e3);
}
/**
! * Returns an unmodifiable list containing four elements.
*
! * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
*** 859,871 ****
static <E> List<E> of(E e1, E e2, E e3, E e4) {
return new ImmutableCollections.ListN<>(e1, e2, e3, e4);
}
/**
! * Returns an immutable list containing five elements.
*
! * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
--- 860,872 ----
static <E> List<E> of(E e1, E e2, E e3, E e4) {
return new ImmutableCollections.ListN<>(e1, e2, e3, e4);
}
/**
! * Returns an unmodifiable list containing five elements.
*
! * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
*** 879,891 ****
static <E> List<E> of(E e1, E e2, E e3, E e4, E e5) {
return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5);
}
/**
! * Returns an immutable list containing six elements.
*
! * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
--- 880,892 ----
static <E> List<E> of(E e1, E e2, E e3, E e4, E e5) {
return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5);
}
/**
! * Returns an unmodifiable list containing six elements.
*
! * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
*** 901,913 ****
return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
e6);
}
/**
! * Returns an immutable list containing seven elements.
*
! * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
--- 902,914 ----
return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
e6);
}
/**
! * Returns an unmodifiable list containing seven elements.
*
! * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
*** 924,936 ****
return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
e6, e7);
}
/**
! * Returns an immutable list containing eight elements.
*
! * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
--- 925,937 ----
return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
e6, e7);
}
/**
! * Returns an unmodifiable list containing eight elements.
*
! * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
*** 948,960 ****
return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
e6, e7, e8);
}
/**
! * Returns an immutable list containing nine elements.
*
! * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
--- 949,961 ----
return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
e6, e7, e8);
}
/**
! * Returns an unmodifiable list containing nine elements.
*
! * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
*** 973,985 ****
return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
e6, e7, e8, e9);
}
/**
! * Returns an immutable list containing ten elements.
*
! * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
--- 974,986 ----
return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
e6, e7, e8, e9);
}
/**
! * Returns an unmodifiable list containing ten elements.
*
! * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
*
* @param <E> the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
*** 999,1010 ****
return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
e6, e7, e8, e9, e10);
}
/**
! * Returns an immutable list containing an arbitrary number of elements.
! * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
*
* @apiNote
* This method also accepts a single array as an argument. The element type of
* the resulting list will be the component type of the array, and the size of
* the list will be equal to the length of the array. To create a list with
--- 1000,1011 ----
return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
e6, e7, e8, e9, e10);
}
/**
! * Returns an unmodifiable list containing an arbitrary number of elements.
! * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
*
* @apiNote
* This method also accepts a single array as an argument. The element type of
* the resulting list will be the component type of the array, and the size of
* the list will be equal to the length of the array. To create a list with
*** 1037,1042 ****
--- 1038,1068 ----
return new ImmutableCollections.List2<>(elements[0], elements[1]);
default:
return new ImmutableCollections.ListN<>(elements);
}
}
+
+ /**
+ * Returns an <a href="#unmodifiable">unmodifiable List</a> containing the elements of
+ * the given Collection, in its iteration order. The given Collection must not be null,
+ * and it must not contain any null elements. If the given Collection is subsequently
+ * modified, the returned List will not reflect such modifications.
+ *
+ * @implNote
+ * If the given Collection is an <a href="#unmodifiable">unmodifiable List</a>,
+ * calling copyOf will generally not create a copy.
+ *
+ * @param <E> the {@code List}'s element type
+ * @param coll a {@code Collection} from which elements are drawn, must be non-null
+ * @return a {@code List} 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> List<E> copyOf(Collection<? extends E> coll) {
+ if (coll instanceof ImmutableCollections.AbstractImmutableList) {
+ return (List<E>)coll;
+ } else {
+ return (List<E>)List.of(coll.toArray());
+ }
+ }
}
< prev index next >