changeset 8269:62ee7f5ff8d1

Spec update for Arrays methods in prep for JDK-8012650 push
author briangoetz
date Sat, 20 Apr 2013 17:25:38 -0400
parents 191bba4888f4
children f2fe1654f65c
files src/share/classes/java/util/Arrays.java
diffstat 1 files changed, 84 insertions(+), 40 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/Arrays.java	Sat Apr 20 12:20:23 2013 -0400
+++ b/src/share/classes/java/util/Arrays.java	Sat Apr 20 17:25:38 2013 -0400
@@ -4526,109 +4526,153 @@
     }
 
     /**
-     * Initializes all elements of the specified array, using the provided
+     * Set all elements of the specified array, using the provided
      * generator function to compute each element.
      *
+     * <p>If the generator function throws an exception, it is relayed to
+     * the caller and the array is left in an indeterminate state.
+     *
      * @param array Array to be initialized
      * @param generator Function accepting an index and producing the desired
      *        value for that position
      * @param <T> Type of elements of the array
+     * @throw NullPointerException if the generator is null
      */
     public static<T> void setAll(T[] array, IntFunction<? extends T> generator) {
+        Objects.requireNonNull(generator);
         for (int i=0; i<array.length; i++)
             array[i] = generator.apply(i);
     }
 
     /**
-     * Initializes all elements of the specified array, in parallel, using the
+     * Set all elements of the specified array, in parallel, using the
      * provided generator function to compute each element.
      *
+     * <p>If the generator function throws an exception, an unchecked exception
+     * is thrown from {@code parallelSetAll} and the array is left in an
+     * indeterminate state.
+     *
      * @param array Array to be initialized
      * @param generator Function accepting an index and producing the desired
      *        value for that position
      * @param <T> Type of elements of the array
+     * @throw NullPointerException if the generator is null
      */
     public static<T> void parallelSetAll(T[] array, IntFunction<? extends T> generator) {
+        Objects.requireNonNull(generator);
         Streams.intRange(0, array.length).parallel().forEach(i -> { array[i] = generator.apply(i); });
     }
 
     /**
-     * Initialize all elements of the specified array, using the provided
+     * Set all elements of the specified array, using the provided
      * generator function to compute each element.
      *
+     * <p>If the generator function throws an exception, it is relayed to
+     * the caller and the array is left in an indeterminate state.
+     *
      * @param array Array to be initialized
      * @param generator Function accepting an index and producing the desired
      *        value for that position
+     * @throw NullPointerException if the generator is null
      */
     public static void setAll(int[] array, IntUnaryOperator generator) {
+        Objects.requireNonNull(generator);
         for (int i=0; i<array.length; i++)
             array[i] = generator.applyAsInt(i);
     }
 
     /**
-     * Initialize all elements of the specified array, in parallel, using the
+     * Set all elements of the specified array, in parallel, using the
      * provided generator function to compute each element.
      *
+     * <p>If the generator function throws an exception, an unchecked exception
+     * is thrown from {@code parallelSetAll} and the array is left in an
+     * indeterminate state.
+     *
      * @param array Array to be initialized
      * @param generator Function accepting an index and producing the desired
      * value for that position
+     * @throw NullPointerException if the generator is null
      */
     public static void parallelSetAll(int[] array, IntUnaryOperator generator) {
+        Objects.requireNonNull(generator);
         Streams.intRange(0, array.length).parallel().forEach(i -> { array[i] = generator.applyAsInt(i); });
     }
 
     /**
-     * Initialize all elements of the specified array, using the provided
+     * Set all elements of the specified array, using the provided
      * generator function to compute each element.
      *
+     * <p>If the generator function throws an exception, it is relayed to
+     * the caller and the array is left in an indeterminate state.
+     *
      * @param array Array to be initialized
      * @param generator Function accepting an index and producing the desired
      *        value for that position
+     * @throw NullPointerException if the generator is null
      */
     public static void setAll(long[] array, IntToLongFunction generator) {
+        Objects.requireNonNull(generator);
         for (int i=0; i<array.length; i++)
             array[i] = generator.applyAsLong(i);
     }
 
     /**
-     * Initialize all elements of the specified array, in parallel, using the
+     * Set all elements of the specified array, in parallel, using the
      * provided generator function to compute each element.
      *
+     * <p>If the generator function throws an exception, an unchecked exception
+     * is thrown from {@code parallelSetAll} and the array is left in an
+     * indeterminate state.
+     *
      * @param array Array to be initialized
      * @param generator Function accepting an index and producing the desired
      *        value for that position
+     * @throw NullPointerException if the generator is null
      */
     public static void parallelSetAll(long[] array, IntToLongFunction generator) {
+        Objects.requireNonNull(generator);
         Streams.intRange(0, array.length).parallel().forEach(i -> { array[i] = generator.applyAsLong(i); });
     }
 
     /**
-     * Initialize all elements of the specified array, using the provided
+     * Set all elements of the specified array, using the provided
      * generator function to compute each element.
      *
+     * <p>If the generator function throws an exception, it is relayed to
+     * the caller and the array is left in an indeterminate state.
+     *
      * @param array Array to be initialized
      * @param generator Function accepting an index and producing the desired
      *        value for that position
+     * @throw NullPointerException if the generator is null
      */
     public static void setAll(double[] array, IntToDoubleFunction generator) {
+        Objects.requireNonNull(generator);
         for (int i=0; i<array.length; i++)
             array[i] = generator.applyAsDouble(i);
     }
 
     /**
-     * Initialize all elements of the specified array, in parallel, using the
+     * Set all elements of the specified array, in parallel, using the
      * provided generator function to compute each element.
      *
+     * <p>If the generator function throws an exception, an unchecked exception
+     * is thrown from {@code parallelSetAll} and the array is left in an
+     * indeterminate state.
+     *
      * @param array Array to be initialized
      * @param generator Function accepting an index and producing the desired
      *        value for that position
+     * @throw NullPointerException if the generator is null
      */
     public static void parallelSetAll(double[] array, IntToDoubleFunction generator) {
+        Objects.requireNonNull(generator);
         Streams.intRange(0, array.length).parallel().forEach(i -> { array[i] = generator.applyAsDouble(i); });
     }
 
     /**
-     * Creates a {@link Spliterator} covering all of the specified array.
+     * Returns a {@link Spliterator} covering all of the specified array.
      *
      * <p>The spliterator reports {@link Spliterator#SIZED},
      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
@@ -4636,7 +4680,7 @@
      *
      * @param <T> Type of elements
      * @param array The array, assumed to be unmodified during use
-     * @return A spliterator from the array
+     * @return the spliterator for the array elements
      * @throws NullPointerException if the specified array is {@code null}
      * @since 1.8
      */
