OpenJDK / lambda / lambda / jdk
changeset 7785:e274aca6852b
Spec adjustments as per EG review for Stream; propagate Stream spec into {Int,Long,Double}Stream
author | briangoetz |
---|---|
date | Mon, 01 Apr 2013 15:25:22 -0400 |
parents | 523fb48c9068 |
children | 34443a93970a 90a7fdf1be54 |
files | src/share/classes/java/util/stream/DoublePipeline.java src/share/classes/java/util/stream/DoubleStream.java src/share/classes/java/util/stream/IntPipeline.java src/share/classes/java/util/stream/IntStream.java src/share/classes/java/util/stream/LongPipeline.java src/share/classes/java/util/stream/LongStream.java src/share/classes/java/util/stream/Stream.java src/share/classes/java/util/stream/package-info.java |
diffstat | 8 files changed, 2085 insertions(+), 578 deletions(-) [+] |
line wrap: on
line diff
--- a/src/share/classes/java/util/stream/DoublePipeline.java Mon Apr 01 10:42:34 2013 -0400 +++ b/src/share/classes/java/util/stream/DoublePipeline.java Mon Apr 01 15:25:22 2013 -0400 @@ -260,20 +260,20 @@ } @Override - public DoubleStream substream(long startOffset) { - if (startOffset < 0) - throw new IllegalArgumentException(Long.toString(startOffset)); - if (startOffset == 0) + public DoubleStream substream(long startingOffset) { + if (startingOffset < 0) + throw new IllegalArgumentException(Long.toString(startingOffset)); + if (startingOffset == 0) return this; else - return super.slice(startOffset, -1); + return super.slice(startingOffset, -1); } @Override - public DoubleStream substream(long startOffset, long endOffset) { - if (startOffset < 0 || endOffset < startOffset) - throw new IllegalArgumentException(String.format("substream(%d, %d)", startOffset, endOffset)); - return super.slice(startOffset, endOffset - startOffset); + public DoubleStream substream(long startingOffset, long endingOffset) { + if (startingOffset < 0 || endingOffset < startingOffset) + throw new IllegalArgumentException(String.format("substream(%d, %d)", startingOffset, endingOffset)); + return super.slice(startingOffset, endingOffset - startingOffset); } @Override
--- a/src/share/classes/java/util/stream/DoubleStream.java Mon Apr 01 10:42:34 2013 -0400 +++ b/src/share/classes/java/util/stream/DoubleStream.java Mon Apr 01 15:25:22 2013 -0400 @@ -24,9 +24,11 @@ */ package java.util.stream; -import java.util.*; +import java.util.DoubleSummaryStatistics; +import java.util.OptionalDouble; +import java.util.PrimitiveIterator; +import java.util.Spliterator; import java.util.function.BiConsumer; -import java.util.function.BooleanSupplier; import java.util.function.DoubleBinaryOperator; import java.util.function.DoubleConsumer; import java.util.function.DoubleFunction; @@ -34,17 +36,563 @@ import java.util.function.DoubleToIntFunction; import java.util.function.DoubleToLongFunction; import java.util.function.DoubleUnaryOperator; +import java.util.function.Function; import java.util.function.ObjDoubleConsumer; import java.util.function.Supplier; /** - * A sequence of {@code double} elements supporting sequential and parallel bulk operations. + * A sequence of primitive double elements supporting sequential and parallel + * bulk operations. Streams support lazy transformative operations (transforming + * a stream to another stream) such as {@code filter} and {@code map}, and + * consuming operations, such as {@code forEach}, {@code findFirst}, and {@code + * iterator}. Once an operation has been performed on a stream, it + * is considered <em>consumed</em> and no longer usable for other operations. + * + * <p>For sequential stream pipelines, all operations are performed in the + * <a href="package-summary.html#Ordering">encounter order</a> of the pipeline + * source, if the pipeline source has a defined encounter order. + * + * <p>For parallel stream pipelines, unless otherwise specified, intermediate + * stream operations preserve the <a href="package-summary.html#Ordering"> + * encounter order</a> of their source, and terminal operations + * respect the encounter order of their source, if the source + * has an encounter order. + * + * @apiNote + * Streams are not data structures; they do not manage the storage for their + * elements, nor do they support access to individual elements. However, + * you can use the {@link #iterator()} or {@link #spliterator()} operations to + * perform a controlled traversal. + * + * <p>Unless otherwise noted, passing a {@code null} argument to any stream + * method may result in a {@link NullPointerException}. * * @since 1.8 + * @see <a href="package-summary.html">java.util.stream</a> */ public interface DoubleStream extends BaseStream<Double, DoubleStream> { - // BaseStream + /** + * Produces a stream consisting of the elements of this stream that match + * the given predicate. + * + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. + * + * @param predicate A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> predicate to apply to + * each element to determine if it should be included + * @return the new stream + */ + DoubleStream filter(DoublePredicate predicate); + + /** + * Produces a stream consisting of the results of applying the given + * function to the elements of this stream. + * + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. + * + * @param mapper a <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element + * @return the new stream + */ + DoubleStream map(DoubleUnaryOperator mapper); + + /** + * Produces an object-valued {@code Stream} consisting of the results of + * applying the given function to the elements of this stream. + * + * <p>This is an <a href="package-summary.html#StreamOps"> + * intermediate operation</a>. + * + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element + * @return the new stream + */ + <U> Stream<U> mapToObj(DoubleFunction<U> mapper); + + /** + * Produces an {@code IntStream} consisting of the results of applying + * the given function to the elements of this stream. + * + * <p>This is an <a href="package-summary.html#StreamOps"> + * intermediate operation</a>. + * + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element + * @return the new stream + */ + IntStream mapToInt(DoubleToIntFunction mapper); + + /** + * Produces a {@code LongStream} consisting of the results of applying + * the given function to the elements of this stream. + * + * <p>This is an <a href="package-summary.html#StreamOps"> + * intermediate operation</a>. + * + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element + * @return the new stream + */ + LongStream mapToLong(DoubleToLongFunction mapper); + + /** + * Produces a stream consisting of the results of replacing each + * element of this stream with the contents of the stream + * produced by applying the provided function to each element. + * + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. + * + * @implNote + * <p>This implementation is likely to be less efficient than the other + * form of {@link #flatMap(FlatMapper.OfDoubleToDouble)}, and is provided for + * convenience. + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element which produces a stream of new + * values + * @return the new stream + * @see Stream#flatMap(Function) + */ + DoubleStream flatMap(DoubleFunction<? extends DoubleStream> mapper); + + /** + * Produces a stream consisting of the results of replacing each + * element of this stream with zero or more transformed values, according + * to the transformation encoded in the provided {@code FlatMapper.OfDoubleToDouble}. + * + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. + * @implNote + * This form of {@code flatMap} is usually less convenient to use than the + * {@link #flatMap(DoubleFunction)} form, but is often considerably more + * efficient because it eliminates the overhead of stream construction + * and traversal. + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> {@code FlatMapper.OfDoubleToDouble} + * that transforms each element into zero or more resulting + * values + * @return the new stream + */ + DoubleStream flatMap(FlatMapper.OfDoubleToDouble mapper); + + /** + * Produces a stream consisting of the distinct elements of this stream. + * + * <p>This is a <a href="package-summary.html#StreamOps">stateful + * intermediate operation</a>. + * @return the new stream + */ + DoubleStream distinct(); + + /** + * Produces a stream consisting of the elements of this stream in sorted + * order. + * + * <p>This is a <a href="package-summary.html#StreamOps">stateful + * intermediate operation</a>. + * @return the new stream + */ + DoubleStream sorted(); + + /** + * Produces a stream consisting of the elements of this stream, additionally + * performing the provided action on each element as elements are consumed + * from the resulting stream. + * + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. + * + * <p>For parallel stream pipelines, the action may be called at + * whatever time and in whatever thread the element is made available by the + * upstream operation. If the action modifies shared state, + * it is responsible for providing the required synchronization. + * + * @apiNote This method exists mainly to support debugging, where you want + * to see the elements as they flow past a certain point in a pipeline: + * <pre> + * list.stream() + * .filter(filteringFunction) + * .peek(e -> {System.out.println("Filtered value: " + e); }); + * .map(mappingFunction) + * .peek(e -> {System.out.println("Mapped value: " + e); }); + * .collect(Collectors.toDoubleSummaryStastistics()); + * </pre> + * + * @param consumer A <a href="package-summary.html#NonInterference"> + * non-interfering</a> action to perform on the elements as + * they are consumed from the stream + * @return the new stream + */ + DoubleStream peek(DoubleConsumer consumer); + + /** + * Produces a stream consisting of the elements of this stream, + * truncated to be no longer than {@code maxSize} in length. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * stateful intermediate operation</a>. + * + * @param maxSize the number of elements the stream should be limited to + * @return the new stream + */ + DoubleStream limit(long maxSize); + + /** + * Produces a stream consisting of the elements of this stream, + * discarding the first {@code startingOffset} elements. + * + * <p>This is a <a href="package-summary.html#StreamOps">stateful + * intermediate operation</a>. + * + * @param startingOffset the number of leading elements to be skipped + * @return the new stream + */ + DoubleStream substream(long startingOffset); + + /** + * Produces a stream consisting of the elements of this stream, + * discarding the first {@code startingOffset} elements, and truncating the + * remainder to be no longer than {@code maxSize} in length. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * stateful intermediate operation</a>. + * + * @param startingOffset the starting position of the substream, inclusive + * @param endingOffset the ending position of the substream, exclusive + * @return the new stream + */ + DoubleStream substream(long startingOffset, long endingOffset); + + /** + * Performs an operation for each element of this stream. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * <p>For parallel stream pipelines, this operation does <em>not</em> + * guarantee to respect the encounter order of the stream, as doing so + * would sacrifice the benefit of parallelism. For any given element, the + * action may be performed at whatever time and in whatever thread the + * library chooses. If the operation accesses shared state, it is + * responsible for providing the required synchronization. + * + * @param consumer A <a href="package-summary.html#NonInterference"> + * non-interfering</a> action to perform on the elements + */ + void forEach(DoubleConsumer consumer); + + /** + * Performs an operation for each element of this stream, guaranteeing that + * each element is processed in encounter order for streams that have a + * defined encounter order. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * @param consumer A <a href="package-summary.html#NonInterference"> + * non-interfering</a> action to perform on the elements + * @see #forEach(DoubleConsumer) + */ + void forEachOrdered(DoubleConsumer consumer); + + /** + * Produces an array containing the elements of this stream. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * @return an array containing the elements of this stream + */ + double[] toArray(); + + /** + * Performs a <a href="package-summary.html#Reduction">reduction</a> on the + * elements of this stream, using the provided identity value and + * an <a href="package-summary.html#Associativity">associative</a> + * accumulation function, and return the reduced value. This is equivalent + * to: + * <pre> + * double result = identity; + * for (double element : this stream) + * result = accumulator.apply(result, element) + * return result; + * </pre> + * + * but is not constrained to execute sequentially. + * + * <p>The {@code identity} value must be an identity for the accumulator + * function. This means that for all {@code x}, + * {@code accumulator.apply(identity, x)} is equal to {@code x}. + * The {@code accumulator} function must be an + * <a href="package-summary.html#Associativity">associative</a> function. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * @apiNote Sum, min, max, and average are all special cases of reduction. + * Summing a stream of numbers can be expressed as: + * + * <pre> + * double sum = numbers.reduce(0, (a, b) -> a+b); + * </pre> + * + * or more compactly: + * + * <pre> + * double sum = numbers.reduce(0, Double::sum); + * </pre> + * + * <p>While this may seem a more roundabout way to perform an aggregation + * compared to simply mutating a running total in a loop, reduction + * operations parallelize more gracefully, without needing additional + * synchronization and with greatly reduced risk of data races. + * + * @param identity The identity value for the accumulating function + * @param op An <a href="package-summary.html#Associativity">associative</a> + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for combining two values + * @return The result of the reduction + * @see #sum(), #min(), #max(), #average() + */ + double reduce(double identity, DoubleBinaryOperator op); + + /** + * Performs a <a href="package-summary.html#Reduction">reduction</a> on the + * elements of this stream, using an + * <a href="package-summary.html#Associativity">associative</a> accumulation + * function, and return an {@code OptionalDouble} describing the reduced value, + * if any. This is equivalent to: + * <pre> + * boolean foundAny = false; + * double result = null; + * for (double element : this stream) { + * if (!foundAny) { + * foundAny = true; + * result = element; + * } + * else + * result = accumulator.apply(result, element) + * return foundAny ? OptionalDouble.of(result) : OptionalDouble.empty(); + * </pre> + * + * but is not constrained to execute sequentially. + * + * <p>The {@code accumulator} function must be an + * <a href="package-summary.html#Associativity">associative</a> function. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * @param op An <a href="package-summary.html#Associativity">associative</a> + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for combining two values + * @return The result of the reduction + * @see #reduce(double, DoubleBinaryOperator) + */ + OptionalDouble reduce(DoubleBinaryOperator op); + + /** + * Performs a <a href="package-summary.html#MutableReduction">mutable + * reduction</a> operation on the elements of this stream. A mutable + * reduction is one in which the reduced value is a mutable value holder, + * such as an {@code ArrayList}, and elements are incorporated by updating + * the state of the result, rather than by replacing the result. This + * produces a result equivalent to: + * <pre> + * R result = resultFactory.get(); + * for (double element : this stream) + * accumulator.accept(result, element); + * return result; + * </pre> + * + * Like {@link #reduce(double, DoubleBinaryOperator)}, {@code collect} operations + * can be parallelized without requiring additional sychronization. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * @param resultFactory Function that creates a new result container. + * For a parallel execution, this function may be + * called multiple times and must return a fresh value + * each time. + * @param accumulator An <a href="package-summary.html#Associativity">associative</a> + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for incorporating an additional + * element into a result + * @param combiner An <a href="package-summary.html#Associativity">associative</a> + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for combining two values, which + * must be compatible with the accumulator function + * @param <R> Type of the result + * @return The result of the reduction + * @see Stream#collect(Supplier, BiConsumer, BiConsumer) + */ + <R> R collect(Supplier<R> resultFactory, + ObjDoubleConsumer<R> accumulator, + BiConsumer<R, R> combiner); + + /** + * Returns the sum of elements in this stream. This is a special case + * of a <a href="package-summary.html#MutableReduction">reduction</a> + * and is equivalent to: + * <pre> + * return reduce(0, Double::sum); + * </pre> + * @return The sum of elements in this stream + */ + double sum(); + + /** + * Returns an {@code OptionalDouble} describing the minimal element of this + * stream, or an empty optional if this stream is empty. This is a special + * case of a <a href="package-summary.html#MutableReduction">reduction</a> + * and is equivalent to: + * <pre> + * return reduce(Double::min); + * </pre> + * @return The minimal element of this stream, or an empty + * {@code OptionalDouble} + */ + OptionalDouble min(); + + /** + * Returns an {@code OptionalDouble} describing the maximal element of this + * stream, or an empty optional if this stream is empty. This is a special + * case of a <a href="package-summary.html#MutableReduction">reduction</a> + * and is equivalent to: + * <pre> + * return reduce(Double::max); + * </pre> + * @return The maximal element of this stream, or an empty + * {@code OptionalDouble} + */ + OptionalDouble max(); + + /** + * Returns the count of elements in this stream. This is a special case of + * a <a href="package-summary.html#MutableReduction">reduction</a> and is + * equivalent to: + * <pre> + * return mapToLong(e -> 1L).sum(); + * </pre> + * @return The count of elements in this stream + */ + long count(); + + /** + * Returns an {@code OptionalDouble} describing the average of elements of this + * stream, or an empty optional if this stream is empty. This is a special + * case of a <a href="package-summary.html#MutableReduction">reduction</a>. + * @return The average of elements in this stream, or an empty + * {@code OptionalDouble} + */ + OptionalDouble average(); + + /** + * Returns a {@code DoubleSummaryStatistics} describing various + * summary data about the elements of this stream. This is a special + * case of a <a href="package-summary.html#MutableReduction">reduction</a>. + * @return A {@code DoubleSummaryStatistics} describing various + * summary data about the elements of this stream + */ + DoubleSummaryStatistics summaryStatistics(); + + /** + * Returns whether any elements of this stream match the provided + * predicate. May not evaluate the predicate on all elements if + * not necessary for determining the result. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. + * + * @param predicate A <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> predicate to apply to elements of this + * stream + * @return Whether any elements of the stream match the provided predicate + */ + boolean anyMatch(DoublePredicate predicate); + + /** + * Returns whether all elements of this stream match the provided + * predicate. May not evaluate the predicate on all elements if + * not necessary for determining the result. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. + * + * @param predicate A <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> predicate to apply to elements of this stream + * @return Whether all elements of the stream match the provided predicate + */ + boolean allMatch(DoublePredicate predicate); + + /** + * Returns whether no elements of this stream match the provided + * predicate. May not evaluate the predicate on all elements if + * not necessary for determining the result. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. + * + * @param predicate A <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> predicate to apply to elements of this stream + * @return Whether no elements of the stream match the provided predicate + */ + boolean noneMatch(DoublePredicate predicate); + + /** + * Returns an {@link OptionalDouble} describing the first element of this stream + * (in the encounter order), or an empty {@code OptionalDouble} if the stream is + * empty. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. + * + * @return An {@code OptionalDouble} describing the first element of this stream, + * or an empty {@code OptionalDouble} if the stream is empty + */ + OptionalDouble findFirst(); + + /** + * Returns an {@link OptionalDouble} describing some element of the stream, or an + * empty {@code OptionalDouble} if the stream is empty. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. + * + * <p>The behavior of this operation is explicitly nondeterministic; it is + * free to select any element in the stream. This is to allow for maximal + * performance in parallel operations; the cost is that multiple invocations + * on the same source may not return the same result. (If the first element + * in the encounter order is desired, use {@link #findFirst()} instead.) + * + * @return An {@code OptionalDouble} describing some element of this stream, or an + * empty {@code OptionalDouble} if the stream is empty + * @see #findFirst() + */ + OptionalDouble findAny(); + + /** + * Returns a {@code Stream} consisting of the elements of this stream, + * boxed to {@code Double}. + * @return A {@code Stream} consistent of the elements of this stream, + * boxed to {@code Double} + */ + Stream<Double> boxed(); + + @Override + DoubleStream sequential(); + + @Override + DoubleStream parallel(); @Override PrimitiveIterator.OfDouble iterator(); @@ -52,71 +600,4 @@ @Override Spliterator.OfDouble spliterator(); - Stream<Double> boxed(); - - DoubleStream map(DoubleUnaryOperator mapper); - - <U> Stream<U> mapToObj(DoubleFunction<U> mapper); - - IntStream mapToInt(DoubleToIntFunction mapper); - - LongStream mapToLong(DoubleToLongFunction mapper); - - DoubleStream flatMap(DoubleFunction<? extends DoubleStream> mapper); - - DoubleStream flatMap(FlatMapper.OfDoubleToDouble mapper); - - DoubleStream filter(DoublePredicate predicate); - - DoubleStream peek(DoubleConsumer consumer); - - DoubleStream sorted(); - - DoubleStream distinct(); - - DoubleStream limit(long maxSize); - - DoubleStream substream(long startOffset); - - DoubleStream substream(long startOffset, long endOffset); - - DoubleStream sequential(); - - DoubleStream parallel(); - - double reduce(double identity, DoubleBinaryOperator op); - - OptionalDouble reduce(DoubleBinaryOperator op); - - <R> R collect(Supplier<R> resultFactory, - ObjDoubleConsumer<R> accumulator, - BiConsumer<R, R> combiner); - - boolean anyMatch(DoublePredicate predicate); - - boolean allMatch(DoublePredicate predicate); - - boolean noneMatch(DoublePredicate predicate); - - OptionalDouble findFirst(); - - OptionalDouble findAny(); - - void forEach(DoubleConsumer consumer); - - void forEachOrdered(DoubleConsumer consumer); - - double sum(); - - OptionalDouble min(); - - OptionalDouble max(); - - OptionalDouble average(); - - long count(); - - DoubleSummaryStatistics summaryStatistics(); - - double[] toArray(); }
--- a/src/share/classes/java/util/stream/IntPipeline.java Mon Apr 01 10:42:34 2013 -0400 +++ b/src/share/classes/java/util/stream/IntPipeline.java Mon Apr 01 15:25:22 2013 -0400 @@ -282,20 +282,20 @@ } @Override - public IntStream substream(long startOffset) { - if (startOffset < 0) - throw new IllegalArgumentException(Long.toString(startOffset)); - if (startOffset == 0) + public IntStream substream(long startingOffset) { + if (startingOffset < 0) + throw new IllegalArgumentException(Long.toString(startingOffset)); + if (startingOffset == 0) return this; else - return super.slice(startOffset, -1); + return super.slice(startingOffset, -1); } @Override - public IntStream substream(long startOffset, long endOffset) { - if (startOffset < 0 || endOffset < startOffset) - throw new IllegalArgumentException(String.format("substream(%d, %d)", startOffset, endOffset)); - return super.slice(startOffset, endOffset - startOffset); + public IntStream substream(long startingOffset, long endingOffset) { + if (startingOffset < 0 || endingOffset < startingOffset) + throw new IllegalArgumentException(String.format("substream(%d, %d)", startingOffset, endingOffset)); + return super.slice(startingOffset, endingOffset - startingOffset); } @Override
--- a/src/share/classes/java/util/stream/IntStream.java Mon Apr 01 10:42:34 2013 -0400 +++ b/src/share/classes/java/util/stream/IntStream.java Mon Apr 01 15:25:22 2013 -0400 @@ -24,9 +24,13 @@ */ package java.util.stream; -import java.util.*; +import java.util.IntSummaryStatistics; +import java.util.OptionalDouble; +import java.util.OptionalInt; +import java.util.PrimitiveIterator; +import java.util.Spliterator; import java.util.function.BiConsumer; -import java.util.function.BooleanSupplier; +import java.util.function.Function; import java.util.function.IntBinaryOperator; import java.util.function.IntConsumer; import java.util.function.IntFunction; @@ -38,157 +42,578 @@ import java.util.function.Supplier; /** - * A sequence of int elements supporting sequential and parallel bulk operations. Streams support lazy transformative - * operations (transforming a stream to another stream) such as {@code filter} and {@code map}, and consuming - * operations, such as {@code forEach}, {@code findFirst}, and {@code iterator}. Once an operation has been - * performed on a stream, it is considered <em>consumed</em> and no longer usable for other operations. + * A sequence of primitive integer elements supporting sequential and parallel + * bulk operations. Streams support lazy transformative operations (transforming + * a stream to another stream) such as {@code filter} and {@code map}, and + * consuming operations, such as {@code forEach}, {@code findFirst}, and {@code + * iterator}. Once an operation has been performed on a stream, it + * is considered <em>consumed</em> and no longer usable for other operations. + * + * <p>For sequential stream pipelines, all operations are performed in the + * <a href="package-summary.html#Ordering">encounter order</a> of the pipeline + * source, if the pipeline source has a defined encounter order. + * + * <p>For parallel stream pipelines, unless otherwise specified, intermediate + * stream operations preserve the <a href="package-summary.html#Ordering"> + * encounter order</a> of their source, and terminal operations + * respect the encounter order of their source, if the source + * has an encounter order. * * @apiNote - * Streams are not data structures; they do not manage the storage for their elements, nor do they support access - * to individual elements. However, you can use the {@link #iterator()} or {@link #spliterator()} operations to + * Streams are not data structures; they do not manage the storage for their + * elements, nor do they support access to individual elements. However, + * you can use the {@link #iterator()} or {@link #spliterator()} operations to * perform a controlled traversal. + * + * <p>Unless otherwise noted, passing a {@code null} argument to any stream + * method may result in a {@link NullPointerException}. + * * @since 1.8 + * @see <a href="package-summary.html">java.util.stream</a> */ public interface IntStream extends BaseStream<Integer, IntStream> { + /** + * Produces a stream consisting of the elements of this stream that match + * the given predicate. + * + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. + * + * @param predicate A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> predicate to apply to + * each element to determine if it should be included + * @return the new stream + */ + IntStream filter(IntPredicate predicate); + + /** + * Produces a stream consisting of the results of applying the given + * function to the elements of this stream. + * + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. + * + * @param mapper a <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element + * @return the new stream + */ + IntStream map(IntUnaryOperator mapper); + + /** + * Produces an object-valued {@code Stream} consisting of the results of + * applying the given function to the elements of this stream. + * + * <p>This is an <a href="package-summary.html#StreamOps"> + * intermediate operation</a>. + * + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element + * @return the new stream + */ + <U> Stream<U> mapToObj(IntFunction<U> mapper); + + /** + * Produces a {@code LongStream} consisting of the results of applying + * the given function to the elements of this stream. + * + * <p>This is an <a href="package-summary.html#StreamOps"> + * intermediate operation</a>. + * + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element + * @return the new stream + */ + LongStream mapToLong(IntToLongFunction mapper); + + /** + * Produces a {@code DoubleStream} consisting of the results of applying + * the given function to the elements of this stream. + * + * <p>This is an <a href="package-summary.html#StreamOps"> + * intermediate operation</a>. + * + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element + * @return the new stream + */ + DoubleStream mapToDouble(IntToDoubleFunction mapper); + + /** + * Produces a stream consisting of the results of replacing each + * element of this stream with the contents of the stream + * produced by applying the provided function to each element. + * + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. + * + * @implNote + * <p>This implementation is likely to be less efficient than the other + * form of {@link #flatMap(FlatMapper.OfIntToInt)}, and is provided for + * convenience. + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element which produces an {@code IntStream} of new + * values + * @return the new stream + * @see Stream#flatMap(Function) + */ + IntStream flatMap(IntFunction<? extends IntStream> mapper); + + /** + * Produces a stream consisting of the results of replacing each + * element of this stream with zero or more transformed values, according + * to the transformation encoded in the provided {@code FlatMapper.OfIntToInt}. + * + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. + * @implNote + * This form of {@code flatMap} is usually less convenient to use than the + * {@link #flatMap(IntFunction)} form, but is often considerably more + * efficient because it eliminates the overhead of stream construction + * and traversal. + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> {@code FlatMapper.OfIntToInt} + * that transforms each element into zero or more resulting + * values + * @return the new stream + */ + IntStream flatMap(FlatMapper.OfIntToInt mapper); + + /** + * Produces a stream consisting of the distinct elements of this stream. + * + * <p>This is a <a href="package-summary.html#StreamOps">stateful + * intermediate operation</a>. + * @return the new stream + */ + IntStream distinct(); + + /** + * Produces a stream consisting of the elements of this stream in sorted + * order. + * + * <p>This is a <a href="package-summary.html#StreamOps">stateful + * intermediate operation</a>. + * @return the new stream + */ + IntStream sorted(); + + /** + * Produces a stream consisting of the elements of this stream, additionally + * performing the provided action on each element as elements are consumed + * from the resulting stream. + * + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. + * + * <p>For parallel stream pipelines, the action may be called at + * whatever time and in whatever thread the element is made available by the + * upstream operation. If the action modifies shared state, + * it is responsible for providing the required synchronization. + * + * @apiNote This method exists mainly to support debugging, where you want + * to see the elements as they flow past a certain point in a pipeline: + * <pre> + * list.stream() + * .filter(filteringFunction) + * .peek(e -> {System.out.println("Filtered value: " + e); }); + * .map(mappingFunction) + * .peek(e -> {System.out.println("Mapped value: " + e); }); + * .collect(Collectors.toIntSummaryStastistics()); + * </pre> + * + * @param consumer A <a href="package-summary.html#NonInterference"> + * non-interfering</a> action to perform on the elements as + * they are consumed from the stream + * @return the new stream + */ + IntStream peek(IntConsumer consumer); + + /** + * Produces a stream consisting of the elements of this stream, + * truncated to be no longer than {@code maxSize} in length. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * stateful intermediate operation</a>. + * + * @param maxSize the number of elements the stream should be limited to + * @return the new stream + */ + IntStream limit(long maxSize); + + /** + * Produces a stream consisting of the elements of this stream, + * discarding the first {@code startingOffset} elements. + * + * <p>This is a <a href="package-summary.html#StreamOps">stateful + * intermediate operation</a>. + * + * @param startingOffset the number of leading elements to be skipped + * @return the new stream + */ + IntStream substream(long startingOffset); + + /** + * Produces a stream consisting of the elements of this stream, + * discarding the first {@code startingOffset} elements, and truncating the + * remainder to be no longer than {@code maxSize} in length. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * stateful intermediate operation</a>. + * + * @param startingOffset the starting position of the substream, inclusive + * @param endingOffset the ending position of the substream, exclusive + * @return the new stream + */ + IntStream substream(long startingOffset, long endingOffset); + + /** + * Performs an operation for each element of this stream. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * <p>For parallel stream pipelines, this operation does <em>not</em> + * guarantee to respect the encounter order of the stream, as doing so + * would sacrifice the benefit of parallelism. For any given element, the + * action may be performed at whatever time and in whatever thread the + * library chooses. If the operation accesses shared state, it is + * responsible for providing the required synchronization. + * + * @param consumer A <a href="package-summary.html#NonInterference"> + * non-interfering</a> action to perform on the elements + */ + void forEach(IntConsumer consumer); + + /** + * Performs an operation for each element of this stream, guaranteeing that + * each element is processed in encounter order for streams that have a + * defined encounter order. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * @param consumer A <a href="package-summary.html#NonInterference"> + * non-interfering</a> action to perform on the elements + * @see #forEach(IntConsumer) + */ + void forEachOrdered(IntConsumer consumer); + + /** + * Produces an array containing the elements of this stream. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * @return an array containing the elements of this stream + */ + int[] toArray(); + + /** + * Performs a <a href="package-summary.html#Reduction">reduction</a> on the + * elements of this stream, using the provided identity value and + * an <a href="package-summary.html#Associativity">associative</a> + * accumulation function, and return the reduced value. This is equivalent + * to: + * <pre> + * int result = identity; + * for (int element : this stream) + * result = accumulator.apply(result, element) + * return result; + * </pre> + * + * but is not constrained to execute sequentially. + * + * <p>The {@code identity} value must be an identity for the accumulator + * function. This means that for all {@code x}, + * {@code accumulator.apply(identity, x)} is equal to {@code x}. + * The {@code accumulator} function must be an + * <a href="package-summary.html#Associativity">associative</a> function. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * @apiNote Sum, min, max, and average are all special cases of reduction. + * Summing a stream of numbers can be expressed as: + * + * <pre> + * int sum = integers.reduce(0, (a, b) -> a+b); + * </pre> + * + * or more compactly: + * + * <pre> + * int sum = integers.reduce(0, Integer::sum); + * </pre> + * + * <p>While this may seem a more roundabout way to perform an aggregation + * compared to simply mutating a running total in a loop, reduction + * operations parallelize more gracefully, without needing additional + * synchronization and with greatly reduced risk of data races. + * + * @param identity The identity value for the accumulating function + * @param op An <a href="package-summary.html#Associativity">associative</a> + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for combining two values + * @return The result of the reduction + * @see #sum(), #min(), #max(), #average() + */ + int reduce(int identity, IntBinaryOperator op); + + /** + * Performs a <a href="package-summary.html#Reduction">reduction</a> on the + * elements of this stream, using an + * <a href="package-summary.html#Associativity">associative</a> accumulation + * function, and return an {@code OptionalInt} describing the reduced value, + * if any. This is equivalent to: + * <pre> + * boolean foundAny = false; + * int result = null; + * for (int element : this stream) { + * if (!foundAny) { + * foundAny = true; + * result = element; + * } + * else + * result = accumulator.apply(result, element) + * return foundAny ? OptionalInt.of(result) : OptionalInt.empty(); + * </pre> + * + * but is not constrained to execute sequentially. + * + * <p>The {@code accumulator} function must be an + * <a href="package-summary.html#Associativity">associative</a> function. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * @param op An <a href="package-summary.html#Associativity">associative</a> + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for combining two values + * @return The result of the reduction + * @see #reduce(int, IntBinaryOperator) + */ + OptionalInt reduce(IntBinaryOperator op); + + /** + * Performs a <a href="package-summary.html#MutableReduction">mutable + * reduction</a> operation on the elements of this stream. A mutable + * reduction is one in which the reduced value is a mutable value holder, + * such as an {@code ArrayList}, and elements are incorporated by updating + * the state of the result, rather than by replacing the result. This + * produces a result equivalent to: + * <pre> + * R result = resultFactory.get(); + * for (int element : this stream) + * accumulator.accept(result, element); + * return result; + * </pre> + * + * Like {@link #reduce(int, IntBinaryOperator)}, {@code collect} operations + * can be parallelized without requiring additional sychronization. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * @param resultFactory Function that creates a new result container. + * For a parallel execution, this function may be + * called multiple times and must return a fresh value + * each time. + * @param accumulator An <a href="package-summary.html#Associativity">associative</a> + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for incorporating an additional + * element into a result + * @param combiner An <a href="package-summary.html#Associativity">associative</a> + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for combining two values, which + * must be compatible with the accumulator function + * @param <R> Type of the result + * @return The result of the reduction + * @see Stream#collect(Supplier, BiConsumer, BiConsumer) + */ + <R> R collect(Supplier<R> resultFactory, + ObjIntConsumer<R> accumulator, + BiConsumer<R, R> combiner); + + /** + * Returns the sum of elements in this stream. This is a special case + * of a <a href="package-summary.html#MutableReduction">reduction</a> + * and is equivalent to: + * <pre> + * return reduce(0, Integer::sum); + * </pre> + * @return The sum of elements in this stream + */ + int sum(); + + /** + * Returns an {@code OptionalInt} describing the minimal element of this + * stream, or an empty optional if this stream is empty. This is a special + * case of a <a href="package-summary.html#MutableReduction">reduction</a> + * and is equivalent to: + * <pre> + * return reduce(Integer::min); + * </pre> + * @return The minimal element of this stream, or an empty + * {@code OptionalInt} + */ + OptionalInt min(); + + /** + * Returns an {@code OptionalInt} describing the maximal element of this + * stream, or an empty optional if this stream is empty. This is a special + * case of a <a href="package-summary.html#MutableReduction">reduction</a> + * and is equivalent to: + * <pre> + * return reduce(Integer::max); + * </pre> + * @return The maximal element of this stream, or an empty + * {@code OptionalInt} + */ + OptionalInt max(); + + /** + * Returns the count of elements in this stream. This is a special case of + * a <a href="package-summary.html#MutableReduction">reduction</a> and is + * equivalent to: + * <pre> + * return mapToLong(e -> 1L).sum(); + * </pre> + * @return The count of elements in this stream + */ + long count(); + + /** + * Returns an {@code OptionalDouble} describing the average of elements of this + * stream, or an empty optional if this stream is empty. This is a special + * case of a <a href="package-summary.html#MutableReduction">reduction</a>. + * @return The average of elements in this stream, or an empty + * {@code OptionalDouble} + */ + OptionalDouble average(); + + /** + * Returns an {@code IntSummaryStatistics} describing various + * summary data about the elements of this stream. This is a special + * case of a <a href="package-summary.html#MutableReduction">reduction</a>. + * @return An {@code IntSummaryStatistics} describing various + * summary data about the elements of this stream + */ + IntSummaryStatistics summaryStatistics(); + + /** + * Returns whether any elements of this stream match the provided + * predicate. May not evaluate the predicate on all elements if + * not necessary for determining the result. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. + * + * @param predicate A <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> predicate to apply to elements of this + * stream + * @return Whether any elements of the stream match the provided predicate + */ + boolean anyMatch(IntPredicate predicate); + + /** + * Returns whether all elements of this stream match the provided + * predicate. May not evaluate the predicate on all elements if + * not necessary for determining the result. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. + * + * @param predicate A <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> predicate to apply to elements of this stream + * @return Whether all elements of the stream match the provided predicate + */ + boolean allMatch(IntPredicate predicate); + + /** + * Returns whether no elements of this stream match the provided + * predicate. May not evaluate the predicate on all elements if + * not necessary for determining the result. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. + * + * @param predicate A <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> predicate to apply to elements of this stream + * @return Whether no elements of the stream match the provided predicate + */ + boolean noneMatch(IntPredicate predicate); + + /** + * Returns an {@link OptionalInt} describing the first element of this stream + * (in the encounter order), or an empty {@code OptionalInt} if the stream is + * empty. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. + * + * @return An {@code OptionalInt} describing the first element of this stream, + * or an empty {@code OptionalInt} if the stream is empty + */ + OptionalInt findFirst(); + + /** + * Returns an {@link OptionalInt} describing some element of the stream, or an + * empty {@code OptionalInt} if the stream is empty. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. + * + * <p>The behavior of this operation is explicitly nondeterministic; it is + * free to select any element in the stream. This is to allow for maximal + * performance in parallel operations; the cost is that multiple invocations + * on the same source may not return the same result. (If the first element + * in the encounter order is desired, use {@link #findFirst()} instead.) + * + * @return An {@code OptionalInt} describing some element of this stream, or an + * empty {@code OptionalInt} if the stream is empty + * @see #findFirst() + */ + OptionalInt findAny(); + + /** + * Returns a {@code LongStream} consisting of the elements of this stream, + * converted to {@code long}. + * @return A {@code LongStream} consisting of the elements of this stream, + * converted to {@code long} + */ + LongStream longs(); + + /** + * Returns a {@code DoubleStream} consisting of the elements of this stream, + * converted to {@code double}. + * @return A {@code DoubleStream} consisting of the elements of this stream, + * converted to {@code double} + */ + DoubleStream doubles(); + + /** + * Returns a {@code Stream} consisting of the elements of this stream, + * boxed to {@code Integer}. + * @return A {@code Stream} consistent of the elements of this stream, + * boxed to {@code Integer} + */ + Stream<Integer> boxed(); + + @Override + IntStream sequential(); + + @Override + IntStream parallel(); + @Override PrimitiveIterator.OfInt iterator(); @Override Spliterator.OfInt spliterator(); - - LongStream longs(); - - DoubleStream doubles(); - - Stream<Integer> boxed(); - - /** - * Transform this stream into one consisting of the elements that match the given {@code IntPredicate}. This is - * an <a href="package-summary.html#StreamOps">intermediate operation</a>. - * @param predicate The test criteria to apply to each element to determine if it should be included in the output - * @return the new stream - */ - IntStream filter(IntPredicate predicate); - - /** - * Transform this stream into one consisting of the result of applying the given function to the - * elements of this stream. This is an <a href="package-summary.html#StreamOps">intermediate operation</a>. - * @param mapper The function to be applied to each element - * @return the new stream - */ - IntStream map(IntUnaryOperator mapper); - - /** - * Transform this stream into one consisting of the result of applying the given function to the - * elements of this stream. This is an <a href="package-summary.html#StreamOps">intermediate operation</a>. - * @param mapper The function to be applied to each element - * @return the new stream - */ - <U> Stream<U> mapToObj(IntFunction<U> mapper); - - /** - * Transform this stream into one consisting of the result of applying the given function to the - * elements of this stream. This is an <a href="package-summary.html#StreamOps">intermediate operation</a>. - * @param mapper The function to be applied to each element - * @return the new stream - */ - LongStream mapToLong(IntToLongFunction mapper); - - /** - * Transform this stream into one consisting of the result of applying the given function to the - * elements of this stream. This is an <a href="package-summary.html#StreamOps">intermediate operation</a>. - * @param mapper The function to be applied to each element - * @return the new stream - */ - DoubleStream mapToDouble(IntToDoubleFunction mapper); - - /** - * Transform this stream into one where each element is replaced with the contents of the stream produced - * by applying the provided function to that element. This is - * an <a href="package-summary.html#StreamOps">intermediate operation</a>. - * @implNote - * This implementation is generally less efficient than the other form of - * {@link #flatMap(FlatMapper.OfIntToInt)}, and is provided for convenience. - * @param mapper The function to be applied to each element, resulting in an {@code IntStream} of new values - * @return the new stream - */ - IntStream flatMap(IntFunction<? extends IntStream> mapper); - - /** - * Transform this stream into one where each element is replaced with zero or more transformed values, - * according to the transformation encoded in the provided {@code FlatMapper.OfIntToInt}. This is - * an <a href="package-summary.html#StreamOps">intermediate operation</a>. - * @apiNote - * A {@code FlatMapper} is like a function that received an element to transform, and a {@code Consumer} into which - * to deposit zero or more values corresponding to that element. For example, to map a stream of numbers to a - * stream of prime factors of those numbers: - * <pre> - * stringStream.flatMap((elt, destination) -> { - * for (i=2; i < elt; i++) - * if (elt % i == 0 && isPrime(i)) - * destination.accept(i); - * }) - * ... - * </pre> - * @implNote - * This form of {@code flatMap} is usually less convenient to use than the {@link #flatMap(IntFunction)} form, - * but is often considerably more efficient because it eliminates the overhead of stream construction and - * traversal. - * @param mapper The {@code FlatMapper.OfIntToInt} that transforms each element into zero or more resulting values - * @return the new stream - */ - IntStream flatMap(FlatMapper.OfIntToInt mapper); - - IntStream peek(IntConsumer consumer); - - IntStream sorted(); - - IntStream distinct(); - - IntStream limit(long maxSize); - - IntStream substream(long startOffset); - - IntStream substream(long startOffset, long endOffset); - - IntStream sequential(); - - IntStream parallel(); - - int reduce(int identity, IntBinaryOperator op); - - OptionalInt reduce(IntBinaryOperator op); - - <R> R collect(Supplier<R> resultFactory, - ObjIntConsumer<R> accumulator, - BiConsumer<R, R> combiner); - - boolean anyMatch(IntPredicate predicate); - - boolean allMatch(IntPredicate predicate); - - boolean noneMatch(IntPredicate predicate); - - OptionalInt findFirst(); - - OptionalInt findAny(); - - void forEach(IntConsumer consumer); - - void forEachOrdered(IntConsumer consumer); - - int sum(); - - OptionalInt min(); - - OptionalInt max(); - - long count(); - - OptionalDouble average(); - - IntSummaryStatistics summaryStatistics(); - - int[] toArray(); }
--- a/src/share/classes/java/util/stream/LongPipeline.java Mon Apr 01 10:42:34 2013 -0400 +++ b/src/share/classes/java/util/stream/LongPipeline.java Mon Apr 01 15:25:22 2013 -0400 @@ -272,20 +272,20 @@ } @Override - public LongStream substream(long startOffset) { - if (startOffset < 0) - throw new IllegalArgumentException(Long.toString(startOffset)); - if (startOffset == 0) + public LongStream substream(long startingOffset) { + if (startingOffset < 0) + throw new IllegalArgumentException(Long.toString(startingOffset)); + if (startingOffset == 0) return this; else - return super.slice(startOffset, -1); + return super.slice(startingOffset, -1); } @Override - public LongStream substream(long startOffset, long endOffset) { - if (startOffset < 0 || endOffset < startOffset) - throw new IllegalArgumentException(String.format("substream(%d, %d)", startOffset, endOffset)); - return super.slice(startOffset, endOffset - startOffset); + public LongStream substream(long startingOffset, long endingOffset) { + if (startingOffset < 0 || endingOffset < startingOffset) + throw new IllegalArgumentException(String.format("substream(%d, %d)", startingOffset, endingOffset)); + return super.slice(startingOffset, endingOffset - startingOffset); } @Override
--- a/src/share/classes/java/util/stream/LongStream.java Mon Apr 01 10:42:34 2013 -0400 +++ b/src/share/classes/java/util/stream/LongStream.java Mon Apr 01 15:25:22 2013 -0400 @@ -24,9 +24,13 @@ */ package java.util.stream; -import java.util.*; +import java.util.LongSummaryStatistics; +import java.util.OptionalDouble; +import java.util.OptionalLong; +import java.util.PrimitiveIterator; +import java.util.Spliterator; import java.util.function.BiConsumer; -import java.util.function.BooleanSupplier; +import java.util.function.Function; import java.util.function.LongBinaryOperator; import java.util.function.LongConsumer; import java.util.function.LongFunction; @@ -38,87 +42,570 @@ import java.util.function.Supplier; /** - * A sequence of {@code long} elements supporting sequential and parallel bulk operations. + * A sequence of primitive long elements supporting sequential and parallel + * bulk operations. Streams support lazy transformative operations (transforming + * a stream to another stream) such as {@code filter} and {@code map}, and + * consuming operations, such as {@code forEach}, {@code findFirst}, and {@code + * iterator}. Once an operation has been performed on a stream, it + * is considered <em>consumed</em> and no longer usable for other operations. + * + * <p>For sequential stream pipelines, all operations are performed in the + * <a href="package-summary.html#Ordering">encounter order</a> of the pipeline + * source, if the pipeline source has a defined encounter order. + * + * <p>For parallel stream pipelines, unless otherwise specified, intermediate + * stream operations preserve the <a href="package-summary.html#Ordering"> + * encounter order</a> of their source, and terminal operations + * respect the encounter order of their source, if the source + * has an encounter order. + * + * @apiNote + * Streams are not data structures; they do not manage the storage for their + * elements, nor do they support access to individual elements. However, + * you can use the {@link #iterator()} or {@link #spliterator()} operations to + * perform a controlled traversal. + * + * <p>Unless otherwise noted, passing a {@code null} argument to any stream + * method may result in a {@link NullPointerException}. * * @since 1.8 + * @see <a href="package-summary.html">java.util.stream</a> */ public interface LongStream extends BaseStream<Long, LongStream> { - // BaseStream + /** + * Produces a stream consisting of the elements of this stream that match + * the given predicate. + * + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. + * + * @param predicate A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> predicate to apply to + * each element to determine if it should be included + * @return the new stream + */ + LongStream filter(LongPredicate predicate); + + /** + * Produces a stream consisting of the results of applying the given + * function to the elements of this stream. + * + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. + * + * @param mapper a <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element + * @return the new stream + */ + LongStream map(LongUnaryOperator mapper); + + /** + * Produces an object-valued {@code Stream} consisting of the results of + * applying the given function to the elements of this stream. + * + * <p>This is an <a href="package-summary.html#StreamOps"> + * intermediate operation</a>. + * + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element + * @return the new stream + */ + <U> Stream<U> mapToObj(LongFunction<U> mapper); + + /** + * Produces an {@code IntStream} consisting of the results of applying + * the given function to the elements of this stream. + * + * <p>This is an <a href="package-summary.html#StreamOps"> + * intermediate operation</a>. + * + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element + * @return the new stream + */ + IntStream mapToInt(LongToIntFunction mapper); + + /** + * Produces a {@code DoubleStream} consisting of the results of applying + * the given function to the elements of this stream. + * + * <p>This is an <a href="package-summary.html#StreamOps"> + * intermediate operation</a>. + * + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element + * @return the new stream + */ + DoubleStream mapToDouble(LongToDoubleFunction mapper); + + /** + * Produces a stream consisting of the results of replacing each + * element of this stream with the contents of the stream + * produced by applying the provided function to each element. + * + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. + * + * @implNote + * <p>This implementation is likely to be less efficient than the other + * form of {@link #flatMap(FlatMapper.OfLongToLong)}, and is provided for + * convenience. + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element which produces an stream of new + * values + * @return the new stream + * @see Stream#flatMap(Function) + */ + LongStream flatMap(LongFunction<? extends LongStream> mapper); + + /** + * Produces a stream consisting of the results of replacing each + * element of this stream with zero or more transformed values, according + * to the transformation encoded in the provided {@code FlatMapper.OfLongToLong}. + * + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. + * @implNote + * This form of {@code flatMap} is usually less convenient to use than the + * {@link #flatMap(LongFunction)} form, but is often considerably more + * efficient because it eliminates the overhead of stream construction + * and traversal. + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> {@code FlatMapper.OfLongToLong} + * that transforms each element into zero or more resulting + * values + * @return the new stream + */ + LongStream flatMap(FlatMapper.OfLongToLong mapper); + + /** + * Produces a stream consisting of the distinct elements of this stream. + * + * <p>This is a <a href="package-summary.html#StreamOps">stateful + * intermediate operation</a>. + * @return the new stream + */ + LongStream distinct(); + + /** + * Produces a stream consisting of the elements of this stream in sorted + * order. + * + * <p>This is a <a href="package-summary.html#StreamOps">stateful + * intermediate operation</a>. + * @return the new stream + */ + LongStream sorted(); + + /** + * Produces a stream consisting of the elements of this stream, additionally + * performing the provided action on each element as elements are consumed + * from the resulting stream. + * + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. + * + * <p>For parallel stream pipelines, the action may be called at + * whatever time and in whatever thread the element is made available by the + * upstream operation. If the action modifies shared state, + * it is responsible for providing the required synchronization. + * + * @apiNote This method exists mainly to support debugging, where you want + * to see the elements as they flow past a certain point in a pipeline: + * <pre> + * list.stream() + * .filter(filteringFunction) + * .peek(e -> {System.out.println("Filtered value: " + e); }); + * .map(mappingFunction) + * .peek(e -> {System.out.println("Mapped value: " + e); }); + * .collect(Collectors.toLongSummaryStastistics()); + * </pre> + * + * @param consumer A <a href="package-summary.html#NonInterference"> + * non-interfering</a> action to perform on the elements as + * they are consumed from the stream + * @return the new stream + */ + LongStream peek(LongConsumer consumer); + + /** + * Produces a stream consisting of the elements of this stream, + * truncated to be no longer than {@code maxSize} in length. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * stateful intermediate operation</a>. + * + * @param maxSize the number of elements the stream should be limited to + * @return the new stream + */ + LongStream limit(long maxSize); + + /** + * Produces a stream consisting of the elements of this stream, + * discarding the first {@code startingOffset} elements. + * + * <p>This is a <a href="package-summary.html#StreamOps">stateful + * intermediate operation</a>. + * + * @param startingOffset the number of leading elements to be skipped + * @return the new stream + */ + LongStream substream(long startingOffset); + + /** + * Produces a stream consisting of the elements of this stream, + * discarding the first {@code startingOffset} elements, and truncating the + * remainder to be no longer than {@code maxSize} in length. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * stateful intermediate operation</a>. + * + * @param startingOffset the starting position of the substream, inclusive + * @param endingOffset the ending position of the substream, exclusive + * @return the new stream + */ + LongStream substream(long startingOffset, long endingOffset); + + /** + * Performs an operation for each element of this stream. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * <p>For parallel stream pipelines, this operation does <em>not</em> + * guarantee to respect the encounter order of the stream, as doing so + * would sacrifice the benefit of parallelism. For any given element, the + * action may be performed at whatever time and in whatever thread the + * library chooses. If the operation accesses shared state, it is + * responsible for providing the required synchronization. + * + * @param consumer A <a href="package-summary.html#NonInterference"> + * non-interfering</a> action to perform on the elements + */ + void forEach(LongConsumer consumer); + + /** + * Performs an operation for each element of this stream, guaranteeing that + * each element is processed in encounter order for streams that have a + * defined encounter order. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * @param consumer A <a href="package-summary.html#NonInterference"> + * non-interfering</a> action to perform on the elements + * @see #forEach(LongConsumer) + */ + void forEachOrdered(LongConsumer consumer); + + /** + * Produces an array containing the elements of this stream. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * @return an array containing the elements of this stream + */ + long[] toArray(); + + /** + * Performs a <a href="package-summary.html#Reduction">reduction</a> on the + * elements of this stream, using the provided identity value and + * an <a href="package-summary.html#Associativity">associative</a> + * accumulation function, and return the reduced value. This is equivalent + * to: + * <pre> + * long result = identity; + * for (long element : this stream) + * result = accumulator.apply(result, element) + * return result; + * </pre> + * + * but is not constrained to execute sequentially. + * + * <p>The {@code identity} value must be an identity for the accumulator + * function. This means that for all {@code x}, + * {@code accumulator.apply(identity, x)} is equal to {@code x}. + * The {@code accumulator} function must be an + * <a href="package-summary.html#Associativity">associative</a> function. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * @apiNote Sum, min, max, and average are all special cases of reduction. + * Summing a stream of numbers can be expressed as: + * + * <pre> + * long sum = integers.reduce(0, (a, b) -> a+b); + * </pre> + * + * or more compactly: + * + * <pre> + * long sum = integers.reduce(0, Long::sum); + * </pre> + * + * <p>While this may seem a more roundabout way to perform an aggregation + * compared to simply mutating a running total in a loop, reduction + * operations parallelize more gracefully, without needing additional + * synchronization and with greatly reduced risk of data races. + * + * @param identity The identity value for the accumulating function + * @param op An <a href="package-summary.html#Associativity">associative</a> + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for combining two values + * @return The result of the reduction + * @see #sum(), #min(), #max(), #average() + */ + long reduce(long identity, LongBinaryOperator op); + + /** + * Performs a <a href="package-summary.html#Reduction">reduction</a> on the + * elements of this stream, using an + * <a href="package-summary.html#Associativity">associative</a> accumulation + * function, and return an {@code OptionalLong} describing the reduced value, + * if any. This is equivalent to: + * <pre> + * boolean foundAny = false; + * long result = null; + * for (long element : this stream) { + * if (!foundAny) { + * foundAny = true; + * result = element; + * } + * else + * result = accumulator.apply(result, element) + * return foundAny ? OptionalLong.of(result) : OptionalLong.empty(); + * </pre> + * + * but is not constrained to execute sequentially. + * + * <p>The {@code accumulator} function must be an + * <a href="package-summary.html#Associativity">associative</a> function. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * @param op An <a href="package-summary.html#Associativity">associative</a> + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for combining two values + * @return The result of the reduction + * @see #reduce(long, LongBinaryOperator) + */ + OptionalLong reduce(LongBinaryOperator op); + + /** + * Performs a <a href="package-summary.html#MutableReduction">mutable + * reduction</a> operation on the elements of this stream. A mutable + * reduction is one in which the reduced value is a mutable value holder, + * such as an {@code ArrayList}, and elements are incorporated by updating + * the state of the result, rather than by replacing the result. This + * produces a result equivalent to: + * <pre> + * R result = resultFactory.get(); + * for (long element : this stream) + * accumulator.accept(result, element); + * return result; + * </pre> + * + * Like {@link #reduce(long, LongBinaryOperator)}, {@code collect} operations + * can be parallelized without requiring additional sychronization. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * @param resultFactory Function that creates a new result container. + * For a parallel execution, this function may be + * called multiple times and must return a fresh value + * each time. + * @param accumulator An <a href="package-summary.html#Associativity">associative</a> + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for incorporating an additional + * element into a result + * @param combiner An <a href="package-summary.html#Associativity">associative</a> + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for combining two values, which + * must be compatible with the accumulator function + * @param <R> Type of the result + * @return The result of the reduction + * @see Stream#collect(Supplier, BiConsumer, BiConsumer) + */ + <R> R collect(Supplier<R> resultFactory, + ObjLongConsumer<R> accumulator, + BiConsumer<R, R> combiner); + + /** + * Returns the sum of elements in this stream. This is a special case + * of a <a href="package-summary.html#MutableReduction">reduction</a> + * and is equivalent to: + * <pre> + * return reduce(0, Long::sum); + * </pre> + * @return The sum of elements in this stream + */ + long sum(); + + /** + * Returns an {@code OptionalLong} describing the minimal element of this + * stream, or an empty optional if this stream is empty. This is a special + * case of a <a href="package-summary.html#MutableReduction">reduction</a> + * and is equivalent to: + * <pre> + * return reduce(Long::min); + * </pre> + * @return The minimal element of this stream, or an empty + * {@code OptionalLong} + */ + OptionalLong min(); + + /** + * Returns an {@code OptionalLong} describing the maximal element of this + * stream, or an empty optional if this stream is empty. This is a special + * case of a <a href="package-summary.html#MutableReduction">reduction</a> + * and is equivalent to: + * <pre> + * return reduce(Long::max); + * </pre> + * @return The maximal element of this stream, or an empty + * {@code OptionalLong} + */ + OptionalLong max(); + + /** + * Returns the count of elements in this stream. This is a special case of + * a <a href="package-summary.html#MutableReduction">reduction</a> and is + * equivalent to: + * <pre> + * return map(e -> 1).sum(); + * </pre> + * @return The count of elements in this stream + */ + long count(); + + /** + * Returns an {@code OptionalDouble} describing the average of elements of this + * stream, or an empty optional if this stream is empty. This is a special + * case of a <a href="package-summary.html#MutableReduction">reduction</a>. + * @return The average of elements in this stream, or an empty + * {@code OptionalDouble} + */ + OptionalDouble average(); + + /** + * Returns a {@code LongSummaryStatistics} describing various + * summary data about the elements of this stream. This is a special + * case of a <a href="package-summary.html#MutableReduction">reduction</a>. + * @return A {@code LongSummaryStatistics} describing various + * summary data about the elements of this stream + */ + LongSummaryStatistics summaryStatistics(); + + /** + * Returns whether any elements of this stream match the provided + * predicate. May not evaluate the predicate on all elements if + * not necessary for determining the result. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. + * + * @param predicate A <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> predicate to apply to elements of this + * stream + * @return Whether any elements of the stream match the provided predicate + */ + boolean anyMatch(LongPredicate predicate); + + /** + * Returns whether all elements of this stream match the provided + * predicate. May not evaluate the predicate on all elements if + * not necessary for determining the result. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. + * + * @param predicate A <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> predicate to apply to elements of this stream + * @return Whether all elements of the stream match the provided predicate + */ + boolean allMatch(LongPredicate predicate); + + /** + * Returns whether no elements of this stream match the provided + * predicate. May not evaluate the predicate on all elements if + * not necessary for determining the result. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. + * + * @param predicate A <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> predicate to apply to elements of this stream + * @return Whether no elements of the stream match the provided predicate + */ + boolean noneMatch(LongPredicate predicate); + + /** + * Returns an {@link OptionalLong} describing the first element of this stream + * (in the encounter order), or an empty {@code OptionalLong} if the stream is + * empty. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. + * + * @return An {@code OptionalLong} describing the first element of this stream, + * or an empty {@code OptionalLong} if the stream is empty + */ + OptionalLong findFirst(); + + /** + * Returns an {@link OptionalLong} describing some element of the stream, or an + * empty {@code OptionalLong} if the stream is empty. + * + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. + * + * <p>The behavior of this operation is explicitly nondeterministic; it is + * free to select any element in the stream. This is to allow for maximal + * performance in parallel operations; the cost is that multiple invocations + * on the same source may not return the same result. (If the first element + * in the encounter order is desired, use {@link #findFirst()} instead.) + * + * @return An {@code OptionalLong} describing some element of this stream, or an + * empty {@code OptionalLong} if the stream is empty + * @see #findFirst() + */ + OptionalLong findAny(); + + /** + * Returns a {@code DoubleStream} consisting of the elements of this stream, + * converted to {@code double}. + * @return A {@code DoubleStream} consisting of the elements of this stream, + * converted to {@code double} + */ + DoubleStream doubles(); + + /** + * Returns a {@code Stream} consisting of the elements of this stream, + * boxed to {@code Long}. + * @return A {@code Stream} consistent of the elements of this stream, + * boxed to {@code Long} + */ + Stream<Long> boxed(); + + @Override + LongStream sequential(); + + @Override + LongStream parallel(); @Override PrimitiveIterator.OfLong iterator(); @Override Spliterator.OfLong spliterator(); - - DoubleStream doubles(); - - Stream<Long> boxed(); - - LongStream map(LongUnaryOperator mapper); - - <U> Stream<U> mapToObj(LongFunction<U> mapper); - - IntStream mapToInt(LongToIntFunction mapper); - - DoubleStream mapToDouble(LongToDoubleFunction mapper); - - LongStream flatMap(LongFunction<? extends LongStream> mapper); - - LongStream flatMap(FlatMapper.OfLongToLong mapper); - - LongStream filter(LongPredicate predicate); - - LongStream peek(LongConsumer consumer); - - LongStream sorted(); - - LongStream distinct(); - - LongStream limit(long maxSize); - - LongStream substream(long startOffset); - - LongStream substream(long startOffset, long endOffset); - - LongStream sequential(); - - LongStream parallel(); - - long reduce(long identity, LongBinaryOperator op); - - OptionalLong reduce(LongBinaryOperator op); - - <R> R collect(Supplier<R> resultFactory, - ObjLongConsumer<R> accumulator, - BiConsumer<R, R> combiner); - - boolean anyMatch(LongPredicate predicate); - - boolean allMatch(LongPredicate predicate); - - boolean noneMatch(LongPredicate predicate); - - OptionalLong findFirst(); - - OptionalLong findAny(); - - void forEach(LongConsumer consumer); - - void forEachOrdered(LongConsumer consumer); - - long sum(); - - OptionalLong min(); - - OptionalLong max(); - - OptionalDouble average(); - - long count(); - - LongSummaryStatistics summaryStatistics(); - - long[] toArray(); }
--- a/src/share/classes/java/util/stream/Stream.java Mon Apr 01 10:42:34 2013 -0400 +++ b/src/share/classes/java/util/stream/Stream.java Mon Apr 01 15:25:22 2013 -0400 @@ -24,11 +24,11 @@ */ package java.util.stream; -import java.util.*; +import java.util.Comparator; +import java.util.Optional; import java.util.function.BiConsumer; import java.util.function.BiFunction; import java.util.function.BinaryOperator; -import java.util.function.BooleanSupplier; import java.util.function.Consumer; import java.util.function.Function; import java.util.function.IntFunction; @@ -47,120 +47,148 @@ // @@@ Specification to-do list @@@ /** - * A sequence of elements supporting sequential and parallel bulk operations. Streams support lazy transformative - * operations (transforming a stream to another stream) such as {@code filter} and {@code map}, and consuming - * operations, such as {@code forEach}, {@code findFirst}, and {@code iterator}. Once an operation has been - * performed on a stream, it is considered <em>consumed</em> and no longer usable for other operations. + * A sequence of elements supporting sequential and parallel bulk operations. + * Streams support lazy transformative operations (transforming a stream to + * another stream) such as {@code filter} and {@code map}, and consuming + * operations, such as {@code forEach}, {@code findFirst}, and {@code + * iterator}. Once an operation has been performed on a stream, it + * is considered <em>consumed</em> and no longer usable for other operations. * - * <p>For sequential stream pipelines, all operations are performed respecting in the - * <a href="package-summary.html#Ordering">encounter order</a> of the source, if the source has a defined encounter - * order. For parallel stream pipelines, unless otherwise specified, intermediate stream operations preserve the - * <a href="package-summary.html#Ordering">encounter order</a> of the source, and - * terminal operations respect the encounter order of the source, if the source has an encounter order. + * <p>For sequential stream pipelines, all operations are performed in the + * <a href="package-summary.html#Ordering">encounter order</a> of the pipeline + * source, if the pipeline source has a defined encounter order. + * + * <p>For parallel stream pipelines, unless otherwise specified, intermediate + * stream operations preserve the <a href="package-summary.html#Ordering"> + * encounter order</a> of their source, and terminal operations + * respect the encounter order of their source, if the source + * has an encounter order. * * @apiNote - * Streams are not data structures; they do not manage the storage for their elements, nor do they support access - * to individual elements. However, you can use the {@link #iterator()} or {@link #spliterator()} operations to + * Streams are not data structures; they do not manage the storage for their + * elements, nor do they support access to individual elements. However, + * you can use the {@link #iterator()} or {@link #spliterator()} operations to * perform a controlled traversal. * - * <p> Unless otherwise noted, passing a {@code null} argument to a method - * will cause a {@link NullPointerException} to be thrown. + * <p>Unless otherwise noted, passing a {@code null} argument to any stream + * method may result in a {@link NullPointerException}. * * @param <T> Type of elements. * @since 1.8 + * @see <a href="package-summary.html">java.util.stream</a> */ public interface Stream<T> extends BaseStream<T, Stream<T>> { /** - * Produce a stream consisting of the elements of this stream that match the given {@code Predicate}. + * Produces a stream consisting of the elements of this stream that match + * the given predicate. * - * <p>This is an <a href="package-summary.html#StreamOps">intermediate operation</a>. + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. * - * @param predicate A <a href="package-summary.html#NonInterference">non-interfering, stateless</a> predicate - * to apply to each element to determine if it should be included + * @param predicate A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> predicate to apply to + * each element to determine if it should be included * @return the new stream */ Stream<T> filter(Predicate<? super T> predicate); /** - * Produce a stream consisting of the results of applying the given function to the - * elements of this stream. + * Produces a stream consisting of the results of applying the given + * function to the elements of this stream. * - * <p>This is an <a href="package-summary.html#StreamOps">intermediate operation</a>. + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. * - * @param mapper a <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * function to be applied to each element + * @param mapper a <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element * @return the new stream */ <R> Stream<R> map(Function<? super T, ? extends R> mapper); /** - * Produce an {@code IntStream} consisting of the results of applying the given function - * to the elements of this stream. + * Produces an {@code IntStream} consisting of the results of applying + * the given function to the elements of this stream. * - * <p>This is an <a href="package-summary.html#StreamOps">intermediate operation</a>. + * <p>This is an <a href="package-summary.html#StreamOps"> + * intermediate operation</a>. * - * @param mapper A <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * function to be applied to each element + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element * @return the new stream */ IntStream mapToInt(ToIntFunction<? super T> mapper); /** - * Produce a {@code LongStream} consisting of the results of applying the given function - * to the elements of this stream. + * Produces a {@code LongStream} consisting of the results of applying the + * given function to the elements of this stream. * - * <p>This is an <a href="package-summary.html#StreamOps">intermediate operation</a>. + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. * - * @param mapper A <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * function to be applied to each element + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element * @return the new stream */ LongStream mapToLong(ToLongFunction<? super T> mapper); /** - * Produce a {@code DoubleStream} consisting of the results of applying the given function - * to the elements of this stream. + * Produces a {@code DoubleStream} consisting of the results of applying + * the given function to the elements of this stream. * - * <p>This is an <a href="package-summary.html#StreamOps">intermediate operation</a>. + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. * - * @param mapper A <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * function to be applied to each element + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element * @return the new stream */ DoubleStream mapToDouble(ToDoubleFunction<? super T> mapper); /** - * Produce a {@code Stream} consisting of the results of replacing each element of this stream with the contents - * of the {@code Stream} produced by applying the provided {@code Function} to each element. + * Produces a stream consisting of the results of replacing each + * element of this stream with the contents of the stream produced + * by applying the provided function to each element. * - * <p>This is an <a href="package-summary.html#StreamOps">intermediate operation</a>. + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. + * * @apiNote - * The "flatMap" operation has the effect of applying a one-to-many tranformation to the elements of the stream, - * and then flattening the resulting elements into a new stream. - * For example, if @{code orders} is a stream of purchase orders, and each purchase order contains a collection of - * line items, then the following produces a stream of line items: + * The "flatMap" operation has the effect of applying a one-to-many + * tranformation to the elements of the stream, and then flattening the + * resulting elements into a new stream. For example, if {@code orders} + * is a stream of purchase orders, and each purchase order contains a + * collection of line items, then the following produces a stream of line + * items: * <pre> * orderStream.flatMap(order -> order.getLineItems().stream())... * </pre> * - * <p>This implementation is likely to be less efficient than the other form of {@link #flatMap(FlatMapper)}, - * and is provided for convenience. - * @param mapper A <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * function to be applied to each element which produces a {@code Stream} of new values + * <p>This implementation is likely to be less efficient than the other + * form of {@link #flatMap(FlatMapper)}, and is provided for convenience. + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> function to be applied to + * each element which produces a stream of new values * @return the new stream */ <R> Stream<R> flatMap(Function<T, Stream<? extends R>> mapper); /** - * Produce a {@code Stream} consisting of the results of replacing each element of this stream with zero - * or more transformed values, according to the transformation encoded in the provided {@code FlatMapper}. + * Produces a stream consisting of the results of replacing each + * element of this stream with zero or more transformed values, according + * to the transformation encoded in the provided {@code FlatMapper}. * - * <p>This is an <a href="package-summary.html#StreamOps">intermediate operation</a>. + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. * @apiNote - * A {@code FlatMapper} is like a function that receives an element to transform, and a {@code Consumer} into which - * it deposits zero or more values corresponding to that element. For example, to map a stream of strings into a - * stream of the characters in those strings, you would do: + * A {@code FlatMapper} is like a function that receives an element to + * transform, and a {@code Consumer} into which it deposits zero or more + * values corresponding to that element. For example, to map a stream of + * strings into a stream of the characters in those strings, you would do: * <pre> * stringStream.flatMap((elt, destination) -> { * for (i=0; i < elt.length(); i++) @@ -169,127 +197,124 @@ * ... * </pre> * @implNote - * This form of {@code flatMap} is usually less convenient to use than the {@link #flatMap(Function)} form, - * but is often considerably more efficient because it eliminates the overhead of stream construction and - * traversal. - * @param mapper A <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * {@code FlatMapper} that transforms each element into zero or more resulting values + * This form of {@code flatMap} is usually less convenient to use than the + * {@link #flatMap(Function)} form, but is often considerably more efficient + * because it eliminates the overhead of stream construction and traversal. + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> {@code FlatMapper} that + * transforms each element into zero or more resulting values * @return the new stream */ <R> Stream<R> flatMap(FlatMapper<? super T, R> mapper); /** - * Produce an {@code IntStream} consisting of the results of replacing each element of this stream with zero - * or more transformed values, according to the transformation encoded in the provided {@code FlatMapper}. + * Produces an {@code IntStream} consisting of the results of replacing + * each element of this stream with zero or more transformed values, + * according to the transformation encoded in the provided + * {@code FlatMapper}. * - * <p>This is an <a href="package-summary.html#StreamOps">intermediate operation</a>. + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. * @implNote - * This form of {@code flatMap} is usually less convenient to use than the {@link #flatMap(Function)} form, - * but is often considerably more efficient because it eliminates the overhead of stream construction and - * traversal. + * This form of {@code flatMap} is usually less convenient to use than the + * {@link #flatMap(Function)} form, but is often considerably more efficient + * because it eliminates the overhead of stream construction and traversal. * @see #flatMap(FlatMapper) - * @param mapper A <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * {@code FlatMapper.ToInt} that transforms each element into zero or more resulting values + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> {@code FlatMapper.ToInt} + * that transforms each element into zero or more resulting + * values * @return the new stream */ IntStream flatMapToInt(FlatMapper.ToInt<? super T> mapper); /** - * Produce a {@code LongStream} consisting of the results of replacing each element of this stream with zero - * or more transformed values, according to the transformation encoded in the provided {@code FlatMapper}. + * Produces a {@code LongStream} consisting of the results of replacing each + * element of this stream with zero or more transformed values, according + * to the transformation encoded in the provided {@code FlatMapper}. * - * <p>This is an <a href="package-summary.html#StreamOps">intermediate operation</a>. + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. * @implNote - * This form of {@code flatMap} is usually less convenient to use than the {@link #flatMap(Function)} form, - * but is often considerably more efficient because it eliminates the overhead of stream construction and - * traversal. + * This form of {@code flatMap} is usually less convenient to use than the + * {@link #flatMap(Function)} form, but is often considerably more efficient + * because it eliminates the overhead of stream construction and traversal. * @see #flatMap(FlatMapper) - * @param mapper A <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * {@code FlatMapper.ToLong} that transforms each element into zero or more resulting values + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> {@code FlatMapper.ToLong} + * that transforms each element into zero or more resulting + * values * @return the new stream */ LongStream flatMapToLong(FlatMapper.ToLong<? super T> mapper); /** - * Produce a {@code DoubleStream} consisting of the results of replacing each element of this stream with zero - * or more transformed values, according to the transformation encoded in the provided {@code FlatMapper}. + * Produces a {@code DoubleStream} consisting of the results of replacing + * each element of this stream with zero or more transformed values, + * according to the transformation encoded in the provided {@code + * FlatMapper}. * - * <p>This is an <a href="package-summary.html#StreamOps">intermediate operation</a>. + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. * @implNote - * This form of {@code flatMap} is usually less convenient to use than the {@link #flatMap(Function)} form, - * but is often considerably more efficient because it eliminates the overhead of stream construction and - * traversal. + * This form of {@code flatMap} is usually less convenient to use than the + * {@link #flatMap(Function)} form, but is often considerably more efficient + * because it eliminates the overhead of stream construction and traversal. * @see #flatMap(FlatMapper) - * @param mapper A <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * {@code FlatMapper.ToDouble} that transforms each element into zero or more resulting values + * @param mapper A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> {@code FlatMapper.ToDouble} + * that transforms each element into zero or more resulting + * values * @return the new stream */ DoubleStream flatMapToDouble(FlatMapper.ToDouble<? super T> mapper); /** - * Produce a stream consisting of the distinct elements (according to {@link Object#equals(Object)}) of this stream. + * Produces a stream consisting of the distinct elements (according to + * {@link Object#equals(Object)}) of this stream. * - * <p>This is a <a href="package-summary.html#StreamOps">stateful intermediate operation</a>. + * <p>This is a <a href="package-summary.html#StreamOps">stateful + * intermediate operation</a>. * @return the new stream */ Stream<T> distinct(); /** - * Produce a stream consisting of the elements of this stream, sorted according to natural - * order. If the elements of this stream are not {@code Comparable}, a {@code java.lang.ClassCastException} + * Produces a stream consisting of the elements of this stream, sorted + * according to natural order. If the elements of this stream are not + * {@code Comparable}, a {@code java.lang.ClassCastException} * may be thrown when the stream pipeline is executed. * - * <p>This is a <a href="package-summary.html#StreamOps">stateful intermediate operation</a>. + * <p>This is a <a href="package-summary.html#StreamOps">stateful + * intermediate operation</a>. * @return the new stream */ Stream<T> sorted(); /** - * Produce a stream consisting of the elements of this stream, sorted according to the provide - * {@code Comparator}. + * Produces a stream consisting of the elements of this stream, sorted + * according to the provide {@code Comparator}. * - * <p>This is a <a href="package-summary.html#StreamOps">stateful intermediate operation</a>. - * @param comparator A <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * {@code Comparator} to be used to compare stream elements + * <p>This is a <a href="package-summary.html#StreamOps">stateful + * intermediate operation</a>. + * @param comparator A <a href="package-summary.html#NonInterference"> + * non-interfering, stateless</a> {@code Comparator} to + * be used to compare stream elements * @return the new stream */ Stream<T> sorted(Comparator<? super T> comparator); /** - * Perform an operation for each element of this stream. + * Produces a stream consisting of the elements of this stream, additionally + * performing the provided action on each element as elements are consumed + * from the resulting stream. * - * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. + * <p>This is an <a href="package-summary.html#StreamOps">intermediate + * operation</a>. * - * <p>For parallel stream pipelines, this operation does <em>not</em> guarantee to respect the encounter order - * of the stream, as doing so would sacrifice the benefit of parallelism. For any given element, the action - * may be performed at whatever time and in whatever thread the library chooses. If the operation accesses - * shared state, it is responsible for providing the required synchronization. - * - * @param consumer A <a href="package-summary.html#NonInterference">non-interfering</a> - * action to perform on the elements - */ - void forEach(Consumer<? super T> consumer); - - /** - * Perform an operation for each element of this stream, guaranteeing that each element - * is processed in encounter order for streams that have a defined encounter order. - * - * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. - * - * @param consumer A <a href="package-summary.html#NonInterference">non-interfering</a> - * action to perform on the elements - * @see #forEach(Consumer) - */ - void forEachOrdered(Consumer<? super T> consumer); - - /** - * Produce a stream consisting of the elements of this stream, additionally performing the provided - * action on each element as elements are consumed from the resulting stream. - * - * <p>This is an <a href="package-summary.html#StreamOps">intermediate operation</a>. - * - * <p>For parallel stream pipelines, the {@code Consumer} may be called at whatever time and in whatever thread - * the element is made available by the upstream operation. If the {@code Consumer} modifies shared state, + * <p>For parallel stream pipelines, the action may be called at + * whatever time and in whatever thread the element is made available by the + * upstream operation. If the action modifies shared state, * it is responsible for providing the required synchronization. * * @apiNote This method exists mainly to support debugging, where you want @@ -303,17 +328,19 @@ * .collect(Collectors.intoList()); * </pre> * - * @param consumer A <a href="package-summary.html#NonInterference">non-interfering</a> - * action to perform on the elements as they are consumed from the stream + * @param consumer A <a href="package-summary.html#NonInterference"> + * non-interfering</a> action to perform on the elements as + * they are consumed from the stream * @return the new stream */ Stream<T> peek(Consumer<? super T> consumer); /** - * Produce a {@code Stream} consisting of the elements of this stream, truncated to be no longer than - * {@code maxSize} in length. + * Produces a stream consisting of the elements of this stream, + * truncated to be no longer than {@code maxSize} in length. * - * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting stateful intermediate operation</a>. + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * stateful intermediate operation</a>. * * @param maxSize the number of elements the stream should be limited to * @return the new stream @@ -321,10 +348,11 @@ Stream<T> limit(long maxSize); /** - * Produce a {@code Stream} consistent of the elements of this stream, discarding the first {@code startingOffset} - * elements. + * Produces a stream consisting of the elements of this stream, + * discarding the first {@code startingOffset} elements. * - * <p>This is a <a href="package-summary.html#StreamOps">stateful intermediate operation</a>. + * <p>This is a <a href="package-summary.html#StreamOps">stateful + * intermediate operation</a>. * * @param startingOffset the number of leading elements to be skipped * @return the new stream @@ -332,10 +360,12 @@ Stream<T> substream(long startingOffset); /** - * Produce a {@code Stream} consisting of the elements of this stream, discarding the first {@code startingOffset} - * elements, and truncating the remainder to be no longer than {@code maxSize} in length. + * Produces a stream consisting of the elements of this stream, + * discarding the first {@code startingOffset} elements, and truncating the + * remainder to be no longer than {@code maxSize} in length. * - * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting stateful intermediate operation</a>. + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * stateful intermediate operation</a>. * * @param startingOffset the starting position of the substream, inclusive * @param endingOffset the ending position of the substream, exclusive @@ -344,33 +374,70 @@ Stream<T> substream(long startingOffset, long endingOffset); /** - * Produce an array containing the elements of this stream. + * Performs an operation for each element of this stream. * - * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * <p>For parallel stream pipelines, this operation does <em>not</em> + * guarantee to respect the encounter order of the stream, as doing so + * would sacrifice the benefit of parallelism. For any given element, the + * action may be performed at whatever time and in whatever thread the + * library chooses. If the operation accesses shared state, it is + * responsible for providing the required synchronization. + * + * @param consumer A <a href="package-summary.html#NonInterference"> + * non-interfering</a> action to perform on the elements + */ + void forEach(Consumer<? super T> consumer); + + /** + * Performs an operation for each element of this stream, guaranteeing that + * each element is processed in encounter order for streams that have a + * defined encounter order. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. + * + * @param consumer A <a href="package-summary.html#NonInterference"> + * non-interfering</a> action to perform on the elements + * @see #forEach(Consumer) + */ + void forEachOrdered(Consumer<? super T> consumer); + + /** + * Produces an array containing the elements of this stream. + * + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. * * @return an array containing the elements of this stream */ Object[] toArray(); /** - * Produce an array containing the elements of this stream, using the provided {@code generator} function - * to allocate the returned array. + * Produces an array containing the elements of this stream, using the + * provided {@code generator} function to allocate the returned array. * - * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. * - * @param generator a function which produces a new array of the desired type and the provided length + * @param generator a function which produces a new array of the desired + * type and the provided length * @param <A> the element type of the resulting array * @return an array containing the elements in this stream - * @throws ArrayStoreException if the runtime type of the array returned from the array generator - * is not a supertype of the runtime type of every element in this stream + * @throws ArrayStoreException if the runtime type of the array returned + * from the array generator is not a supertype of the runtime type of every + * element in this stream */ <A> A[] toArray(IntFunction<A[]> generator); /** - * Perform a <a href="package-summary.html#Reduction">reduction</a> on the elements of this stream, - * using the provided identity value and - * an <a href="package-summary.html#Associativity">associative</a> accumulation function, - * and return the reduced value. This is equivalent to: + * Performs a <a href="package-summary.html#Reduction">reduction</a> on the + * elements of this stream, using the provided identity value and + * an <a href="package-summary.html#Associativity">associative</a> + * accumulation function, and return the reduced value. This is equivalent + * to: * <pre> * T result = identity; * for (T element : this stream) @@ -380,14 +447,17 @@ * * but is not constrained to execute sequentially. * - * <p>The {@code identity} value must be an identity for the accumulator function. - * This means that for all {@code t}, <code>accumulator.apply(identity, t)</code> is equal to {@code t}. - * The {@code accumulator} function must be an <a href="package-summary.html#Associativity">associative</a> function. + * <p>The {@code identity} value must be an identity for the accumulator + * function. This means that for all {@code t}, + * {@code accumulator.apply(identity, t)} is equal to {@code t}. + * The {@code accumulator} function must be an + * <a href="package-summary.html#Associativity">associative</a> function. * - * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. * - * @apiNote Sum, min, max, average, and string concatenation are all special cases of reduction. - * Summing a stream of numbers can be expressed as: + * @apiNote Sum, min, max, average, and string concatenation are all special + * cases of reduction. Summing a stream of numbers can be expressed as: * * <pre> * Integer sum = integers.reduce(0, (a, b) -> a+b); @@ -399,23 +469,25 @@ * Integer sum = integers.reduce(0, Integer::sum); * </pre> * - * <p>While this may seem a more roundabout way to perform an aggregation compared to simply mutating a running - * total in a loop, reduction operations parallelize more gracefully, without needing additional synchronization - * and with greatly reduced risk of data races. + * <p>While this may seem a more roundabout way to perform an aggregation + * compared to simply mutating a running total in a loop, reduction + * operations parallelize more gracefully, without needing additional + * synchronization and with greatly reduced risk of data races. * * @param identity The identity value for the accumulating function * @param accumulator An <a href="package-summary.html#Associativity">associative</a> - * <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * function for combining two values + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for combining two values * @return The result of the reduction */ T reduce(T identity, BinaryOperator<T> accumulator); /** - * Perform a <a href="package-summary.html#Reduction">reduction</a> on the elements of this stream, using an - * <a href="package-summary.html#Associativity">associative</a> accumulation function, - * and return an {@code Optional} describing the reduced value, if any. - * This is equivalent to: + * Performs a <a href="package-summary.html#Reduction">reduction</a> on the + * elements of this stream, using an + * <a href="package-summary.html#Associativity">associative</a> accumulation + * function, and return an {@code Optional} describing the reduced value, + * if any. This is equivalent to: * <pre> * boolean foundAny = false; * T result = null; @@ -431,22 +503,24 @@ * * but is not constrained to execute sequentially. * - * <p>The {@code accumulator} function must be an <a href="package-summary.html#Associativity">associative</a> - * function. + * <p>The {@code accumulator} function must be an + * <a href="package-summary.html#Associativity">associative</a> function. * - * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. * * @param accumulator An <a href="package-summary.html#Associativity">associative</a> - * <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * function for combining two values + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for combining two values * @return The result of the reduction * @see #reduce(Object, BinaryOperator) */ Optional<T> reduce(BinaryOperator<T> accumulator); /** - * Perform a <a href="package-summary.html#Reduction">reduction</a> on the elements of this stream, - * using the provided identity, accumulation function, and a combining functions. This is equivalent to: + * Performs a <a href="package-summary.html#Reduction">reduction</a> on the + * elements of this stream, using the provided identity, accumulation + * function, and a combining functions. This is equivalent to: * <pre> * U result = identity; * for (T element : this stream) @@ -456,28 +530,33 @@ * * but is not constrained to execute sequentially. * - * <p>The {@code identity} value must be an identity for the combiner function. This means that for all {@code u}, - * <code>combiner(identity, u)</code> is equal to {@code u}. Additionally, the {@code combiner} function - * must be compatible with the {@code accumulator} function; for all {@code u} and {@code t}, the following must hold: + * <p>The {@code identity} value must be an identity for the combiner + * function. This means that for all {@code u}, {@code combiner(identity, u)} + * is equal to {@code u}. Additionally, the {@code combiner} function + * must be compatible with the {@code accumulator} function; for all + * {@code u} and {@code t}, the following must hold: * <pre> * combiner.apply(u, accumulator.apply(identity, t)) == accumulator.apply(u, t) * </pre> * * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. * - * @apiNote Many reductions using this form can be represented more simply by an explicit combination of {@code map} - * and {@code reduce} operations. The {@code accumulator} function acts as a fused mapper and accumulator, which can - * sometimes be more efficient than separate mapping and reduction, such as in the case where knowing the - * previously reduced value allows you to avoid some computation. + * @apiNote Many reductions using this form can be represented more simply + * by an explicit combination of {@code map} and {@code reduce} operations. + * The {@code accumulator} function acts as a fused mapper and accumulator, + * which can sometimes be more efficient than separate mapping and reduction, + * such as in the case where knowing the previously reduced value allows you + * to avoid some computation. * * @param identity The identity value for the combiner function * @param accumulator An <a href="package-summary.html#Associativity">associative</a> - * <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * function for incorporating an additional element into a result + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for incorporating an additional + * element into a result * @param combiner An <a href="package-summary.html#Associativity">associative</a> - * <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * function for combining two values, which must be compatible - * with the accumulator function + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for combining two values, which + * must be compatible with the accumulator function * @param <U> The type of the result * @return The result of the reduction * @see #reduce(BinaryOperator) @@ -488,10 +567,12 @@ BinaryOperator<U> combiner); /** - * Perform a <a href="package-summary.html#MutableReduction">mutable reduction</a> operation on the elements of - * this stream. A mutable reduction is one in which the reduced value is a mutable value holder, such as - * an {@code ArrayList}, and elements are incorporated by updating the state of the result, rather than - * by replacing the result. This produces a result equivalent to: + * Performs a <a href="package-summary.html#MutableReduction">mutable + * reduction</a> operation on the elements of this stream. A mutable + * reduction is one in which the reduced value is a mutable value holder, + * such as an {@code ArrayList}, and elements are incorporated by updating + * the state of the result, rather than by replacing the result. This + * produces a result equivalent to: * <pre> * R result = resultFactory.get(); * for (T element : this stream) @@ -499,33 +580,39 @@ * return result; * </pre> * - * Like {@link #reduce(Object, BinaryOperator)}, {@code collect} operations can be parallelized without - * requiring additional sychronization. + * Like {@link #reduce(Object, BinaryOperator)}, {@code collect} operations + * can be parallelized without requiring additional sychronization. * - * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. * - * @apiNote There are many existing classes in the JDK whose signatures are a good match for use as - * arguments to {@code collect()}. For example, the following will accumulate strings into an ArrayList: + * @apiNote There are many existing classes in the JDK whose signatures are + * a good match for use as arguments to {@code collect()}. For example, + * the following will accumulate strings into an ArrayList: * <pre> * List<String> asList = stringStream.collect(ArrayList::new, ArrayList::add, ArrayList::addAll); * </pre> * - * The following will take a stream of strings and concatenates them into a single string: + * The following will take a stream of strings and concatenates them into a + * single string: * <pre> * String concat = stringStream.collect(StringBuilder::new, StringBuilder::append, * StringBuilder::append) * .toString(); * </pre> * - * @param resultFactory Function that creates a new result container. For a parallel execution, this function - * may be called multiple times and must return a fresh value each time. + * @param resultFactory Function that creates a new result container. + * For a parallel execution, this function may be + * called multiple times and must return a fresh value + * each time. * @param accumulator An <a href="package-summary.html#Associativity">associative</a> - * <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * function for incorporating an additional element into a result + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for incorporating an additional + * element into a result * @param combiner An <a href="package-summary.html#Associativity">associative</a> - * <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * function for combining two values, which must be compatible - * with the accumulator function + * <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> function for combining two values, which + * must be compatible with the accumulator function * @param <R> Type of the result * @return The result of the reduction */ @@ -533,18 +620,22 @@ BiConsumer<R, ? super T> accumulator, BiConsumer<R, R> combiner); - /** Perform a <a href="package-summary.html#MutableReduction">mutable reduction</a> operation on the elements - * of this stream using a {@code Collector} object to describe the reduction. A {@code Collector} - * encapsulates the functions used as arguments to {@link #collect(Supplier, BiConsumer, BiConsumer)}, - * allowing for reuse of collection strategies, and composition of collect operations such as multiple-level - * grouping or partitioning. + /** Performs a <a href="package-summary.html#MutableReduction">mutable + * reduction</a> operation on the elements of this stream using a + * {@code Collector} object to describe the reduction. A {@code Collector} + * encapsulates the functions used as arguments to + * {@link #collect(Supplier, BiConsumer, BiConsumer)}, allowing for reuse of + * collection strategies, and composition of collect operations such as + * multiple-level grouping or partitioning. * - * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. * - * When executed in parallel, multiple intermediate results may be instantiated, populated, and merged, - * so as to maintain isolation of mutable data structures. Therefore, even when executed in parallel - * with non-thread-safe data structures (such as {@code ArrayList}), no additional synchronization is - * needed for a parallel reduction. + * <p>When executed in parallel, multiple intermediate results may be + * instantiated, populated, and merged, so as to maintain isolation of + * mutable data structures. Therefore, even when executed in parallel + * with non-thread-safe data structures (such as {@code ArrayList}), no + * additional synchronization is needed for a parallel reduction. * * @apiNote * The following will accumulate strings into an ArrayList: @@ -558,8 +649,8 @@ * = personStream.collect(Collectors.groupBy(Person::getCity)); * </pre> * - * The following will classify {@code Person} objects by state and city, cascading two {@code Collector}s - * together: + * The following will classify {@code Person} objects by state and city, + * cascading two {@code Collector}s together: * <pre> * Map<String, Map<String, Collection<Person>>> peopleByStateAndCity * = personStream.collect(Collectors.groupBy(Person::getState, @@ -574,12 +665,14 @@ */ <R> R collect(Collector<? super T, R> collector); - /** Perform a <a href="package-summary.html#MutableReduction">mutable reduction</a> operation on the elements - * of this stream using a {@code Collector} object to describe the reduction, without regard to encounter order. - * If the provided {@code Collector} is concurrent, this implementation may invoke the function - * returned by {@link Collector#accumulator()} concurrently on the same result object. In some cases, - * implementing a reduction by concurrently modifying a shared data structure may be more efficient than - * partitioning and merging. + /** Performs a <a href="package-summary.html#MutableReduction">mutable + * reduction</a> operation on the elements of this stream using a + * {@code Collector} object to describe the reduction, without regard to + * encounter order. If the provided {@code Collector} is concurrent, this + * implementation may invoke the function returned by + * {@link Collector#accumulator()} concurrently on the same result object. + * In some cases, implementing a reduction by concurrently modifying a + * shared data structure may be more efficient than partitioning and merging. * * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. * @@ -592,31 +685,39 @@ <R> R collectUnordered(Collector<? super T, R> collector); /** - * Return the maximal element of this stream according to the provided {@code Comparator}. + * Returns the maximal element of this stream according to the provided + * {@code Comparator}. This is a special case of a + * <a href="package-summary.html#MutableReduction">reduction</a>. * - * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. + * <p>This is a <a href="package-summary.html#StreamOps">terminal + * operation</a>. * - * @param comparator A <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * {@code Comparator} to use to compare elements of this stream - * @return An {@code Optional} describing the maximal element of this stream, or an empty {@code Optional} - * if the stream is empty + * @param comparator A <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> {@code Comparator} to use to compare + * elements of this stream + * @return An {@code Optional} describing the maximal element of this stream, + * or an empty {@code Optional} if the stream is empty */ Optional<T> max(Comparator<? super T> comparator); /** - * Return the minimal element of this stream according to the provided {@code Comparator}. + * Returns the minimal element of this stream according to the provided + * {@code Comparator}. This is a special case of a + * <a href="package-summary.html#MutableReduction">reduction</a>. * * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. * - * @param comparator A <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * {@code Comparator} to use to compare elements of this stream - * @return An {@code Optional} describing the minimal element of this stream, or an empty {@code Optional} - * if the stream is empty + * @param comparator A <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> {@code Comparator} to use to compare + * elements of this stream + * @return An {@code Optional} describing the minimal element of this stream, + * or an empty {@code Optional} if the stream is empty */ Optional<T> min(Comparator<? super T> comparator); /** - * Return the count of elements in this stream. + * Returns the count of elements in this stream. This is a special case of a + * <a href="package-summary.html#MutableReduction">reduction</a>. * * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. * @@ -625,65 +726,76 @@ long count(); /** - * Return whether any elements of this stream match the provided {@code Predicate}. May not evaluate the - * predicate on all elements if not necessary for determining the result. + * Returns whether any elements of this stream match the provided + * predicate. May not evaluate the predicate on all elements if not + * necessary for determining the result. * - * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting terminal operation</a>. + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. * - * @param predicate A <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * predicate to apply to elements of this stream + * @param predicate A <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> predicate to apply to elements of this + * stream * @return Whether any elements of the stream match the provided predicate */ boolean anyMatch(Predicate<? super T> predicate); /** - * Return whether all elements of this stream match the provided {@code Predicate}. May not evaluate the - * predicate on all elements if not necessary for determining the result. + * Returns whether all elements of this stream match the provided + * predicate. May not evaluate the predicate on all elements if + * not necessary for determining the result. * - * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting terminal operation</a>. + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. * - * @param predicate A <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * predicate to apply to elements of this stream + * @param predicate A <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> predicate to apply to elements of this stream * @return Whether all elements of the stream match the provided predicate */ boolean allMatch(Predicate<? super T> predicate); /** - * Return whether no elements of this stream match the provided {@code Predicate}. May not evaluate the - * predicate on all elements if not necessary for determining the result. + * Returns whether no elements of this stream match the provided + * predicate. May not evaluate the predicate on all elements if + * not necessary for determining the result. * - * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting terminal operation</a>. + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. * - * @param predicate A <a href="package-summary.html#NonInterference">non-interfering, stateless</a> - * predicate to apply to elements of this stream + * @param predicate A <a href="package-summary.html#NonInterference">non-interfering, + * stateless</a> predicate to apply to elements of this stream * @return Whether no elements of the stream match the provided predicate */ boolean noneMatch(Predicate<? super T> predicate); /** - * Return an {@link Optional} describing the first element of this stream (in the encounter order), or an - * empty {@code Optional} if the stream is empty. + * Returns an {@link Optional} describing the first element of this stream + * (in the encounter order), or an empty {@code Optional} if the stream is + * empty. * - * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting terminal operation</a>. + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. * - * @return An {@code Optional} describing the first element of this stream, or an empty - * {@code Optional} if the stream is empty + * @return An {@code Optional} describing the first element of this stream, + * or an empty {@code Optional} if the stream is empty */ Optional<T> findFirst(); /** - * Return an {@link Optional} describing some element of the stream, or an + * Returns an {@link Optional} describing some element of the stream, or an * empty {@code Optional} if the stream is empty. * - * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting terminal operation</a>. + * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting + * terminal operation</a>. * - * <p>The behavior of this operation is explicitly nondeterministic; it is free to select any element in the - * stream. This is to allow for maximal performance in parallel operations; the cost is that multiple invocations - * on the same source may not return the same result. (If the first element in the encounter order is desired, - * use {@link #findFirst()} instead.) + * <p>The behavior of this operation is explicitly nondeterministic; it is + * free to select any element in the stream. This is to allow for maximal + * performance in parallel operations; the cost is that multiple invocations + * on the same source may not return the same result. (If the first element + * in the encounter order is desired, use {@link #findFirst()} instead.) * - * @return An {@code Optional} describing some element of this stream, or an empty - * {@code Optional} if the stream is empty + * @return An {@code Optional} describing some element of this stream, or an + * empty {@code Optional} if the stream is empty * @see #findFirst() */ Optional<T> findAny();
--- a/src/share/classes/java/util/stream/package-info.java Mon Apr 01 10:42:34 2013 -0400 +++ b/src/share/classes/java/util/stream/package-info.java Mon Apr 01 15:25:22 2013 -0400 @@ -205,15 +205,17 @@ * depends on the source, the intermediate operations, and the terminal operation. Certain stream sources * (such as {@code List} or arrays) are intrinsically ordered, whereas others (such as {@code HashSet}) are * not. Some intermediate operations may impose an encounter order on an otherwise unordered stream, such - * as {@link java.util.stream.Stream#sorted()}. Finally, some terminal operations may ignore encounter order, - * such as {@link java.util.stream.Stream#forEach}, and others may have optimized implementations for the case - * where there is no defined encounter order. + * as {@link java.util.stream.Stream#sorted()}. Some intermediate operations may remove the constraint of + * ordering, rendering unorerded an otherwise ordered stream. Finally, some terminal operations may ignore + * encounter order, such as {@link java.util.stream.Stream#forEach}, and others may have optimized + * implementations for the case where there is no defined encounter order. * * <p>If a Stream is ordered, most operations are constrained to operate on the elements in their * encounter order; if the source of a stream is a {@code List} containing {@code [1, 2, 3]}, then the * result of executing {@code map(x -> x*2)} must be {@code [2, 4, 6]}. However, if the source has no * defined encounter order, than any permutation of the values {@code [2, 4, 6]} would be a valid result. - * Many operations can still be efficiently parallelized even under such constraints. + * Many operations can still be efficiently parallelized even under ordering constraints, but some (such + * as duplicate removal) may be much more efficient without ordering constraints. * * @@@ Interaction between ordering and concurrency *