From a7dd7b59dac29f20dcdabf646dcab34981a2a677 Mon Sep 17 00:00:00 2001 From: Paul Sandoz Date: Fri, 9 Sep 2016 14:54:29 -0700 Subject: [PATCH] 8164691: Stream specification clarifications for iterate and collect Reviewed-by: briangoetz, smarks, tvaleev --- .../java/util/stream/DoubleStream.java | 79 +++++++++++-------- .../classes/java/util/stream/IntStream.java | 79 +++++++++++-------- .../classes/java/util/stream/LongStream.java | 79 +++++++++++-------- .../classes/java/util/stream/Stream.java | 77 +++++++++++------- 4 files changed, 191 insertions(+), 123 deletions(-) diff --git a/jdk/src/java.base/share/classes/java/util/stream/DoubleStream.java b/jdk/src/java.base/share/classes/java/util/stream/DoubleStream.java index 59f669baf67..2bc146c8d5f 100644 --- a/jdk/src/java.base/share/classes/java/util/stream/DoubleStream.java +++ b/jdk/src/java.base/share/classes/java/util/stream/DoubleStream.java @@ -567,19 +567,23 @@ public interface DoubleStream extends BaseStream { *

This is a terminal * operation. * - * @param type of the result - * @param supplier a function that creates a new result container. For a - * parallel execution, this function may be called + * @param the type of the mutable result container + * @param supplier a function that creates a new mutable result container. + * For a parallel execution, this function may be called * multiple times and must return a fresh value each time. * @param accumulator an associative, * non-interfering, * stateless - * function for incorporating an additional element into a result + * function that must fold an element into a result + * container. * @param combiner an associative, * non-interfering, * stateless - * function for combining two values, which must be - * compatible with the accumulator function + * function that accepts two partial result containers + * and merges them, which must be compatible with the + * accumulator function. The combiner function must fold + * the elements from the second result container into the + * first result container. * @return the result of the reduction * @see Stream#collect(Supplier, BiConsumer, BiConsumer) */ @@ -947,6 +951,12 @@ public interface DoubleStream extends BaseStream { * position {@code n}, will be the result of applying the function {@code f} * to the element at position {@code n - 1}. * + *

The action of applying {@code f} for one element + * happens-before + * the action of applying {@code f} for subsequent elements. For any given + * element the action may be performed in whatever thread the library + * chooses. + * * @param seed the initial element * @param f a function to be applied to the previous element to produce * a new element @@ -978,37 +988,44 @@ public interface DoubleStream extends BaseStream { /** * Returns a sequential ordered {@code DoubleStream} produced by iterative - * application of a function to an initial element, conditioned on - * satisfying the supplied predicate. The stream terminates as soon as - * the predicate returns false. + * application of the given {@code next} function to an initial element, + * conditioned on satisfying the given {@code hasNext} predicate. The + * stream terminates as soon as the {@code hasNext} predicate returns false. * - *

- * {@code DoubleStream.iterate} should produce the same sequence of - * elements as produced by the corresponding for-loop: + *

{@code DoubleStream.iterate} should produce the same sequence of elements as + * produced by the corresponding for-loop: * 

{@code
-     *     for (double index=seed; predicate.test(index); index = f.applyAsDouble(index)) {
+     *     for (double index=seed; hasNext.test(index); index = next.applyAsDouble(index)) {
      *         ...
      *     }
      * }
* - *

- * The resulting sequence may be empty if the predicate does not hold on - * the seed value. Otherwise the first element will be the supplied seed - * value, the next element (if present) will be the result of applying the - * function f to the seed value, and so on iteratively until the predicate - * indicates that the stream should terminate. + *

The resulting sequence may be empty if the {@code hasNext} predicate + * does not hold on the seed value. Otherwise the first element will be the + * supplied {@code seed} value, the next element (if present) will be the + * result of applying the {@code next} function to the {@code seed} value, + * and so on iteratively until the {@code hasNext} predicate indicates that + * the stream should terminate. + * + *

The action of applying the {@code hasNext} predicate to an element + * happens-before + * the action of applying the {@code next} function to that element. The + * action of applying the {@code next} function for one element + * happens-before the action of applying the {@code hasNext} + * predicate for subsequent elements. For any given element an action may + * be performed in whatever thread the library chooses. * * @param seed the initial element - * @param predicate a predicate to apply to elements to determine when the - * stream must terminate. - * @param f a function to be applied to the previous element to produce - * a new element + * @param hasNext a predicate to apply to elements to determine when the + * stream must terminate. + * @param next a function to be applied to the previous element to produce + * a new element * @return a new sequential {@code DoubleStream} * @since 9 */ - public static DoubleStream iterate(double seed, DoublePredicate predicate, DoubleUnaryOperator f) { - Objects.requireNonNull(f); - Objects.requireNonNull(predicate); + public static DoubleStream iterate(double seed, DoublePredicate hasNext, DoubleUnaryOperator next) { + Objects.requireNonNull(next); + Objects.requireNonNull(hasNext); Spliterator.OfDouble spliterator = new Spliterators.AbstractDoubleSpliterator(Long.MAX_VALUE, Spliterator.ORDERED | Spliterator.IMMUTABLE | Spliterator.NONNULL) { double prev; @@ -1021,12 +1038,12 @@ public interface DoubleStream extends BaseStream { return false; double t; if (started) - t = f.applyAsDouble(prev); + t = next.applyAsDouble(prev); else { t = seed; started = true; } - if (!predicate.test(t)) { + if (!hasNext.test(t)) { finished = true; return false; } @@ -1040,10 +1057,10 @@ public interface DoubleStream extends BaseStream { if (finished) return; finished = true; - double t = started ? f.applyAsDouble(prev) : seed; - while (predicate.test(t)) { + double t = started ? next.applyAsDouble(prev) : seed; + while (hasNext.test(t)) { action.accept(t); - t = f.applyAsDouble(t); + t = next.applyAsDouble(t); } } }; diff --git a/jdk/src/java.base/share/classes/java/util/stream/IntStream.java b/jdk/src/java.base/share/classes/java/util/stream/IntStream.java index daeac3ab140..c051a12bec7 100644 --- a/jdk/src/java.base/share/classes/java/util/stream/IntStream.java +++ b/jdk/src/java.base/share/classes/java/util/stream/IntStream.java @@ -562,19 +562,23 @@ public interface IntStream extends BaseStream { *

This is a terminal * operation. * - * @param type of the result - * @param supplier a function that creates a new result container. For a - * parallel execution, this function may be called + * @param the type of the mutable result container + * @param supplier a function that creates a new mutable result container. + * For a parallel execution, this function may be called * multiple times and must return a fresh value each time. * @param accumulator an associative, * non-interfering, * stateless - * function for incorporating an additional element into a result + * function that must fold an element into a result + * container. * @param combiner an associative, * non-interfering, * stateless - * function for combining two values, which must be - * compatible with the accumulator function + * function that accepts two partial result containers + * and merges them, which must be compatible with the + * accumulator function. The combiner function must fold + * the elements from the second result container into the + * first result container. * @return the result of the reduction * @see Stream#collect(Supplier, BiConsumer, BiConsumer) */ @@ -887,6 +891,12 @@ public interface IntStream extends BaseStream { * {@code n}, will be the result of applying the function {@code f} to the * element at position {@code n - 1}. * + *

The action of applying {@code f} for one element + * happens-before + * the action of applying {@code f} for subsequent elements. For any given + * element the action may be performed in whatever thread the library + * chooses. + * * @param seed the initial element * @param f a function to be applied to the previous element to produce * a new element @@ -918,37 +928,44 @@ public interface IntStream extends BaseStream { /** * Returns a sequential ordered {@code IntStream} produced by iterative - * application of a function to an initial element, conditioned on - * satisfying the supplied predicate. The stream terminates as soon as - * the predicate returns false. + * application of the given {@code next} function to an initial element, + * conditioned on satisfying the given {@code hasNext} predicate. The + * stream terminates as soon as the {@code hasNext} predicate returns false. * - *

- * {@code IntStream.iterate} should produce the same sequence of elements - * as produced by the corresponding for-loop: + *

{@code IntStream.iterate} should produce the same sequence of elements as + * produced by the corresponding for-loop: * 

{@code
-     *     for (int index=seed; predicate.test(index); index = f.applyAsInt(index)) {
+     *     for (int index=seed; hasNext.test(index); index = next.applyAsInt(index)) {
      *         ...
      *     }
      * }
* - *

- * The resulting sequence may be empty if the predicate does not hold on - * the seed value. Otherwise the first element will be the supplied seed - * value, the next element (if present) will be the result of applying the - * function f to the seed value, and so on iteratively until the predicate - * indicates that the stream should terminate. + *

The resulting sequence may be empty if the {@code hasNext} predicate + * does not hold on the seed value. Otherwise the first element will be the + * supplied {@code seed} value, the next element (if present) will be the + * result of applying the {@code next} function to the {@code seed} value, + * and so on iteratively until the {@code hasNext} predicate indicates that + * the stream should terminate. + * + *

The action of applying the {@code hasNext} predicate to an element + * happens-before + * the action of applying the {@code next} function to that element. The + * action of applying the {@code next} function for one element + * happens-before the action of applying the {@code hasNext} + * predicate for subsequent elements. For any given element an action may + * be performed in whatever thread the library chooses. * * @param seed the initial element - * @param predicate a predicate to apply to elements to determine when the - * stream must terminate. - * @param f a function to be applied to the previous element to produce - * a new element + * @param hasNext a predicate to apply to elements to determine when the + * stream must terminate. + * @param next a function to be applied to the previous element to produce + * a new element * @return a new sequential {@code IntStream} * @since 9 */ - public static IntStream iterate(int seed, IntPredicate predicate, IntUnaryOperator f) { - Objects.requireNonNull(f); - Objects.requireNonNull(predicate); + public static IntStream iterate(int seed, IntPredicate hasNext, IntUnaryOperator next) { + Objects.requireNonNull(next); + Objects.requireNonNull(hasNext); Spliterator.OfInt spliterator = new Spliterators.AbstractIntSpliterator(Long.MAX_VALUE, Spliterator.ORDERED | Spliterator.IMMUTABLE | Spliterator.NONNULL) { int prev; @@ -961,12 +978,12 @@ public interface IntStream extends BaseStream { return false; int t; if (started) - t = f.applyAsInt(prev); + t = next.applyAsInt(prev); else { t = seed; started = true; } - if (!predicate.test(t)) { + if (!hasNext.test(t)) { finished = true; return false; } @@ -980,10 +997,10 @@ public interface IntStream extends BaseStream { if (finished) return; finished = true; - int t = started ? f.applyAsInt(prev) : seed; - while (predicate.test(t)) { + int t = started ? next.applyAsInt(prev) : seed; + while (hasNext.test(t)) { action.accept(t); - t = f.applyAsInt(t); + t = next.applyAsInt(t); } } }; diff --git a/jdk/src/java.base/share/classes/java/util/stream/LongStream.java b/jdk/src/java.base/share/classes/java/util/stream/LongStream.java index d6428d55df5..bbdc1d00e0c 100644 --- a/jdk/src/java.base/share/classes/java/util/stream/LongStream.java +++ b/jdk/src/java.base/share/classes/java/util/stream/LongStream.java @@ -564,19 +564,23 @@ public interface LongStream extends BaseStream { *

This is a terminal * operation. * - * @param type of the result - * @param supplier a function that creates a new result container. For a - * parallel execution, this function may be called + * @param the type of the mutable result container + * @param supplier a function that creates a new mutable result container. + * For a parallel execution, this function may be called * multiple times and must return a fresh value each time. * @param accumulator an associative, * non-interfering, * stateless - * function for incorporating an additional element into a result + * function that must fold an element into a result + * container. * @param combiner an associative, * non-interfering, * stateless - * function for combining two values, which must be - * compatible with the accumulator function + * function that accepts two partial result containers + * and merges them, which must be compatible with the + * accumulator function. The combiner function must fold + * the elements from the second result container into the + * first result container. * @return the result of the reduction * @see Stream#collect(Supplier, BiConsumer, BiConsumer) */ @@ -877,6 +881,12 @@ public interface LongStream extends BaseStream { * {@code n}, will be the result of applying the function {@code f} to the * element at position {@code n - 1}. * + *

The action of applying {@code f} for one element + * happens-before + * the action of applying {@code f} for subsequent elements. For any given + * element the action may be performed in whatever thread the library + * chooses. + * * @param seed the initial element * @param f a function to be applied to the previous element to produce * a new element @@ -908,37 +918,44 @@ public interface LongStream extends BaseStream { /** * Returns a sequential ordered {@code LongStream} produced by iterative - * application of a function to an initial element, conditioned on - * satisfying the supplied predicate. The stream terminates as soon as - * the predicate returns false. + * application of the given {@code next} function to an initial element, + * conditioned on satisfying the given {@code hasNext} predicate. The + * stream terminates as soon as the {@code hasNext} predicate returns false. * - *

- * {@code LongStream.iterate} should produce the same sequence of elements - * as produced by the corresponding for-loop: + *

{@code LongStream.iterate} should produce the same sequence of elements as + * produced by the corresponding for-loop: * 

{@code
-     *     for (long index=seed; predicate.test(index); index = f.applyAsLong(index)) {
+     *     for (long index=seed; hasNext.test(index); index = next.applyAsLong(index)) {
      *         ...
      *     }
      * }
* - *

- * The resulting sequence may be empty if the predicate does not hold on - * the seed value. Otherwise the first element will be the supplied seed - * value, the next element (if present) will be the result of applying the - * function f to the seed value, and so on iteratively until the predicate - * indicates that the stream should terminate. + *

The resulting sequence may be empty if the {@code hasNext} predicate + * does not hold on the seed value. Otherwise the first element will be the + * supplied {@code seed} value, the next element (if present) will be the + * result of applying the {@code next} function to the {@code seed} value, + * and so on iteratively until the {@code hasNext} predicate indicates that + * the stream should terminate. + * + *

The action of applying the {@code hasNext} predicate to an element + * happens-before + * the action of applying the {@code next} function to that element. The + * action of applying the {@code next} function for one element + * happens-before the action of applying the {@code hasNext} + * predicate for subsequent elements. For any given element an action may + * be performed in whatever thread the library chooses. * * @param seed the initial element - * @param predicate a predicate to apply to elements to determine when the - * stream must terminate. - * @param f a function to be applied to the previous element to produce - * a new element + * @param hasNext a predicate to apply to elements to determine when the + * stream must terminate. + * @param next a function to be applied to the previous element to produce + * a new element * @return a new sequential {@code LongStream} * @since 9 */ - public static LongStream iterate(long seed, LongPredicate predicate, LongUnaryOperator f) { - Objects.requireNonNull(f); - Objects.requireNonNull(predicate); + public static LongStream iterate(long seed, LongPredicate hasNext, LongUnaryOperator next) { + Objects.requireNonNull(next); + Objects.requireNonNull(hasNext); Spliterator.OfLong spliterator = new Spliterators.AbstractLongSpliterator(Long.MAX_VALUE, Spliterator.ORDERED | Spliterator.IMMUTABLE | Spliterator.NONNULL) { long prev; @@ -951,12 +968,12 @@ public interface LongStream extends BaseStream { return false; long t; if (started) - t = f.applyAsLong(prev); + t = next.applyAsLong(prev); else { t = seed; started = true; } - if (!predicate.test(t)) { + if (!hasNext.test(t)) { finished = true; return false; } @@ -970,10 +987,10 @@ public interface LongStream extends BaseStream { if (finished) return; finished = true; - long t = started ? f.applyAsLong(prev) : seed; - while (predicate.test(t)) { + long t = started ? next.applyAsLong(prev) : seed; + while (hasNext.test(t)) { action.accept(t); - t = f.applyAsLong(t); + t = next.applyAsLong(t); } } }; diff --git a/jdk/src/java.base/share/classes/java/util/stream/Stream.java b/jdk/src/java.base/share/classes/java/util/stream/Stream.java index 7ab71a50aee..1ec21ed2b57 100644 --- a/jdk/src/java.base/share/classes/java/util/stream/Stream.java +++ b/jdk/src/java.base/share/classes/java/util/stream/Stream.java @@ -882,19 +882,23 @@ public interface Stream extends BaseStream> { * .toString(); * } * - * @param type of the result - * @param supplier a function that creates a new result container. For a - * parallel execution, this function may be called + * @param the type of the mutable result container + * @param supplier a function that creates a new mutable result container. + * For a parallel execution, this function may be called * multiple times and must return a fresh value each time. * @param accumulator an associative, * non-interfering, * stateless - * function for incorporating an additional element into a result + * function that must fold an element into a result + * container. * @param combiner an associative, * non-interfering, * stateless - * function for combining two values, which must be - * compatible with the accumulator function + * function that accepts two partial result containers + * and merges them, which must be compatible with the + * accumulator function. The combiner function must fold + * the elements from the second result container into the + * first result container. * @return the result of the reduction */ R collect(Supplier supplier, @@ -1194,6 +1198,12 @@ public interface Stream extends BaseStream> { * {@code n}, will be the result of applying the function {@code f} to the * element at position {@code n - 1}. * + *

The action of applying {@code f} for one element + * happens-before + * the action of applying {@code f} for subsequent elements. For any given + * element the action may be performed in whatever thread the library + * chooses. + * * @param the type of stream elements * @param seed the initial element * @param f a function to be applied to the previous element to produce @@ -1226,38 +1236,45 @@ public interface Stream extends BaseStream> { /** * Returns a sequential ordered {@code Stream} produced by iterative - * application of a function to an initial element, conditioned on - * satisfying the supplied predicate. The stream terminates as soon as - * the predicate returns false. + * application of the given {@code next} function to an initial element, + * conditioned on satisfying the given {@code hasNext} predicate. The + * stream terminates as soon as the {@code hasNext} predicate returns false. * - *

- * {@code Stream.iterate} should produce the same sequence of elements as + *

{@code Stream.iterate} should produce the same sequence of elements as * produced by the corresponding for-loop: * 

{@code
-     *     for (T index=seed; predicate.test(index); index = f.apply(index)) {
+     *     for (T index=seed; hasNext.test(index); index = next.apply(index)) {
      *         ...
      *     }
      * }
* - *

- * The resulting sequence may be empty if the predicate does not hold on - * the seed value. Otherwise the first element will be the supplied seed - * value, the next element (if present) will be the result of applying the - * function f to the seed value, and so on iteratively until the predicate - * indicates that the stream should terminate. + *

The resulting sequence may be empty if the {@code hasNext} predicate + * does not hold on the seed value. Otherwise the first element will be the + * supplied {@code seed} value, the next element (if present) will be the + * result of applying the {@code next} function to the {@code seed} value, + * and so on iteratively until the {@code hasNext} predicate indicates that + * the stream should terminate. + * + *

The action of applying the {@code hasNext} predicate to an element + * happens-before + * the action of applying the {@code next} function to that element. The + * action of applying the {@code next} function for one element + * happens-before the action of applying the {@code hasNext} + * predicate for subsequent elements. For any given element an action may + * be performed in whatever thread the library chooses. * * @param the type of stream elements * @param seed the initial element - * @param predicate a predicate to apply to elements to determine when the - * stream must terminate. - * @param f a function to be applied to the previous element to produce - * a new element + * @param hasNext a predicate to apply to elements to determine when the + * stream must terminate. + * @param next a function to be applied to the previous element to produce + * a new element * @return a new sequential {@code Stream} * @since 9 */ - public static Stream iterate(T seed, Predicate predicate, UnaryOperator f) { - Objects.requireNonNull(f); - Objects.requireNonNull(predicate); + public static Stream iterate(T seed, Predicate hasNext, UnaryOperator next) { + Objects.requireNonNull(next); + Objects.requireNonNull(hasNext); Spliterator spliterator = new Spliterators.AbstractSpliterator<>(Long.MAX_VALUE, Spliterator.ORDERED | Spliterator.IMMUTABLE) { T prev; @@ -1270,12 +1287,12 @@ public interface Stream extends BaseStream> { return false; T t; if (started) - t = f.apply(prev); + t = next.apply(prev); else { t = seed; started = true; } - if (!predicate.test(t)) { + if (!hasNext.test(t)) { prev = null; finished = true; return false; @@ -1290,11 +1307,11 @@ public interface Stream extends BaseStream> { if (finished) return; finished = true; - T t = started ? f.apply(prev) : seed; + T t = started ? next.apply(prev) : seed; prev = null; - while (predicate.test(t)) { + while (hasNext.test(t)) { action.accept(t); - t = f.apply(t); + t = next.apply(t); } } };