@@ -4646,7 +4690,7 @@
     }
 
     /**
-     * Creates a {@link Spliterator} covering the specified range of the
+     * Returns a {@link Spliterator} covering the specified range of the
      * specified array.
      *
      * <p>The spliterator reports {@link Spliterator#SIZED},
@@ -4657,7 +4701,7 @@
      * @param array The array, assumed to be unmodified during use
      * @param fromIndex The least index (inclusive) to cover
      * @param toIndex One past the greatest index to cover
-     * @return A spliterator from the array
+     * @return the spliterator for the array elements
      * @throws NullPointerException if the specified array is {@code null}
      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex} is negative,
      *         {@code toIndex} is less than {@code fromIndex}, or
@@ -4670,14 +4714,14 @@
     }
 
     /**
-     * Creates a {@link Spliterator.OfInt} covering all of the specified array.
+     * Returns a {@link Spliterator.OfInt} covering all of the specified array.
      *
      * <p>The spliterator reports {@link Spliterator#SIZED},
      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
      * {@link Spliterator#IMMUTABLE}.
      *
      * @param array The array, assumed to be unmodified during use
-     * @return A spliterator from the array
+     * @return the spliterator for the array elements
      * @throws NullPointerException if the specified array is {@code null}
      * @since 1.8
      */
