RFR: JDK-8319123 : Implementation of JEP-461: Stream Gatherers (Preview)

[ExE Boss]

On Mon, 30 Oct 2023 15:38:35 GMT, Viktor Klang <vklang at openjdk.org> wrote:

> This is a Draft PR for [JEP-461](https://openjdk.org/jeps/461)

These should probably use `{@snippet ...}`:

src/java.base/share/classes/java/util/stream/Gatherer.java line 82:

> 80:  *     }
> 81:  *     gatherer.finisher().accept(state, downstream);
> 82:  * }</pre>

Suggestion:

 * {@snippet lang="java" :
 *     Gatherer.Downstream<? super R> downstream = ...;
 *     A state = gatherer.initializer().get();
 *     for (T t : data) {
 *         gatherer.integrator().integrate(state, t, downstream);
 *     }
 *     gatherer.finisher().accept(state, downstream);
 * }

src/java.base/share/classes/java/util/stream/Gatherer.java line 103:

> 101:  *     );
> 102:  * }
> 103:  * }</pre>

Suggestion:

 * {@snippet lang="java" :
 * public static <T, R> Gatherer<T, ?, R> map(Function<? super T, ? extends R> mapper) {
 *     return Gatherer.of(
 *         (unused, element, downstream) -> // integrator
 *             downstream.push(mapper.apply(element))
 *     );
 * }
 * }

src/java.base/share/classes/java/util/stream/Gatherer.java line 116:

> 114:  *
> 115:  * Gatherer<Integer, ?, String> incrementThenToString = plusOne.andThen(intToString);
> 116:  * }</pre>

Suggestion:

 * {@snippet lang="java" :
 * // using the implementation of `map` as seen above
 * Gatherer<Integer, ?, Integer> increment = map(i -> i + 1);
 *
 * Gatherer<Object, ?, String> toString = map(i -> i.toString());
 *
 * Gatherer<Integer, ?, String> incrementThenToString = plusOne.andThen(intToString);
 * }

src/java.base/share/classes/java/util/stream/Gatherer.java line 138:

> 136:  *     );
> 137:  * }
> 138:  * }</pre>

Suggestion:

 * {@snippet lang="java" :
 * public static <T, R> Gatherer<T, ?, R> scan(
 *     Supplier<R> initial,
 *     BiFunction<? super R, ? super T, ? extends R> scanner) {
 *
 *     class State {
 *         R current = initial.get();
 *     }
 *
 *     return Gatherer.<T, State, R>ofSequential(
 *          State::new,
 *          Gatherer.Integrator.ofGreedy((state, element, downstream) -> {
 *              state.current = scanner.apply(state.current, element);
 *              return downstream.push(state.current);
 *          })
 *     );
 * }
 * }

src/java.base/share/classes/java/util/stream/Gatherer.java line 549:

> 547:             return greedy;
> 548:         }
> 549: 

Since [GH‑16213] was closed in favour of adding diamond inference to casts (e.g.: `(Integrator<>) Foo::bar` or `(Integrator.Greedy<>) Foo::bar`), these should probably be removed as well:
Suggestion:



[GH‑16213]: https://github.com/openjdk/jdk/pull/16213

src/java.base/share/classes/java/util/stream/Stream.java line 1080:

> 1078:      *     var stream1 = Stream.of(...).gather(gatherer1).gather(gatherer2);
> 1079:      *     var stream2 = Stream.of(...).gather(gatherer1.andThen(gatherer2));
> 1080:      * }</pre>

Suggestion:

     * {@snippet lang="java" :
     *     // @replace region substring="values" replacement="..."
     *     var stream1 = Stream.of(values).gather(gatherer1).gather(gatherer2);
     *     var stream2 = Stream.of(values).gather(gatherer1.andThen(gatherer2));
     *     // @end
     * }

src/java.base/share/classes/java/util/stream/Stream.java line 1085:

> 1083:      * <pre>{@code
> 1084:      * StreamSupport.stream(spliterator(), isParallel()).gather(gatherer)
> 1085:      * }</pre>

Suggestion:

     * {@snippet lang="java" :
     * StreamSupport.stream(spliterator(), isParallel()).gather(gatherer)
     * }

-------------

PR Review: https://git.openjdk.org/jdk/pull/16420#pullrequestreview-1715691921
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1383646341
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1383647033
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1383647410
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1383647839
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1380597659
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1383652617
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1383654255