--- old/src/java.base/share/classes/java/util/Collection.java 2017-12-07 14:44:06.000000000 -0800 +++ new/src/java.base/share/classes/java/util/Collection.java 2017-12-07 14:44:06.000000000 -0800 @@ -25,6 +25,7 @@ package java.util; +import java.util.function.IntFunction; import java.util.function.Predicate; import java.util.stream.Stream; import java.util.stream.StreamSupport; @@ -276,8 +277,12 @@ * allocate a new array even if this collection is backed by an array). * The caller is thus free to modify the returned array. * - *
This method acts as bridge between array-based and collection-based - * APIs. + * @apiNote + * This method acts as a bridge between array-based and collection-based APIs. + * It returns an array whose runtime type is {@code Object[]}. + * Use {@link #toArray(Object[]) toArray(T[])} to reuse an existing + * array, or use {@link #toArray(IntFunction)} to control the runtime type + * of the array. * * @return an array, whose {@linkplain Class#getComponentType runtime component * type} is {@code Object}, containing all of the elements in this collection @@ -302,19 +307,27 @@ * are returned by its iterator, this method must return the elements in * the same order. * - *
Like the {@link #toArray()} method, this method acts as bridge between - * array-based and collection-based APIs. Further, this method allows - * precise control over the runtime type of the output array, and may, - * under certain circumstances, be used to save allocation costs. + * @apiNote + * This method acts as a bridge between array-based and collection-based APIs. + * It allows an existing array to be reused under certain circumstances. + * Use {@link #toArray()} to create an array whose runtime type is {@code Object[]}, + * or use {@link #toArray(IntFunction)} to control the runtime type of + * the array. * *
Suppose {@code x} is a collection known to contain only strings. - * The following code can be used to dump the collection into a newly - * allocated array of {@code String}: + * The following code can be used to dump the collection into a previously + * allocated {@code String} array: * *
- * String[] y = x.toArray(new String[0]);+ * String[] y = new String[SIZE]; + * ... + * y = x.toArray(y); + * + *
The return value is reassigned to the variable {@code y}, because a + * new array will be allocated and returned if the collection {@code x} has + * too many elements to fit into the existing array {@code y}. * - * Note that {@code toArray(new Object[0])} is identical in function to + *
Note that {@code toArray(new Object[0])} is identical in function to
* {@code toArray()}.
*
* @param If this collection makes any guarantees as to what order its elements
+ * are returned by its iterator, this method must return the elements in
+ * the same order.
+ *
+ * @apiNote
+ * This method acts as a bridge between array-based and collection-based APIs.
+ * It allows creation of an array of a particular runtime type. Use
+ * {@link #toArray()} to create an array whose runtime type is {@code Object[]},
+ * or use {@link #toArray(Object[]) toArray(T[])} to reuse an existing array.
+ *
+ * Suppose {@code x} is a collection known to contain only strings.
+ * The following code can be used to dump the collection into a newly
+ * allocated array of {@code String}:
+ *
+ *
+ * String[] y = x.toArray(String[]::new);
+ *
+ * @implSpec
+ * The default implementation calls the generator function with zero
+ * and then passes the resulting array to {@link #toArray(Object[]) toArray(T[])}.
+ *
+ * @param