@@ -4687,7 +4731,7 @@
     }
 
     /**
-     * Creates a {@link Spliterator.OfInt} covering the specified range of the
+     * Returns a {@link Spliterator.OfInt} covering the specified range of the
      * specified array.
      *
      * <p>The spliterator reports {@link Spliterator#SIZED},
@@ -4697,7 +4741,7 @@
      * @param array The array, assumed to be unmodified during use
      * @param fromIndex The least index (inclusive) to cover
      * @param toIndex One past the greatest index to cover
-     * @return A spliterator from the array
+     * @return the spliterator for the array elements
      * @throws NullPointerException if the specified array is {@code null}
      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex} is negative,
      *         {@code toIndex} is less than {@code fromIndex}, or
@@ -4710,14 +4754,14 @@
     }
 
     /**
-     * Creates a {@link Spliterator.OfLong} covering all of the specified array.
+     * Returns a {@link Spliterator.OfLong} covering all of the specified array.
      *
      * <p>The spliterator reports {@link Spliterator#SIZED},
      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
      * {@link Spliterator#IMMUTABLE}.
      *
      * @param array The array, assumed to be unmodified during use
-     * @return A spliterator from the array
+     * @return the spliterator for the array elements
      * @throws NullPointerException if the specified array is {@code null}
      * @since 1.8
      */
@@ -4727,7 +4771,7 @@
     }
 
     /**
-     * Creates a {@link Spliterator.OfLong} covering the specified range of the
+     * Returns a {@link Spliterator.OfLong} covering the specified range of the
      * specified array.
      *
      * <p>The spliterator reports {@link Spliterator#SIZED},
@@ -4737,7 +4781,7 @@
      * @param array The array, assumed to be unmodified during use
      * @param fromIndex The least index (inclusive) to cover
      * @param toIndex One past the greatest index to cover
-     * @return A spliterator from the array
+     * @return the spliterator for the array elements
      * @throws NullPointerException if the specified array is {@code null}
      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex} is negative,
      *         {@code toIndex} is less than {@code fromIndex}, or
@@ -4750,7 +4794,7 @@
     }
 
     /**
-     * Creates a {@link Spliterator.OfDouble} covering all of the specified
+     * Returns a {@link Spliterator.OfDouble} covering all of the specified
      * array.
      *
      * <p>The spliterator reports {@link Spliterator#SIZED},
@@ -4758,7 +4802,7 @@
      * {@link Spliterator#IMMUTABLE}.
      *
      * @param array The array, assumed to be unmodified during use
-     * @return A spliterator from the array
+     * @return the spliterator for the array elements
      * @throws NullPointerException if the specified array is {@code null}
      * @since 1.8
      */
