src/java.base/share/classes/java/util/Collection.java

rev 48215 : 8060192: Add default method <A> A[] Collection.toArray(IntFunction<A[]> generator)
Reviewed-by: martin, forax, psandoz

*** 23,32 ****
--- 23,33 ----
   * questions.
   */
  
  package java.util;
  
+ import java.util.function.IntFunction;
  import java.util.function.Predicate;
  import java.util.stream.Stream;
  import java.util.stream.StreamSupport;
  
  /**
*** 274,285 ****
       * <p>The returned array will be "safe" in that no references to it are
       * maintained by this collection.  (In other words, this method must
       * allocate a new array even if this collection is backed by an array).
       * The caller is thus free to modify the returned array.
       *
!      * <p>This method acts as bridge between array-based and collection-based
!      * APIs.
       *
       * @return an array, whose {@linkplain Class#getComponentType runtime component
       * type} is {@code Object}, containing all of the elements in this collection
       */
      Object[] toArray();
--- 275,290 ----
       * <p>The returned array will be "safe" in that no references to it are
       * maintained by this collection.  (In other words, this method must
       * allocate a new array even if this collection is backed by an array).
       * The caller is thus free to modify the returned array.
       *
!      * @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
       */
      Object[] toArray();
*** 300,322 ****
       *
       * <p>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.
       *
!      * <p>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.
       *
       * <p>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}:
       *
       * <pre>
!      *     String[] y = x.toArray(new String[0]);</pre>
       *
!      * Note that {@code toArray(new Object[0])} is identical in function to
       * {@code toArray()}.
       *
       * @param <T> the component type of the array to contain the collection
       * @param a the array into which the elements of this collection are to be
       *        stored, if it is big enough; otherwise, a new array of the same
--- 305,335 ----
       *
       * <p>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 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.
       *
       * <p>Suppose {@code x} is a collection known to contain only strings.
!      * The following code can be used to dump the collection into a previously
!      * allocated {@code String} array:
       *
       * <pre>
!      *     String[] y = new String[SIZE];
!      *     ...
!      *     y = x.toArray(y);</pre>
!      *
!      * <p>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}.
       *
!      * <p>Note that {@code toArray(new Object[0])} is identical in function to
       * {@code toArray()}.
       *
       * @param <T> the component type of the array to contain the collection
       * @param a the array into which the elements of this collection are to be
       *        stored, if it is big enough; otherwise, a new array of the same
*** 327,336 ****
--- 340,388 ----
       *         runtime component type} of the specified array
       * @throws NullPointerException if the specified array is null
       */
      <T> T[] toArray(T[] a);
  
+     /**
+      * Returns an array containing all of the elements in this collection,
+      * using the provided {@code generator} function to allocate the returned array.
+      *
+      * <p>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.
+      *
+      * <p>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}:
+      *
+      * <pre>
+      *     String[] y = x.toArray(String[]::new);</pre>
+      *
+      * @implSpec
+      * The default implementation calls the generator function with zero
+      * and then passes the resulting array to {@link #toArray(Object[]) toArray(T[])}.
+      *
+      * @param <T> the component type of the array to contain the collection
+      * @param generator a function which produces a new array of the desired
+      *                  type and the provided length
+      * @return an array containing all of the elements in this collection
+      * @throws ArrayStoreException if the runtime type of any element in this
+      *         collection is not assignable to the {@linkplain Class#getComponentType
+      *         runtime component type} of the generated array
+      * @throws NullPointerException if the generator function is null
+      * @since 10
+      */
+     default <T> T[] toArray(IntFunction<T[]> generator) {
+         return toArray(generator.apply(0));
+     }
+ 
      // Modification Operations
  
      /**
       * Ensures that this collection contains the specified element (optional
       * operation).  Returns {@code true} if this collection changed as a