--- a/jdk/src/share/classes/java/util/stream/LongStream.java Thu Sep 12 13:20:26 2013 -0400
+++ b/jdk/src/share/classes/java/util/stream/LongStream.java Fri Sep 06 22:20:01 2013 -0700
@@ -24,7 +24,11 @@
*/
package java.util.stream;
+import java.nio.charset.Charset;
+import java.nio.file.Files;
+import java.nio.file.Path;
import java.util.Arrays;
+import java.util.Collection;
import java.util.LongSummaryStatistics;
import java.util.Objects;
import java.util.OptionalDouble;
@@ -32,6 +36,7 @@
import java.util.PrimitiveIterator;
import java.util.Spliterator;
import java.util.Spliterators;
+import java.util.concurrent.ConcurrentHashMap;
import java.util.function.BiConsumer;
import java.util.function.Function;
import java.util.function.LongBinaryOperator;
@@ -46,40 +51,87 @@
import java.util.function.Supplier;
/**
- * A sequence of primitive long elements supporting sequential and parallel
- * bulk operations. Streams support lazy intermediate operations (transforming
- * a stream to another stream) such as {@code filter} and {@code map}, and terminal
- * operations (consuming the contents of a stream to produce a result or
- * side-effect), 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 aggregate
+ * operations. The following example illustrates an aggregate operation using
+ * {@link Stream} and {@link LongStream}:
+ *
+ * <pre>{@code
+ * long sum = widgets.stream()
+ * .filter(w -> w.getColor() == RED)
+ * .mapToLong(w -> w.getWeight())
+ * .sum();
+ * }</pre>
+ *
+ * In this example, {@code widgets} is a {@code Collection<Widget>}. We create
+ * a stream of {@code Widget} objects via {@link Collection#stream Collection.stream()},
+ * filter it to produce a stream containing only the red widgets, and then
+ * transform it into a stream of {@code long} values representing the weight of
+ * each red widget. Then this stream is summed to produce a total weight.
*
- * <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>To perform a computation, stream
+ * <a href="package-summary.html#StreamOps">operations</a> are composed into a
+ * <em>stream pipeline</em>. A stream pipeline consists of a source (which
+ * might be an array, a collection, a generator function, an IO channel,
+ * etc), zero or more <em>intermediate operations</em> (which transform a
+ * stream into another stream, such as {@link LongStream#filter(LongPredicate)}), and a
+ * <em>terminal operation</em> (which produces a result or side-effect, such
+ * as {@link LongStream#sum()} or {@link LongStream#forEach(LongConsumer)}).
+ * Streams are lazy; computation on the source data is only performed when the
+ * terminal operation is initiated, and source elements are consumed only
+ * as needed.
+ *
+ * <p>Collections and streams, while bearing some superficial similarities,
+ * have different goals. Collections are primarily concerned with the efficient
+ * management of, and access to, their elements. By contrast, streams do not
+ * provide a means to directly access or manipulate their elements, and are
+ * instead concerned with declaratively describing their source and the
+ * computational operations which will be performed in aggregate on that source.
+ * However, if the provided stream operations do not offer the desired
+ * functionality, the {@link #iterator()} and {@link #spliterator()} operations
+ * can be used to perform a controlled traversal.
*
- * <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. Provided that and parameters to stream operations
- * satisfy the <a href="package-summary.html#NonInterference">non-interference
- * requirements</a>, and excepting differences arising from the absence of
- * a defined encounter order, the result of a stream pipeline should be the
- * stable across multiple executions of the same operations on the same source.
- * However, the timing and thread in which side-effects occur (for those
- * operations which are allowed to produce side-effects, such as
- * {@link #forEach(LongConsumer)}), are explicitly nondeterministic for parallel
- * execution of stream pipelines.
+ * <p>A stream pipeline, like the "widgets" example above, can be viewed as
+ * a <em>query</em> on the stream source. Unless the source was explicitly
+ * designed for concurrent modification (such as a {@link ConcurrentHashMap}),
+ * unpredictable or erroneous behavior may result from modifying the stream
+ * source while it is being queried.
+ *
+ * <p>Most stream operations accept parameters that describe user-specified
+ * behavior, such as the lambda expression {@code w -> w.getWeight()} passed to
+ * {@code mapToLong} in the example above. Such parameters are always instances
+ * of a <a href="../function/package-summary.html">functional interface</a> such
+ * as {@link java.util.function.Function}, and are often lambda expressions or
+ * method references. These parameters can never be null, should not modify the
+ * stream source, and should be
+ * <a href="package-summary.html#NonInterference">effectively stateless</a>
+ * (their result should not depend on any state that might change during
+ * execution of the stream pipeline.)
*
- * <p>Unless otherwise noted, passing a {@code null} argument to any stream
- * method may result in a {@link NullPointerException}.
+ * <p>A stream should be operated on (invoking an intermediate or terminal stream
+ * operation) only once. This rules out, for example, "forked" streams, where
+ * the same source feeds two or more pipelines, or multiple traversals of the
+ * same stream. A stream implementation may throw {@link IllegalStateException}
+ * if it detects that the stream is being reused. However, since some stream
+ * operations may return their receiver rather than a new stream object, it may
+ * not be possible to detect reuse in all cases.
*
- * @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>Streams have a {@link #close()} method and implement {@link AutoCloseable},
+ * but nearly all stream instances do not actually need to be closed after use.
+ * Generally, only streams whose source is an IO channel (such as those returned
+ * by {@link Files#lines(Path, Charset)}) will require closing. Most streams
+ * are backed by collections, arrays, or generating functions, which require no
+ * special resource management. (If a stream does require closing, it can be
+ * declared as a resource in a {@code try}-with-resources statement.)
+ *
+ * <p>Stream pipelines may execute either sequentially or in
+ * <a href="package-summary.html#Parallelism">parallel</a>. This
+ * execution mode is a property of the stream. Streams are created
+ * with an initial choice of sequential or parallel execution. (For example,
+ * {@link Collection#stream() Collection.stream()} creates a sequential stream,
+ * and {@link Collection#parallelStream() Collection.parallelStream()} creates
+ * a parallel one.) This choice of execution mode may be modified by the
+ * {@link #sequential()} or {@link #parallel()} methods, and may be queried with
+ * the {@link #isParallel()} method.
*
* @since 1.8
* @see <a href="package-summary.html">java.util.stream</a>
@@ -160,22 +212,13 @@
/**
* Returns a stream consisting of the results of replacing each element of
* this stream with the contents of the stream produced by applying the
- * provided mapping function to each element.
+ * provided mapping function to each element. (If the result of the mapping
+ * function is {@code null}, this is treated as if the result was an empty
+ * stream.)
*
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @apiNote
- * The {@code 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>{@code
- * orderStream.flatMap(order -> order.getLineItems().stream())...
- * }</pre>
- *
* @param mapper a <a href="package-summary.html#NonInterference">
* non-interfering, stateless</a> function to apply to
* each element which produces an {@code LongStream} of new
@@ -224,18 +267,18 @@
* <pre>{@code
* list.stream()
* .filter(filteringFunction)
- * .peek(e -> {System.out.println("Filtered value: " + e); });
+ * .peek(e -> System.out.println("Filtered value: " + e));
* .map(mappingFunction)
- * .peek(e -> {System.out.println("Mapped value: " + e); });
+ * .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
+ * @param action 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);
+ LongStream peek(LongConsumer action);
/**
* Returns a stream consisting of the elements of this stream, truncated
@@ -252,8 +295,8 @@
/**
* Returns a stream consisting of the remaining elements of this stream
- * after indexing {@code startInclusive} elements into the stream. If the
- * {@code startInclusive} index lies past the end of this stream then an
+ * after discarding the first {@code startInclusive} elements of the stream.
+ * If this stream contains fewer than {@code startInclusive} elements then an
* empty stream will be returned.
*
* <p>This is a <a href="package-summary.html#StreamOps">stateful
@@ -267,10 +310,10 @@
/**
* Returns a stream consisting of the remaining elements of this stream
- * after indexing {@code startInclusive} elements into the stream and
- * truncated to contain no more than {@code endExclusive - startInclusive}
- * elements. If the {@code startInclusive} index lies past the end
- * of this stream then an empty stream will be returned.
+ * after discarding the first {@code startInclusive} elements and truncating
+ * the result to be no longer than {@code endExclusive - startInclusive}
+ * elements in length. If this stream contains fewer than
+ * {@code startInclusive} elements then an empty stream will be returned.
*
* <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
* stateful intermediate operation</a>.
@@ -419,12 +462,12 @@
/**
* 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,
+ * reduction is one in which the reduced value is a mutable result container,
* such as an {@code ArrayList}, and elements are incorporated by updating
- * the state of the result, rather than by replacing the result. This
+ * the state of the result rather than by replacing the result. This
* produces a result equivalent to:
* <pre>{@code
- * R result = resultFactory.get();
+ * R result = supplier.get();
* for (long element : this stream)
* accumulator.accept(result, element);
* return result;
@@ -437,10 +480,9 @@
* operation</a>.
*
* @param <R> type of the result
- * @param resultFactory a 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 supplier a 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
@@ -452,18 +494,21 @@
* @return the result of the reduction
* @see Stream#collect(Supplier, BiConsumer, BiConsumer)
*/
- <R> R collect(Supplier<R> resultFactory,
+ <R> R collect(Supplier<R> supplier,
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>
+ * of a <a href="package-summary.html#Reduction">reduction</a>
* and is equivalent to:
* <pre>{@code
* return reduce(0, Long::sum);
* }</pre>
*
+ * <p>This is a <a href="package-summary.html#StreamOps">terminal
+ * operation</a>.
+ *
* @return the sum of elements in this stream
*/
long sum();
@@ -471,7 +516,7 @@
/**
* Returns an {@code OptionalLong} describing the minimum 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>
+ * case of a <a href="package-summary.html#Reduction">reduction</a>
* and is equivalent to:
* <pre>{@code
* return reduce(Long::min);
@@ -479,7 +524,6 @@
*
* <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
*
-
* @return an {@code OptionalLong} containing the minimum element of this
* stream, or an empty {@code OptionalLong} if the stream is empty
*/
@@ -488,7 +532,7 @@
/**
* Returns an {@code OptionalLong} describing the maximum 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>
+ * case of a <a href="package-summary.html#Reduction">reduction</a>
* and is equivalent to:
* <pre>{@code
* return reduce(Long::max);
@@ -504,7 +548,7 @@
/**
* 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
+ * a <a href="package-summary.html#Reduction">reduction</a> and is
* equivalent to:
* <pre>{@code
* return map(e -> 1L).sum();
@@ -520,7 +564,10 @@
* Returns an {@code OptionalDouble} describing the arithmetic mean 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>.
+ * <a href="package-summary.html#Reduction">reduction</a>.
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">terminal
+ * operation</a>.
*
* @return an {@code OptionalDouble} containing the average element of this
* stream, or an empty optional if the stream is empty
@@ -530,7 +577,10 @@
/**
* 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>.
+ * <a href="package-summary.html#Reduction">reduction</a>.
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">terminal
+ * operation</a>.
*
* @return a {@code LongSummaryStatistics} describing various summary data
* about the elements of this stream
@@ -587,9 +637,8 @@
/**
* 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. If the stream has no encounter order, then any element
- * may be returned.
+ * stream, or an empty {@code OptionalLong} if the stream is empty. If the
+ * stream has no encounter order, then any element may be returned.
*
* <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
* terminal operation</a>.
@@ -609,8 +658,8 @@
* <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.)
+ * on the same source may not return the same result. (If a stable result
+ * 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
@@ -622,6 +671,9 @@
* Returns a {@code DoubleStream} consisting of the elements of this stream,
* converted to {@code double}.
*
+ * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+ * operation</a>.
+ *
* @return a {@code DoubleStream} consisting of the elements of this stream,
* converted to {@code double}
*/
@@ -631,6 +683,9 @@
* Returns a {@code Stream} consisting of the elements of this stream,
* each boxed to a {@code Long}.
*
+ * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+ * operation</a>.
+ *
* @return a {@code Stream} consistent of the elements of this stream,
* each boxed to {@code Long}
*/
@@ -679,7 +734,7 @@
}
/**
- * Returns a sequential stream whose elements are the specified values.
+ * Returns a sequential ordered stream whose elements are the specified values.
*
* @param values the elements of the new stream
* @return the new stream
@@ -689,7 +744,7 @@
}
/**
- * Returns an infinite sequential {@code LongStream} produced by iterative
+ * Returns an infinite sequential ordered {@code LongStream} produced by iterative
* application of a function {@code f} to an initial element {@code seed},
* producing a {@code Stream} consisting of {@code seed}, {@code f(seed)},
* {@code f(f(seed))}, etc.
@@ -727,9 +782,9 @@
}
/**
- * Returns a sequential {@code LongStream} where each element is generated
- * by a {@code LongSupplier}. This is suitable for generating constant
- * streams, streams of random elements, etc.
+ * Returns a sequential stream where each element is generated by
+ * the provided {@code LongSupplier}. This is suitable for generating
+ * constant streams, streams of random elements, etc.
*
* @param s the {@code LongSupplier} for generated elements
* @return a new sequential {@code LongStream}
@@ -741,7 +796,7 @@
}
/**
- * Returns a sequential {@code LongStream} from {@code startInclusive}
+ * Returns a sequential ordered {@code LongStream} from {@code startInclusive}
* (inclusive) to {@code endExclusive} (exclusive) by an incremental step of
* {@code 1}.
*
@@ -774,7 +829,7 @@
}
/**
- * Returns a sequential {@code LongStream} from {@code startInclusive}
+ * Returns a sequential ordered {@code LongStream} from {@code startInclusive}
* (inclusive) to {@code endInclusive} (inclusive) by an incremental step of
* {@code 1}.
*
@@ -808,16 +863,16 @@
}
/**
- * Creates a lazy concatenated {@code LongStream} whose elements are all the
- * elements of a first {@code LongStream} succeeded by all the elements of the
- * second {@code LongStream}. The resulting stream is ordered if both
+ * Creates a lazily concatenated stream whose elements are all the
+ * elements of the first stream followed by all the elements of the
+ * second stream. The resulting stream is ordered if both
* of the input streams are ordered, and parallel if either of the input
* streams is parallel. When the resulting stream is closed, the close
* handlers for both input streams are invoked.
*
* @param a the first stream
- * @param b the second stream to concatenate on to end of the first stream
- * @return the concatenation of the two streams
+ * @param b the second stream
+ * @return the concatenation of the two input streams
*/
public static LongStream concat(LongStream a, LongStream b) {
Objects.requireNonNull(a);
@@ -832,9 +887,9 @@
/**
* A mutable builder for a {@code LongStream}.
*
- * <p>A stream builder has a lifecycle, where it starts in a building
- * phase, during which elements can be added, and then transitions to a
- * built phase, after which elements may not be added. The built phase
+ * <p>A stream builder has a lifecycle, which starts in a building
+ * phase, during which elements can be added, and then transitions to a built
+ * phase, after which elements may not be added. The built phase begins
* begins when the {@link #build()} method is called, which creates an
* ordered stream whose elements are the elements that were added to the
* stream builder, in the order they were added.