@@ -4768,7 +4812,7 @@
     }
 
     /**
-     * Creates a {@link Spliterator.OfDouble} covering the specified range of
+     * Returns a {@link Spliterator.OfDouble} covering the specified range of
      * the specified array.
      *
      * <p>The spliterator reports {@link Spliterator#SIZED},
@@ -4778,7 +4822,7 @@
      * @param array The array, assumed to be unmodified during use
      * @param fromIndex The least index (inclusive) to cover
      * @param toIndex One past the greatest index to cover
-     * @return A spliterator from the array
+     * @return the spliterator for the array elements
      * @throws NullPointerException if the specified array is {@code null}
      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex} is negative,
      *         {@code toIndex} is less than {@code fromIndex}, or
@@ -4791,7 +4835,7 @@
     }
 
     /**
-     * Creates a sequential {@link Stream} with the specified array as its
+     * Returns a sequential {@link Stream} with the specified array as its
      * source.
      *
      * @param <T> The type of the array elements
@@ -4805,7 +4849,7 @@
     }
 
     /**
-     * Creates a sequential {@link Stream} with specified range of the
+     * Returns a sequential {@link Stream} with specified range of the
      * specified array as its source.
      *
      * @param <T> The type of the array elements
@@ -4825,7 +4869,7 @@
     }
 
     /**
-     * Creates a sequential {@link IntStream} with the specified array as its
+     * Returns a sequential {@link IntStream} with the specified array as its
      * source.
      *
      * @param array The array, assumed to be unmodified during use
@@ -4838,7 +4882,7 @@
     }
 
     /**
-     * Creates a sequential {@link IntStream} with specified range of the
+     * Returns a sequential {@link IntStream} with specified range of the
      * specified array as its source.
      *
      * @param array The array, assumed to be unmodified during use
@@ -4857,7 +4901,7 @@
     }
 
     /**
-     * Creates a sequential {@link LongStream} with the specified array as its
+     * Returns a sequential {@link LongStream} with the specified array as its
      * source.
      *
      * @param array The array, assumed to be unmodified during use
@@ -4870,7 +4914,7 @@
     }
 
     /**
-     * Creates a sequential {@link LongStream} with specified range of the
+     * Returns a sequential {@link LongStream} with specified range of the
      * specified array as its source.
      *
      * @param array The array, assumed to be unmodified during use
@@ -4889,7 +4933,7 @@
     }
 
     /**
-     * Creates a sequential {@link DoubleStream} with the specified array as its
+     * Returns a sequential {@link DoubleStream} with the specified array as its
      * source.
      *
      * @param array The array, assumed to be unmodified during use
@@ -4902,7 +4946,7 @@
     }
 
     /**
-     * Creates a sequential {@link DoubleStream} with specified range of the
+     * Returns a sequential {@link DoubleStream} with specified range of the
      * specified array as its source.
      *
      * @param array The array, assumed to be unmodified during use
@@ -4921,7 +4965,7 @@
     }
 
     /**
-     * Creates a parallel {@link Stream} with the specified array as its
+     * Returns a parallel {@link Stream} with the specified array as its
      * source.
      *
      * @param <T> The type of the array elements
@@ -4935,7 +4979,7 @@
     }
 
     /**
-     * Creates a parallel {@link Stream} with specified range of the
+     * Returns a parallel {@link Stream} with specified range of the
      * specified array as its source.
      *
      * @param <T> The type of the array elements
@@ -4955,7 +4999,7 @@
     }
 
     /**
-     * Creates a parallel {@link IntStream} with the specified array as its
+     * Returns a parallel {@link IntStream} with the specified array as its
      * source.
      *
      * @param array The array, assumed to be unmodified during use
@@ -4968,7 +5012,7 @@
     }
 
     /**
-     * Creates a parallel {@link IntStream} with specified range of the
+     * Returns a parallel {@link IntStream} with specified range of the
      * specified array as its source.
      *
      * @param array The array, assumed to be unmodified during use
@@ -4987,7 +5031,7 @@
     }
 
     /**
-     * Creates a parallel {@link LongStream} with the specified array as its
+     * Returns a parallel {@link LongStream} with the specified array as its
      * source.
      *
      * @param array The array, assumed to be unmodified during use
@@ -5000,7 +5044,7 @@
     }
 
     /**
-     * Creates a parallel {@link LongStream} with specified range of the
+     * Returns a parallel {@link LongStream} with specified range of the
      * specified array as its source.
      *
      * @param array The array, assumed to be unmodified during use
@@ -5019,7 +5063,7 @@
     }
 
     /**
-     * Creates a parallel {@link DoubleStream} with the specified array as its
+     * Returns a parallel {@link DoubleStream} with the specified array as its
      * source.
      *
      * @param array The array, assumed to be unmodified during use
@@ -5032,7 +5076,7 @@
     }
 
     /**
-     * Creates a parallel {@link DoubleStream} with specified range of the
+     * Returns a parallel {@link DoubleStream} with specified range of the
      * specified array as its source.
      *
      * @param array The array, assumed to be unmodified during use