changeset 8113:10ad6bc63cbd

Final spec tweaks on Spliterator, Spliterators
author briangoetz
date Mon, 15 Apr 2013 10:14:40 -0400
parents 2532d144a93d
children fc561b4b80b1
files src/share/classes/java/util/Spliterator.java src/share/classes/java/util/Spliterators.java src/share/classes/java/util/function/BiFunction.java src/share/classes/java/util/function/Function.java
diffstat 4 files changed, 86 insertions(+), 56 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/Spliterator.java	Mon Apr 15 11:42:47 2013 +0200
+++ b/src/share/classes/java/util/Spliterator.java	Mon Apr 15 10:14:40 2013 -0400
@@ -93,7 +93,12 @@
  * {@link #trySplit()} may hand over the returned Spliterator to another thread,
  * which in turn may traverse or further split that Spliterator.  The behaviour
  * of splitting and traversal is undefined if two or more threads operate
- * concurrently on the same spliterator.
+ * concurrently on the same spliterator.  If the original thread hands a
+ * spliterator off to another thread for processing, it is best if that handoff
+ * occurs before any elements are consumed with {@link #tryAdvance(Consumer)
+ * tryAdvance()}, as certain guarantees (such as the accuracy of
+ * {@link #estimateSize()} for {@code SIZED} spliterators) are only valid before
+ * traversal has begun.
  *
  * <p>Primitive subtype specializations of {@code Spliterator} are provided for
  * {@link OfInt int}, {@link OfLong long}, and {@link OfDouble double} values.
@@ -364,11 +369,11 @@
      * encountered by a {@link #forEachRemaining} traversal, or returns {@link
      * Long#MAX_VALUE} if infinite, unknown, or too expensive to compute.
      *
-     * <p>If this Spliterator is {@link #SIZED}, this estimate must represent
-     * an accurate count of elements, but need not reflect the effects of
-     * completed or in-progress traversal steps.  Otherwise, this estimate may
-     * be arbitrarily inaccurate, but must decrease as specified across
-     * invocations of {@link #trySplit}.
+     * <p>If this Spliterator is {@link #SIZED}, and has not yet been partially
+     * traversed or split, this estimate must represent an accurate count of
+     * elements that would be encountered by a complete traversal.  Otherwise,
+     * this estimate may be arbitrarily inaccurate, but must decrease as
+     * specified across invocations of {@link #trySplit}.
      *
      * @apiNote
      * Even an inexact estimate is often useful and inexpensive to compute.
@@ -388,8 +393,8 @@
      * elements. The result is represented as ORed values from {@link
      * #ORDERED}, {@link #DISTINCT}, {@link #SORTED}, {@link #SIZED},
      * {@link #NONNULL}, {@link #IMMUTABLE}, {@link #CONCURRENT},
-     * {@link #SUBSIZED}.  The returned value need not reflect effects of any
-     * completed or in-progress traversal.
+     * {@link #SUBSIZED}.  Repeated calls to {@code characteristics()} on
+     * a given spliterator should always return the same result.
      *
      * <p>If a Spliterator reports an inconsistent set of
      * characteristics (either those returned from a single invocation
@@ -494,9 +499,10 @@
 
     /**
      * Characteristic value signifying that the value returned from
-     * {@code estimateSize()} represents a finite size that, in the
-     * absence of structural source modification, is fixed throughout
-     * operations using this Spliterator.
+     * {@code estimateSize()} prior to traversal or splitting represents a
+     * finite size that, in the absence of structural source modification,
+     * represents an exact count of the number of elements that would be
+     * encountered by a complete traversal.
      *
      * @apiNote
      * Most Spliterators, based on Collections, that cover all elements of a
--- a/src/share/classes/java/util/Spliterators.java	Mon Apr 15 11:42:47 2013 +0200
+++ b/src/share/classes/java/util/Spliterators.java	Mon Apr 15 10:14:40 2013 -0400
@@ -117,14 +117,16 @@
      * Creates a {@code Spliterator} covering the elements of a given array,
      * using a customized set of spliterator characteristics.
      *
+     * <p>This method is provided as an implementation conveniece for
+     * Spliterators which store portions of their elements in arrays, and need
+     * fine control over Spliterator characteristics.  Most other situations in
+     * which a Spliterator for an array is needed should use
+     * {@link Arrays#spliterator(Object[])}.
+     *
      * <p>The returned spliterator always reports the characteristics
      * {@code SIZED} and {@code SUBSIZED}.  The caller may provide additional
-     * characteristics for the spliterator to report.  (For example, if it is
-     * known the array will not be further modified, specify {@code IMMUTABLE};
-     * if the array data is considered to have an an encounter order, specify
-     * {@code ORDERED}).  The method {@link Arrays#spliterator(Object[])} can
-     * often be used instead, which returns a spliterator that reports
-     * {@code SIZED}, {@code SUBSIZED}, {@code IMMUTABLE}, and {@code ORDERED}.
+     * characteristics for the spliterator to report; it is common to
+     * additionally specify {@code IMMUTABLE} and {@code ORDERED}.
      *
      * @param <T> Type of elements
      * @param array The array, assumed to be unmodified during use
@@ -145,14 +147,16 @@
      * Creates a {@code Spliterator} covering a range of elements of a given
      * array, using a customized set of spliterator characteristics.
      *
+     * <p>This method is provided as an implementation conveniece for
+     * Spliterators which store portions of their elements in arrays, and need
+     * fine control over Spliterator characteristics.  Most other situations in
+     * which a Spliterator for an array is needed should use
+     * {@link Arrays#spliterator(Object[])}.
+     *
      * <p>The returned spliterator always reports the characteristics
      * {@code SIZED} and {@code SUBSIZED}.  The caller may provide additional
-     * characteristics for the spliterator to report.  (For example, if it is
-     * known the array will not be further modified, specify {@code IMMUTABLE};
-     * if the array data is considered to have an an encounter order, specify
-     * {@code ORDERED}).  The method {@link Arrays#spliterator(Object[], int, int)} can
-     * often be used instead, which returns a spliterator that reports
-     * {@code SIZED}, {@code SUBSIZED}, {@code IMMUTABLE}, and {@code ORDERED}.
+     * characteristics for the spliterator to report; it is common to
+     * additionally specify {@code IMMUTABLE} and {@code ORDERED}.
      *
      * @param <T> Type of elements
      * @param array The array, assumed to be unmodified during use
@@ -178,14 +182,16 @@
      * Creates a {@code Spliterator.OfInt} covering the elements of a given array,
      * using a customized set of spliterator characteristics.
      *
+     * <p>This method is provided as an implementation conveniece for
+     * Spliterators which store portions of their elements in arrays, and need
+     * fine control over Spliterator characteristics.  Most other situations in
+     * which a Spliterator for an array is needed should use
+     * {@link Arrays#spliterator(int[])}.
+     *
      * <p>The returned spliterator always reports the characteristics
      * {@code SIZED} and {@code SUBSIZED}.  The caller may provide additional
-     * characteristics for the spliterator to report.  (For example, if it is
-     * known the array will not be further modified, specify {@code IMMUTABLE};
-     * if the array data is considered to have an an encounter order, specify
-     * {@code ORDERED}).  The method {@link Arrays#spliterator(int[])} can
-     * often be used instead, which returns a spliterator that reports
-     * {@code SIZED}, {@code SUBSIZED}, {@code IMMUTABLE}, and {@code ORDERED}.
+     * characteristics for the spliterator to report; it is common to
+     * additionally specify {@code IMMUTABLE} and {@code ORDERED}.
      *
      * @param array The array, assumed to be unmodified during use
      * @param additionalCharacteristics Additional spliterator characteristics
@@ -201,17 +207,19 @@
     }
 
     /**
-     * Creates a {@code Spliterator.OfInt} covering a range of elements of a given
-     * array, using a customized set of spliterator characteristics.
+     * Creates a {@code Spliterator.OfInt} covering a range of elements of a
+     * given array, using a customized set of spliterator characteristics.
+     *
+     * <p>This method is provided as an implementation conveniece for
+     * Spliterators which store portions of their elements in arrays, and need
+     * fine control over Spliterator characteristics.  Most other situations in
+     * which a Spliterator for an array is needed should use
+     * {@link Arrays#spliterator(int[], int, int)}.
      *
      * <p>The returned spliterator always reports the characteristics
      * {@code SIZED} and {@code SUBSIZED}.  The caller may provide additional
-     * characteristics for the spliterator to report.  (For example, if it is
-     * known the array will not be further modified, specify {@code IMMUTABLE};
-     * if the array data is considered to have an an encounter order, specify
-     * {@code ORDERED}).  The method {@link Arrays#spliterator(int[], int, int)} can
-     * often be used instead, which returns a spliterator that reports
-     * {@code SIZED}, {@code SUBSIZED}, {@code IMMUTABLE}, and {@code ORDERED}.
+     * characteristics for the spliterator to report; it is common to
+     * additionally specify {@code IMMUTABLE} and {@code ORDERED}.
      *
      * @param array The array, assumed to be unmodified during use
      * @param fromIndex The least index (inclusive) to cover
@@ -236,14 +244,16 @@
      * Creates a {@code Spliterator.OfLong} covering the elements of a given array,
      * using a customized set of spliterator characteristics.
      *
+     * <p>This method is provided as an implementation conveniece for
+     * Spliterators which store portions of their elements in arrays, and need
+     * fine control over Spliterator characteristics.  Most other situations in
+     * which a Spliterator for an array is needed should use
+     * {@link Arrays#spliterator(long[])}.
+     *
      * <p>The returned spliterator always reports the characteristics
      * {@code SIZED} and {@code SUBSIZED}.  The caller may provide additional
-     * characteristics for the spliterator to report.  (For example, if it is
-     * known the array will not be further modified, specify {@code IMMUTABLE};
-     * if the array data is considered to have an an encounter order, specify
-     * {@code ORDERED}).  The method {@link Arrays#spliterator(long[])} can
-     * often be used instead, which returns a spliterator that reports
-     * {@code SIZED}, {@code SUBSIZED}, {@code IMMUTABLE}, and {@code ORDERED}.
+     * characteristics for the spliterator to report; it is common to
+     * additionally specify {@code IMMUTABLE} and {@code ORDERED}.
      *
      * @param array The array, assumed to be unmodified during use
      * @param additionalCharacteristics Additional spliterator characteristics
@@ -259,8 +269,14 @@
     }
 
     /**
-     * Creates a {@code Spliterator.OfLong} covering a range of elements of a given
-     * array, using a customized set of spliterator characteristics.
+     * Creates a {@code Spliterator.OfLong} covering a range of elements of a
+     * given array, using a customized set of spliterator characteristics.
+     *
+     * <p>This method is provided as an implementation conveniece for
+     * Spliterators which store portions of their elements in arrays, and need
+     * fine control over Spliterator characteristics.  Most other situations in
+     * which a Spliterator for an array is needed should use
+     * {@link Arrays#spliterator(long[], int, int)}.
      *
      * <p>The returned spliterator always reports the characteristics
      * {@code SIZED} and {@code SUBSIZED}.  The caller may provide additional
@@ -294,14 +310,16 @@
      * Creates a {@code Spliterator.OfDouble} covering the elements of a given array,
      * using a customized set of spliterator characteristics.
      *
+     * <p>This method is provided as an implementation conveniece for
+     * Spliterators which store portions of their elements in arrays, and need
+     * fine control over Spliterator characteristics.  Most other situations in
+     * which a Spliterator for an array is needed should use
+     * {@link Arrays#spliterator(double[])}.
+     *
      * <p>The returned spliterator always reports the characteristics
      * {@code SIZED} and {@code SUBSIZED}.  The caller may provide additional
-     * characteristics for the spliterator to report.  (For example, if it is
-     * known the array will not be further modified, specify {@code IMMUTABLE};
-     * if the array data is considered to have an an encounter order, specify
-     * {@code ORDERED}).  The method {@link Arrays#spliterator(double[])} can
-     * often be used instead, which returns a spliterator that reports
-     * {@code SIZED}, {@code SUBSIZED}, {@code IMMUTABLE}, and {@code ORDERED}.
+     * characteristics for the spliterator to report; it is common to
+     * additionally specify {@code IMMUTABLE} and {@code ORDERED}.
      *
      * @param array The array, assumed to be unmodified during use
      * @param additionalCharacteristics Additional spliterator characteristics
@@ -317,8 +335,14 @@
     }
 
     /**
-     * Creates a {@code Spliterator.OfLong} covering a range of elements of a given
-     * array, using a customized set of spliterator characteristics.
+     * Creates a {@code Spliterator.OfDouble} covering a range of elements of a
+     * given array, using a customized set of spliterator characteristics.
+     *
+     * <p>This method is provided as an implementation conveniece for
+     * Spliterators which store portions of their elements in arrays, and need
+     * fine control over Spliterator characteristics.  Most other situations in
+     * which a Spliterator for an array is needed should use
+     * {@link Arrays#spliterator(double[], int, int)}.
      *
      * <p>The returned spliterator always reports the characteristics
      * {@code SIZED} and {@code SUBSIZED}.  The caller may provide additional
--- a/src/share/classes/java/util/function/BiFunction.java	Mon Apr 15 11:42:47 2013 +0200
+++ b/src/share/classes/java/util/function/BiFunction.java	Mon Apr 15 10:14:40 2013 -0400
@@ -63,7 +63,7 @@
      * function
      * @throws NullPointerException if after is null
      */
-    default <V > BiFunction<T, U, V> andThen(Function<? super R, ? extends V> after) {
+    default <V> BiFunction<T, U, V> andThen(Function<? super R, ? extends V> after) {
         Objects.requireNonNull(after);
         return (T t, U u) -> after.apply(apply(t, u));
     }
--- a/src/share/classes/java/util/function/Function.java	Mon Apr 15 11:42:47 2013 +0200
+++ b/src/share/classes/java/util/function/Function.java	Mon Apr 15 10:14:40 2013 -0400
@@ -59,7 +59,7 @@
      * function
      * @throws NullPointerException if before is null
      */
-    default <V > Function<V, R> compose(Function<? super V, ? extends T> before) {
+    default <V> Function<V, R> compose(Function<? super V, ? extends T> before) {
         Objects.requireNonNull(before);
         return (V v) -> apply(before.apply(v));
     }
@@ -76,7 +76,7 @@
      * function followed
      * @throws NullPointerException if after is null
      */
-    default <V > Function<T, V> andThen(Function<? super R, ? extends V> after) {
+    default <V> Function<T, V> andThen(Function<? super R, ? extends V> after) {
         Objects.requireNonNull(after);
         return (T t) -> after.apply(apply(t));
     }