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 &lt; elt; i++)
-     *                                  if (elt % i == 0 &amp;&amp; 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 &lt; 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&lt;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&lt;String, Map&lt;String, Collection&lt;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
  *