8008682: Inital Streams public API
Reviewed-by: mduigou, dholmes, darcy
Contributed-by: Brian Goetz <brian.goetz@oracle.com>, Mike Duigou <mike.duigou@oracle.com>, Paul Sandoz <paul.sandoz@oracle.com>, JSR-335 EG <lambda-libs-spec-experts@openjdk.java.net>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/util/stream/BaseStream.java Wed Apr 17 14:39:04 2013 -0400
@@ -0,0 +1,108 @@
+/*
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package java.util.stream;
+
+import java.util.Iterator;
+import java.util.Spliterator;
+
+/**
+ * Base interface for stream types such as {@link Stream}, {@link IntStream},
+ * etc. Contains methods common to all stream types. Many of these methods
+ * are implemented by {@link AbstractPipeline}, even though
+ * {@code AbstractPipeline} does not directly implement {@code BaseStream}.
+ *
+ * @param <T> type of stream elements
+ * @param <S> type of stream implementing {@code BaseStream}
+ * @since 1.8
+ */
+interface BaseStream<T, S extends BaseStream<T, S>> {
+ /**
+ * Returns an iterator for the elements of this stream.
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">terminal
+ * operation</a>.
+ *
+ * @return the element iterator for this stream
+ */
+ Iterator<T> iterator();
+
+ /**
+ * Returns a spliterator for the elements of this stream.
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">terminal
+ * operation</a>.
+ *
+ * @return the element spliterator for this stream
+ */
+ Spliterator<T> spliterator();
+
+ /**
+ * Returns whether this stream, when executed, would execute in parallel
+ * (assuming no further modification of the stream, such as appending
+ * further intermediate operations or changing its parallelism). Calling
+ * this method after invoking an intermediate or terminal stream operation
+ * method may yield unpredictable results.
+ *
+ * @return {@code true} if this stream would execute in parallel if executed
+ * without further modification otherwise {@code false}
+ */
+ boolean isParallel();
+
+ /**
+ * Returns an equivalent stream that is sequential. May return
+ * itself, either because the stream was already sequential, or because
+ * the underlying stream state was modified to be sequential.
+ *
+ * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+ * operation</a>.
+ *
+ * @return a sequential stream
+ */
+ S sequential();
+
+ /**
+ * Returns an equivalent stream that is parallel. May return
+ * itself, either because the stream was already parallel, or because
+ * the underlying stream state was modified to be parallel.
+ *
+ * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+ * operation</a>.
+ *
+ * @return a parallel stream
+ */
+ S parallel();
+
+ /**
+ * Returns an equivalent stream that is
+ * <a href="package-summary.html#Ordering">unordered</a>. May return
+ * itself if the stream was already unordered.
+ *
+ * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+ * operation</a>.
+ *
+ * @return an unordered stream
+ */
+ S unordered();
+}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/util/stream/CloseableStream.java Wed Apr 17 14:39:04 2013 -0400
@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package java.util.stream;
+
+/**
+ * A {@code CloseableStream} is a {@code Stream} that can be closed.
+ * The close method is invoked to release resources that the object is
+ * holding (such as open files).
+ *
+ * @param <T> The type of stream elements
+ * @since 1.8
+ */
+public interface CloseableStream<T> extends Stream<T>, AutoCloseable {
+
+ /**
+ * Closes this resource, relinquishing any underlying resources.
+ * This method is invoked automatically on objects managed by the
+ * {@code try}-with-resources statement. Does nothing if called when
+ * the resource has already been closed.
+ *
+ * This method does not allow throwing checked {@code Exception}s like
+ * {@link AutoCloseable#close() AutoCloseable.close()}. Cases where the
+ * close operation may fail require careful attention by implementers. It
+ * is strongly advised to relinquish the underlying resources and to
+ * internally <em>mark</em> the resource as closed. The {@code close}
+ * method is unlikely to be invoked more than once and so this ensures
+ * that the resources are released in a timely manner. Furthermore it
+ * reduces problems that could arise when the resource wraps, or is
+ * wrapped, by another resource.
+ *
+ * @see AutoCloseable#close()
+ */
+ void close();
+}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/util/stream/Collector.java Wed Apr 17 14:39:04 2013 -0400
@@ -0,0 +1,249 @@
+/*
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package java.util.stream;
+
+import java.util.Collections;
+import java.util.Set;
+import java.util.function.BiFunction;
+import java.util.function.BinaryOperator;
+import java.util.function.Supplier;
+
+/**
+ * A <a href="package-summary.html#Reduction">reduction operation</a> that
+ * supports folding input elements into a cumulative result. The result may be
+ * a value or may be a mutable result container. Examples of operations
+ * accumulating results into a mutable result container include: accumulating
+ * input elements into a {@code Collection}; concatenating strings into a
+ * {@code StringBuilder}; computing summary information about elements such as
+ * sum, min, max, or average; computing "pivot table" summaries such as "maximum
+ * valued transaction by seller", etc. Reduction operations can be performed
+ * either sequentially or in parallel.
+ *
+ * <p>The following are examples of using the predefined {@code Collector}
+ * implementations in {@link Collectors} with the {@code Stream} API to perform
+ * mutable reduction tasks:
+ * <pre>{@code
+ * // Accumulate elements into a List
+ * List<String> list = stream.collect(Collectors.toList());
+ *
+ * // Accumulate elements into a TreeSet
+ * Set<String> list = stream.collect(Collectors.toCollection(TreeSet::new));
+ *
+ * // Convert elements to strings and concatenate them, separated by commas
+ * String joined = stream.map(Object::toString)
+ * .collect(Collectors.toStringJoiner(", "))
+ * .toString();
+ *
+ * // Find highest-paid employee
+ * Employee highestPaid = employees.stream()
+ * .collect(Collectors.maxBy(Comparators.comparing(Employee::getSalary)));
+ *
+ * // Group employees by department
+ * Map<Department, List<Employee>> byDept
+ * = employees.stream()
+ * .collect(Collectors.groupingBy(Employee::getDepartment));
+ *
+ * // Find highest-paid employee by department
+ * Map<Department, Employee> highestPaidByDept
+ * = employees.stream()
+ * .collect(Collectors.groupingBy(Employee::getDepartment,
+ * Collectors.maxBy(Comparators.comparing(Employee::getSalary))));
+ *
+ * // Partition students into passing and failing
+ * Map<Boolean, List<Student>> passingFailing =
+ * students.stream()
+ * .collect(Collectors.partitioningBy(s -> s.getGrade() >= PASS_THRESHOLD);
+ *
+ * }</pre>
+ *
+ * <p>A {@code Collector} is specified by three functions that work together to
+ * manage a result or result container. They are: creation of an initial
+ * result, incorporating a new data element into a result, and combining two
+ * results into one. The last function -- combining two results into one -- is
+ * used during parallel operations, where subsets of the input are accumulated
+ * in parallel, and then the subresults merged into a combined result. The
+ * result may be a mutable container or a value. If the result is mutable, the
+ * accumulation and combination functions may either mutate their left argument
+ * and return that (such as adding elements to a collection), or return a new
+ * result, in which case it should not perform any mutation.
+ *
+ * <p>Collectors also have a set of characteristics, including
+ * {@link Characteristics#CONCURRENT} and
+ * {@link Characteristics#STRICTLY_MUTATIVE}. These characteristics provide
+ * hints that can be used by a reduction implementation to provide better
+ * performance.
+ *
+ * <p>Libraries that implement reduction based on {@code Collector}, such as
+ * {@link Stream#collect(Collector)}, must adhere to the following constraints:
+ * <ul>
+ * <li>The first argument passed to the accumulator function, and both
+ * arguments passed to the combiner function, must be the result of a
+ * previous invocation of {@link #resultSupplier()}, {@link #accumulator()},
+ * or {@link #combiner()}.</li>
+ * <li>The implementation should not do anything with the result of any of
+ * the result supplier, accumulator, or combiner functions other than to
+ * pass them again to the accumulator or combiner functions, or return them
+ * to the caller of the reduction operation.</li>
+ * <li>If a result is passed to the accumulator or combiner function, and
+ * the same object is not returned from that function, it is never used
+ * again.</li>
+ * <li>Once a result is passed to the combiner function, it is never passed
+ * to the accumulator function again.</li>
+ * <li>For non-concurrent collectors, any result returned from the result
+ * supplier, accumulator, or combiner functions must be serially
+ * thread-confined. This enables collection to occur in parallel without
+ * the {@code Collector} needing to implement any additional synchronization.
+ * The reduction implementation must manage that the input is properly
+ * partitioned, that partitions are processed in isolation, and combining
+ * happens only after accumulation is complete.</li>
+ * <li>For concurrent collectors, an implementation is free to (but not
+ * required to) implement reduction concurrently. A concurrent reduction
+ * is one where the accumulator function is called concurrently from
+ * multiple threads, using the same concurrently-modifiable result container,
+ * rather than keeping the result isolated during accumulation.
+ * A concurrent reduction should only be applied if the collector has the
+ * {@link Characteristics#UNORDERED} characteristics or if the
+ * originating data is unordered.</li>
+ * </ul>
+ *
+ * @apiNote
+ * Performing a reduction operation with a {@code Collector} should produce a
+ * result equivalent to:
+ * <pre>{@code
+ * BiFunction<R,T,R> accumulator = collector.accumulator();
+ * R result = collector.resultSupplier().get();
+ * for (T t : data)
+ * result = accumulator.apply(result, t);
+ * return result;
+ * }</pre>
+ *
+ * <p>However, the library is free to partition the input, perform the reduction
+ * on the partitions, and then use the combiner function to combine the partial
+ * results to achieve a parallel reduction. Depending on the specific reduction
+ * operation, this may perform better or worse, depending on the relative cost
+ * of the accumulator and combiner functions.
+ *
+ * <p>An example of an operation that can be easily modeled by {@code Collector}
+ * is accumulating elements into a {@code TreeSet}. In this case, the {@code
+ * resultSupplier()} function is {@code () -> new Treeset<T>()}, the
+ * {@code accumulator} function is
+ * {@code (set, element) -> { set.add(element); return set; }}, and the combiner
+ * function is {@code (left, right) -> { left.addAll(right); return left; }}.
+ * (This behavior is implemented by
+ * {@code Collectors.toCollection(TreeSet::new)}).
+ *
+ * TODO Associativity and commutativity
+ *
+ * @see Stream#collect(Collector)
+ * @see Collectors
+ *
+ * @param <T> the type of input element to the collect operation
+ * @param <R> the result type of the collect operation
+ * @since 1.8
+ */
+public interface Collector<T, R> {
+ /**
+ * A function that creates and returns a new result that represents
+ * "no values". If the accumulator or combiner functions may mutate their
+ * arguments, this must be a new, empty result container.
+ *
+ * @return a function which, when invoked, returns a result representing
+ * "no values"
+ */
+ Supplier<R> resultSupplier();
+
+ /**
+ * A function that folds a new value into a cumulative result. The result
+ * may be a mutable result container or a value. The accumulator function
+ * may modify a mutable container and return it, or create a new result and
+ * return that, but if it returns a new result object, it must not modify
+ * any of its arguments.
+ *
+ * <p>If the collector has the {@link Characteristics#STRICTLY_MUTATIVE}
+ * characteristic, then the accumulator function <em>must</em> always return
+ * its first argument, after possibly mutating its state.
+ *
+ * @return a function which folds a new value into a cumulative result
+ */
+ BiFunction<R, T, R> accumulator();
+
+ /**
+ * A function that accepts two partial results and merges them. The
+ * combiner function may fold state from one argument into the other and
+ * return that, or may return a new result object, but if it returns
+ * a new result object, it must not modify the state of either of its
+ * arguments.
+ *
+ * <p>If the collector has the {@link Characteristics#STRICTLY_MUTATIVE}
+ * characteristic, then the combiner function <em>must</em> always return
+ * its first argument, after possibly mutating its state.
+ *
+ * @return a function which combines two partial results into a cumulative
+ * result
+ */
+ BinaryOperator<R> combiner();
+
+ /**
+ * Returns a {@code Set} of {@code Collector.Characteristics} indicating
+ * the characteristics of this Collector. This set should be immutable.
+ *
+ * @return an immutable set of collector characteristics
+ */
+ Set<Characteristics> characteristics();
+
+ /**
+ * Characteristics indicating properties of a {@code Collector}, which can
+ * be used to optimize reduction implementations.
+ */
+ enum Characteristics {
+ /**
+ * Indicates that this collector is <em>concurrent</em>, meaning that
+ * the result container can support the accumulator function being
+ * called concurrently with the same result container from multiple
+ * threads. Concurrent collectors must also always have the
+ * {@code STRICTLY_MUTATIVE} characteristic.
+ *
+ * <p>If a {@code CONCURRENT} collector is not also {@code UNORDERED},
+ * then it should only be evaluated concurrently if applied to an
+ * unordered data source.
+ */
+ CONCURRENT,
+
+ /**
+ * Indicates that the result container has no intrinsic order, such as
+ * a {@link Set}.
+ */
+ UNORDERED,
+
+ /**
+ * Indicates that this collector operates by strict mutation of its
+ * result container. This means that the {@link #accumulator()} and
+ * {@link #combiner()} functions will always modify the state of and
+ * return their first argument, rather than returning a different result
+ * container.
+ */
+ STRICTLY_MUTATIVE
+ }
+}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/util/stream/DelegatingStream.java Wed Apr 17 14:39:04 2013 -0400
@@ -0,0 +1,270 @@
+/*
+ * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package java.util.stream;
+
+import java.util.Comparator;
+import java.util.Iterator;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.Spliterator;
+import java.util.function.BiConsumer;
+import java.util.function.BiFunction;
+import java.util.function.BinaryOperator;
+import java.util.function.Consumer;
+import java.util.function.Function;
+import java.util.function.IntFunction;
+import java.util.function.Predicate;
+import java.util.function.Supplier;
+import java.util.function.ToDoubleFunction;
+import java.util.function.ToIntFunction;
+import java.util.function.ToLongFunction;
+
+/**
+ * A {@code Stream} implementation that delegates operations to another {@code
+ * Stream}.
+ *
+ * @param <T> type of stream elements for this stream and underlying delegate
+ * stream
+ *
+ * @since 1.8
+ */
+public class DelegatingStream<T> implements Stream<T> {
+ final private Stream<T> delegate;
+
+ /**
+ * Construct a {@code Stream} that delegates operations to another {@code
+ * Stream}.
+ *
+ * @param delegate the underlying {@link Stream} to which we delegate all
+ * {@code Stream} methods
+ * @throws NullPointerException if the delegate is null
+ */
+ public DelegatingStream(Stream<T> delegate) {
+ this.delegate = Objects.requireNonNull(delegate);
+ }
+
+ // -- BaseStream methods --
+
+ @Override
+ public Spliterator<T> spliterator() {
+ return delegate.spliterator();
+ }
+
+ @Override
+ public boolean isParallel() {
+ return delegate.isParallel();
+ }
+
+ @Override
+ public Iterator<T> iterator() {
+ return delegate.iterator();
+ }
+
+ // -- Stream methods --
+
+ @Override
+ public Stream<T> filter(Predicate<? super T> predicate) {
+ return delegate.filter(predicate);
+ }
+
+ @Override
+ public <R> Stream<R> map(Function<? super T, ? extends R> mapper) {
+ return delegate.map(mapper);
+ }
+
+ @Override
+ public IntStream mapToInt(ToIntFunction<? super T> mapper) {
+ return delegate.mapToInt(mapper);
+ }
+
+ @Override
+ public LongStream mapToLong(ToLongFunction<? super T> mapper) {
+ return delegate.mapToLong(mapper);
+ }
+
+ @Override
+ public DoubleStream mapToDouble(ToDoubleFunction<? super T> mapper) {
+ return delegate.mapToDouble(mapper);
+ }
+
+ @Override
+ public <R> Stream<R> flatMap(Function<? super T, ? extends Stream<? extends R>> mapper) {
+ return delegate.flatMap(mapper);
+ }
+
+ @Override
+ public IntStream flatMapToInt(Function<? super T, ? extends IntStream> mapper) {
+ return delegate.flatMapToInt(mapper);
+ }
+
+ @Override
+ public LongStream flatMapToLong(Function<? super T, ? extends LongStream> mapper) {
+ return delegate.flatMapToLong(mapper);
+ }
+
+ @Override
+ public DoubleStream flatMapToDouble(Function<? super T, ? extends DoubleStream> mapper) {
+ return delegate.flatMapToDouble(mapper);
+ }
+
+ @Override
+ public Stream<T> distinct() {
+ return delegate.distinct();
+ }
+
+ @Override
+ public Stream<T> sorted() {
+ return delegate.sorted();
+ }
+
+ @Override
+ public Stream<T> sorted(Comparator<? super T> comparator) {
+ return delegate.sorted(comparator);
+ }
+
+ @Override
+ public void forEach(Consumer<? super T> action) {
+ delegate.forEach(action);
+ }
+
+ @Override
+ public void forEachOrdered(Consumer<? super T> action) {
+ delegate.forEachOrdered(action);
+ }
+
+ @Override
+ public Stream<T> peek(Consumer<? super T> consumer) {
+ return delegate.peek(consumer);
+ }
+
+ @Override
+ public Stream<T> limit(long maxSize) {
+ return delegate.limit(maxSize);
+ }
+
+ @Override
+ public Stream<T> substream(long startingOffset) {
+ return delegate.substream(startingOffset);
+ }
+
+ @Override
+ public Stream<T> substream(long startingOffset, long endingOffset) {
+ return delegate.substream(startingOffset, endingOffset);
+ }
+
+ @Override
+ public <A> A[] toArray(IntFunction<A[]> generator) {
+ return delegate.toArray(generator);
+ }
+
+ @Override
+ public Object[] toArray() {
+ return delegate.toArray();
+ }
+
+ @Override
+ public T reduce(T identity, BinaryOperator<T> accumulator) {
+ return delegate.reduce(identity, accumulator);
+ }
+
+ @Override
+ public Optional<T> reduce(BinaryOperator<T> accumulator) {
+ return delegate.reduce(accumulator);
+ }
+
+ @Override
+ public <U> U reduce(U identity, BiFunction<U, ? super T, U> accumulator,
+ BinaryOperator<U> combiner) {
+ return delegate.reduce(identity, accumulator, combiner);
+ }
+
+ @Override
+ public <R> R collect(Supplier<R> resultFactory,
+ BiConsumer<R, ? super T> accumulator,
+ BiConsumer<R, R> combiner) {
+ return delegate.collect(resultFactory, accumulator, combiner);
+ }
+
+ @Override
+ public <R> R collect(Collector<? super T, R> collector) {
+ return delegate.collect(collector);
+ }
+
+ @Override
+ public Optional<T> max(Comparator<? super T> comparator) {
+ return delegate.max(comparator);
+ }
+
+ @Override
+ public Optional<T> min(Comparator<? super T> comparator) {
+ return delegate.min(comparator);
+ }
+
+ @Override
+ public long count() {
+ return delegate.count();
+ }
+
+ @Override
+ public boolean anyMatch(Predicate<? super T> predicate) {
+ return delegate.anyMatch(predicate);
+ }
+
+ @Override
+ public boolean allMatch(Predicate<? super T> predicate) {
+ return delegate.allMatch(predicate);
+ }
+
+ @Override
+ public boolean noneMatch(Predicate<? super T> predicate) {
+ return delegate.noneMatch(predicate);
+ }
+
+ @Override
+ public Optional<T> findFirst() {
+ return delegate.findFirst();
+ }
+
+ @Override
+ public Optional<T> findAny() {
+ return delegate.findAny();
+ }
+
+ @Override
+ public Stream<T> unordered() {
+ return delegate.unordered();
+ }
+
+ @Override
+ public Stream<T> sequential() {
+ return delegate.sequential();
+ }
+
+ @Override
+ public Stream<T> parallel() {
+ return delegate.parallel();
+ }
+}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/util/stream/DoubleStream.java Wed Apr 17 14:39:04 2013 -0400
@@ -0,0 +1,652 @@
+/*
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package java.util.stream;
+
+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.DoubleBinaryOperator;
+import java.util.function.DoubleConsumer;
+import java.util.function.DoubleFunction;
+import java.util.function.DoublePredicate;
+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 primitive double 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.
+ *
+ * <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. 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(DoubleConsumer)}), are explicitly nondeterministic for parallel
+ * execution of stream pipelines.
+ *
+ * <p>Unless otherwise noted, passing a {@code null} argument to any stream
+ * method may result in a {@link NullPointerException}.
+ *
+ * @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.
+ *
+ * @since 1.8
+ * @see <a href="package-summary.html">java.util.stream</a>
+ */
+public interface DoubleStream extends BaseStream<Double, DoubleStream> {
+
+ /**
+ * Returns 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);
+
+ /**
+ * Returns 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 apply to
+ * each element
+ * @return the new stream
+ */
+ DoubleStream map(DoubleUnaryOperator mapper);
+
+ /**
+ * Returns 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 <U> the element type of the new stream
+ * @param mapper a <a href="package-summary.html#NonInterference">
+ * non-interfering, stateless</a> function to apply to each
+ * element
+ * @return the new stream
+ */
+ <U> Stream<U> mapToObj(DoubleFunction<? extends U> mapper);
+
+ /**
+ * Returns 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 apply to each
+ * element
+ * @return the new stream
+ */
+ IntStream mapToInt(DoubleToIntFunction mapper);
+
+ /**
+ * Returns 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 apply to each
+ * element
+ * @return the new stream
+ */
+ LongStream mapToLong(DoubleToLongFunction mapper);
+
+ /**
+ * 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.
+ *
+ * <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 DoubleStream} of new
+ * values
+ * @return the new stream
+ * @see Stream#flatMap(Function)
+ */
+ DoubleStream flatMap(DoubleFunction<? extends DoubleStream> mapper);
+
+ /**
+ * Returns a stream consisting of the distinct elements of this stream. The
+ * elements are compared for equality according to
+ * {@link java.lang.Double#compare(double, double)}.
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">stateful
+ * intermediate operation</a>.
+ *
+ * @return the result stream
+ */
+ DoubleStream distinct();
+
+ /**
+ * Returns a stream consisting of the elements of this stream in sorted
+ * order. The elements are compared for equality according to
+ * {@link java.lang.Double#compare(double, double)}.
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">stateful
+ * intermediate operation</a>.
+ *
+ * @return the result stream
+ */
+ DoubleStream sorted();
+
+ /**
+ * Returns 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>{@code
+ * 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);
+
+ /**
+ * Returns 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
+ * @throws IllegalArgumentException if {@code maxSize} is negative
+ */
+ DoubleStream limit(long maxSize);
+
+ /**
+ * 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
+ * empty stream will be returned.
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">stateful
+ * intermediate operation</a>.
+ *
+ * @param startInclusive the number of leading elements to skip
+ * @return the new stream
+ * @throws IllegalArgumentException if {@code startInclusive} is negative
+ */
+ DoubleStream substream(long startInclusive);
+
+ /**
+ * 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.
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+ * stateful intermediate operation</a>.
+ *
+ * @param startInclusive the starting position of the substream, inclusive
+ * @param endExclusive the ending position of the substream, exclusive
+ * @return the new stream
+ * @throws IllegalArgumentException if {@code startInclusive} or
+ * {@code endExclusive} is negative or {@code startInclusive} is greater
+ * than {@code endExclusive}
+ */
+ DoubleStream substream(long startInclusive, long endExclusive);
+
+ /**
+ * Performs an action 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 action accesses shared state, it is
+ * responsible for providing the required synchronization.
+ *
+ * @param action a <a href="package-summary.html#NonInterference">
+ * non-interfering</a> action to perform on the elements
+ */
+ void forEach(DoubleConsumer action);
+
+ /**
+ * Performs an action 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 action a <a href="package-summary.html#NonInterference">
+ * non-interfering</a> action to perform on the elements
+ * @see #forEach(DoubleConsumer)
+ */
+ void forEachOrdered(DoubleConsumer action);
+
+ /**
+ * Returns 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 returns the reduced value. This is equivalent
+ * to:
+ * <pre>{@code
+ * 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>{@code
+ * double sum = numbers.reduce(0, (a, b) -> a+b);
+ * }</pre>
+ *
+ * or more compactly:
+ *
+ * <pre>{@code
+ * 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()
+ * @see #min()
+ * @see #max()
+ * @see #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 returns an {@code OptionalDouble} describing the reduced
+ * value, if any. This is equivalent to:
+ * <pre>{@code
+ * 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>{@code
+ * R result = resultFactory.get();
+ * for (double element : this stream)
+ * accumulator.accept(result, element);
+ * return result;
+ * }</pre>
+ *
+ * <p>Like {@link #reduce(double, DoubleBinaryOperator)}, {@code collect}
+ * operations can be parallelized without requiring additional
+ * synchronization.
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">terminal
+ * 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 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
+ * @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. The sum returned can vary
+ * depending upon the order in which elements are encountered. This is due
+ * to accumulated rounding error in addition of values of differing
+ * magnitudes. Elements sorted by increasing absolute magnitude tend to
+ * yield more accurate results. If any stream element is a {@code NaN} or
+ * the sum is at any point a {@code NaN} then the sum will be {@code NaN}.
+ * This is a special case of a
+ * <a href="package-summary.html#MutableReduction">reduction</a> and is
+ * equivalent to:
+ * <pre>{@code
+ * return reduce(0, Double::sum);
+ * }</pre>
+ *
+ * @return the sum of elements in this stream
+ */
+ double sum();
+
+ /**
+ * Returns an {@code OptionalDouble} describing the minimum element of this
+ * stream, or an empty OptionalDouble if this stream is empty. The minimum
+ * element will be {@code Double.NaN} if any stream element was NaN. Unlike
+ * the numerical comparison operators, this method considers negative zero
+ * to be strictly smaller than positive zero. This is a special case of a
+ * <a href="package-summary.html#MutableReduction">reduction</a> and is
+ * equivalent to:
+ * <pre>{@code
+ * return reduce(Double::min);
+ * }</pre>
+ *
+ * @return an {@code OptionalDouble} containing the minimum element of this
+ * stream, or an empty optional if the stream is empty
+ */
+ OptionalDouble min();
+
+ /**
+ * Returns an {@code OptionalDouble} describing the maximum element of this
+ * stream, or an empty OptionalDouble if this stream is empty. The maximum
+ * element will be {@code Double.NaN} if any stream element was NaN. Unlike
+ * the numerical comparison operators, this method considers negative zero
+ * to be strictly smaller than positive zero. This is a
+ * special case of a
+ * <a href="package-summary.html#MutableReduction">reduction</a> and is
+ * equivalent to:
+ * <pre>{@code
+ * return reduce(Double::max);
+ * }</pre>
+ *
+ * @return an {@code OptionalDouble} containing the maximum element of this
+ * stream, or an empty optional if the stream is empty
+ */
+ 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>{@code
+ * return mapToLong(e -> 1L).sum();
+ * }</pre>
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+ *
+ * @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. The average
+ * returned can vary depending upon the order in which elements are
+ * encountered. This is due to accumulated rounding error in addition of
+ * elements of differing magnitudes. Elements sorted by increasing absolute
+ * magnitude tend to yield more accurate results. If any recorded value is
+ * a {@code NaN} or the sum is at any point a {@code NaN} then the average
+ * will be {@code NaN}. This is a special case of a
+ * <a href="package-summary.html#MutableReduction">reduction</a>.
+ *
+ * @return an {@code OptionalDouble} containing the average element of this
+ * stream, or an empty optional if the stream is empty
+ */
+ 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 {@code true} if any elements of the stream match the provided
+ * predicate otherwise {@code false}
+ */
+ 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 {@code true} if all elements of the stream match the provided
+ * predicate otherwise {@code false}
+ */
+ 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 {@code true} if no elements of the stream match the provided
+ * predicate otherwise {@code false}
+ */
+ 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. If the stream has no encounter order, than any
+ * element may be returned.
+ *
+ * <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,
+ * each boxed to a {@code Double}
+ */
+ Stream<Double> boxed();
+
+ @Override
+ DoubleStream sequential();
+
+ @Override
+ DoubleStream parallel();
+
+ @Override
+ PrimitiveIterator.OfDouble iterator();
+
+ @Override
+ Spliterator.OfDouble spliterator();
+}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/util/stream/IntStream.java Wed Apr 17 14:39:04 2013 -0400
@@ -0,0 +1,655 @@
+/*
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package java.util.stream;
+
+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.Function;
+import java.util.function.IntBinaryOperator;
+import java.util.function.IntConsumer;
+import java.util.function.IntFunction;
+import java.util.function.IntPredicate;
+import java.util.function.IntToDoubleFunction;
+import java.util.function.IntToLongFunction;
+import java.util.function.IntUnaryOperator;
+import java.util.function.ObjIntConsumer;
+import java.util.function.Supplier;
+
+/**
+ * A sequence of primitive integer 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.
+ *
+ * <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. 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(IntConsumer)}), are explicitly nondeterministic for parallel
+ * execution of stream pipelines.
+ *
+ * <p>Unless otherwise noted, passing a {@code null} argument to any stream
+ * method may result in a {@link NullPointerException}.
+ *
+ * @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.
+ *
+ * @since 1.8
+ * @see <a href="package-summary.html">java.util.stream</a>
+ */
+public interface IntStream extends BaseStream<Integer, IntStream> {
+
+ /**
+ * Returns 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);
+
+ /**
+ * Returns 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 apply to each
+ * element
+ * @return the new stream
+ */
+ IntStream map(IntUnaryOperator mapper);
+
+ /**
+ * Returns 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 <U> the element type of the new stream
+ * @param mapper a <a href="package-summary.html#NonInterference">
+ * non-interfering, stateless</a> function to apply to each
+ * element
+ * @return the new stream
+ */
+ <U> Stream<U> mapToObj(IntFunction<? extends U> mapper);
+
+ /**
+ * Returns 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 apply to each
+ * element
+ * @return the new stream
+ */
+ LongStream mapToLong(IntToLongFunction mapper);
+
+ /**
+ * Returns 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 apply to each
+ * element
+ * @return the new stream
+ */
+ DoubleStream mapToDouble(IntToDoubleFunction mapper);
+
+ /**
+ * 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.
+ *
+ * <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 IntStream} of new
+ * values
+ * @return the new stream
+ * @see Stream#flatMap(Function)
+ */
+ IntStream flatMap(IntFunction<? extends IntStream> mapper);
+
+ /**
+ * Returns 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();
+
+ /**
+ * Returns 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();
+
+ /**
+ * Returns 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>{@code
+ * 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);
+
+ /**
+ * Returns 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
+ * @throws IllegalArgumentException if {@code maxSize} is negative
+ */
+ IntStream limit(long maxSize);
+
+ /**
+ * 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
+ * empty stream will be returned.
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">stateful
+ * intermediate operation</a>.
+ *
+ * @param startInclusive the number of leading elements to skip
+ * @return the new stream
+ * @throws IllegalArgumentException if {@code startInclusive} is negative
+ */
+ IntStream substream(long startInclusive);
+
+ /**
+ * 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.
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+ * stateful intermediate operation</a>.
+ *
+ * @param startInclusive the starting position of the substream, inclusive
+ * @param endExclusive the ending position of the substream, exclusive
+ * @return the new stream
+ * @throws IllegalArgumentException if {@code startInclusive} or
+ * {@code endExclusive} is negative or {@code startInclusive} is greater
+ * than {@code endExclusive}
+ */
+ IntStream substream(long startInclusive, long endExclusive);
+
+ /**
+ * Performs an action 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 action accesses shared state, it is
+ * responsible for providing the required synchronization.
+ *
+ * @param action a <a href="package-summary.html#NonInterference">
+ * non-interfering</a> action to perform on the elements
+ */
+ void forEach(IntConsumer action);
+
+ /**
+ * Performs an action 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 action a <a href="package-summary.html#NonInterference">
+ * non-interfering</a> action to perform on the elements
+ * @see #forEach(IntConsumer)
+ */
+ void forEachOrdered(IntConsumer action);
+
+ /**
+ * Returns 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 returns the reduced value. This is equivalent
+ * to:
+ * <pre>{@code
+ * 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>{@code
+ * int sum = integers.reduce(0, (a, b) -> a+b);
+ * }</pre>
+ *
+ * or more compactly:
+ *
+ * <pre>{@code
+ * 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()
+ * @see #min()
+ * @see #max()
+ * @see #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 returns an {@code OptionalInt} describing the reduced value,
+ * if any. This is equivalent to:
+ * <pre>{@code
+ * 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>{@code
+ * R result = resultFactory.get();
+ * for (int element : this stream)
+ * accumulator.accept(result, element);
+ * return result;
+ * }</pre>
+ *
+ * <p>Like {@link #reduce(int, IntBinaryOperator)}, {@code collect} operations
+ * can be parallelized without requiring additional synchronization.
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">terminal
+ * 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 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
+ * @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>{@code
+ * return reduce(0, Integer::sum);
+ * }</pre>
+ *
+ * @return the sum of elements in this stream
+ */
+ int sum();
+
+ /**
+ * Returns an {@code OptionalInt} 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>
+ * and is equivalent to:
+ * <pre>{@code
+ * return reduce(Integer::min);
+ * }</pre>
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+ *
+
+ * @return an {@code OptionalInt} containing the minimum element of this
+ * stream, or an empty {@code OptionalInt} if the stream is empty
+ */
+ OptionalInt min();
+
+ /**
+ * Returns an {@code OptionalInt} 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>
+ * and is equivalent to:
+ * <pre>{@code
+ * return reduce(Integer::max);
+ * }</pre>
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">terminal
+ * operation</a>.
+ *
+ * @return an {@code OptionalInt} containing the maximum element of this
+ * stream, or an empty {@code OptionalInt} if the stream is empty
+ */
+ 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>{@code
+ * return mapToLong(e -> 1L).sum();
+ * }</pre>
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+ *
+ * @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 an {@code OptionalDouble} containing the average element of this
+ * stream, or an empty optional if the stream is empty
+ */
+ 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 {@code true} if any elements of the stream match the provided
+ * predicate otherwise {@code false}
+ */
+ 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 {@code true} if all elements of the stream match the provided
+ * predicate otherwise {@code false}
+ */
+ 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 {@code true} if no elements of the stream match the provided
+ * predicate otherwise {@code false}
+ */
+ 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. If the stream has no encounter order, than any element
+ * may be returned.
+ *
+ * <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,
+ * each boxed to an {@code Integer}.
+ *
+ * @return a {@code Stream} consistent of the elements of this stream,
+ * each boxed to an {@code Integer}
+ */
+ Stream<Integer> boxed();
+
+ @Override
+ IntStream sequential();
+
+ @Override
+ IntStream parallel();
+
+ @Override
+ PrimitiveIterator.OfInt iterator();
+
+ @Override
+ Spliterator.OfInt spliterator();
+}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/util/stream/LongStream.java Wed Apr 17 14:39:04 2013 -0400
@@ -0,0 +1,646 @@
+/*
+ * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package java.util.stream;
+
+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.Function;
+import java.util.function.LongBinaryOperator;
+import java.util.function.LongConsumer;
+import java.util.function.LongFunction;
+import java.util.function.LongPredicate;
+import java.util.function.LongToDoubleFunction;
+import java.util.function.LongToIntFunction;
+import java.util.function.LongUnaryOperator;
+import java.util.function.ObjLongConsumer;
+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.
+ *
+ * <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. 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>Unless otherwise noted, passing a {@code null} argument to any stream
+ * method may result in a {@link NullPointerException}.
+ *
+ * @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.
+ *
+ * @since 1.8
+ * @see <a href="package-summary.html">java.util.stream</a>
+ */
+public interface LongStream extends BaseStream<Long, LongStream> {
+
+ /**
+ * Returns 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);
+
+ /**
+ * Returns 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 apply to each
+ * element
+ * @return the new stream
+ */
+ LongStream map(LongUnaryOperator mapper);
+
+ /**
+ * Returns 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 <U> the element type of the new stream
+ * @param mapper a <a href="package-summary.html#NonInterference">
+ * non-interfering, stateless</a> function to apply to each
+ * element
+ * @return the new stream
+ */
+ <U> Stream<U> mapToObj(LongFunction<? extends U> mapper);
+
+ /**
+ * Returns 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 apply to each
+ * element
+ * @return the new stream
+ */
+ IntStream mapToInt(LongToIntFunction mapper);
+
+ /**
+ * Returns 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 apply to each
+ * element
+ * @return the new stream
+ */
+ DoubleStream mapToDouble(LongToDoubleFunction mapper);
+
+ /**
+ * 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.
+ *
+ * <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
+ * values
+ * @return the new stream
+ * @see Stream#flatMap(Function)
+ */
+ LongStream flatMap(LongFunction<? extends LongStream> mapper);
+
+ /**
+ * Returns 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();
+
+ /**
+ * Returns 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();
+
+ /**
+ * Returns 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>{@code
+ * 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);
+
+ /**
+ * Returns 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
+ * @throws IllegalArgumentException if {@code maxSize} is negative
+ */
+ LongStream limit(long maxSize);
+
+ /**
+ * 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
+ * empty stream will be returned.
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">stateful
+ * intermediate operation</a>.
+ *
+ * @param startInclusive the number of leading elements to skip
+ * @return the new stream
+ * @throws IllegalArgumentException if {@code startInclusive} is negative
+ */
+ LongStream substream(long startInclusive);
+
+ /**
+ * 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.
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+ * stateful intermediate operation</a>.
+ *
+ * @param startInclusive the starting position of the substream, inclusive
+ * @param endExclusive the ending position of the substream, exclusive
+ * @return the new stream
+ * @throws IllegalArgumentException if {@code startInclusive} or
+ * {@code endExclusive} is negative or {@code startInclusive} is greater
+ * than {@code endExclusive}
+ */
+ LongStream substream(long startInclusive, long endExclusive);
+
+ /**
+ * Performs an action 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 action accesses shared state, it is
+ * responsible for providing the required synchronization.
+ *
+ * @param action a <a href="package-summary.html#NonInterference">
+ * non-interfering</a> action to perform on the elements
+ */
+ void forEach(LongConsumer action);
+
+ /**
+ * Performs an action 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 action a <a href="package-summary.html#NonInterference">
+ * non-interfering</a> action to perform on the elements
+ * @see #forEach(LongConsumer)
+ */
+ void forEachOrdered(LongConsumer action);
+
+ /**
+ * Returns 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 returns the reduced value. This is equivalent
+ * to:
+ * <pre>{@code
+ * 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>{@code
+ * long sum = integers.reduce(0, (a, b) -> a+b);
+ * }</pre>
+ *
+ * or more compactly:
+ *
+ * <pre>{@code
+ * 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()
+ * @see #min()
+ * @see #max()
+ * @see #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 returns an {@code OptionalLong} describing the reduced value,
+ * if any. This is equivalent to:
+ * <pre>{@code
+ * 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>{@code
+ * R result = resultFactory.get();
+ * for (long element : this stream)
+ * accumulator.accept(result, element);
+ * return result;
+ * }</pre>
+ *
+ * <p>Like {@link #reduce(long, LongBinaryOperator)}, {@code collect} operations
+ * can be parallelized without requiring additional synchronization.
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">terminal
+ * 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 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
+ * @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>{@code
+ * return reduce(0, Long::sum);
+ * }</pre>
+ *
+ * @return the sum of elements in this stream
+ */
+ long sum();
+
+ /**
+ * 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>
+ * and is equivalent to:
+ * <pre>{@code
+ * return reduce(Long::min);
+ * }</pre>
+ *
+ * <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
+ */
+ OptionalLong min();
+
+ /**
+ * 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>
+ * and is equivalent to:
+ * <pre>{@code
+ * return reduce(Long::max);
+ * }</pre>
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">terminal
+ * operation</a>.
+ *
+ * @return an {@code OptionalLong} containing the maximum element of this
+ * stream, or an empty {@code OptionalLong} if the stream is empty
+ */
+ 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>{@code
+ * return map(e -> 1L).sum();
+ * }</pre>
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+ *
+ * @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 an {@code OptionalDouble} containing the average element of this
+ * stream, or an empty optional if the stream is empty
+ */
+ 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 {@code true} if any elements of the stream match the provided
+ * predicate otherwise {@code false}
+ */
+ 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 {@code true} if all elements of the stream match the provided
+ * predicate otherwise {@code false}
+ */
+ 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 {@code true} if no elements of the stream match the provided
+ * predicate otherwise {@code false}
+ */
+ 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. If the stream has no encounter order, than any element
+ * may be returned.
+ *
+ * <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,
+ * each boxed to a {@code Long}.
+ *
+ * @return a {@code Stream} consistent of the elements of this stream,
+ * each boxed to {@code Long}
+ */
+ Stream<Long> boxed();
+
+ @Override
+ LongStream sequential();
+
+ @Override
+ LongStream parallel();
+
+ @Override
+ PrimitiveIterator.OfLong iterator();
+
+ @Override
+ Spliterator.OfLong spliterator();
+}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/util/stream/Stream.java Wed Apr 17 14:39:04 2013 -0400
@@ -0,0 +1,782 @@
+/*
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package java.util.stream;
+
+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.Consumer;
+import java.util.function.Function;
+import java.util.function.IntFunction;
+import java.util.function.Predicate;
+import java.util.function.Supplier;
+import java.util.function.ToDoubleFunction;
+import java.util.function.ToIntFunction;
+import java.util.function.ToLongFunction;
+
+// @@@ Specification to-do list @@@
+// - Describe the difference between sequential and parallel streams
+// - More general information about reduce, better definitions for associativity, more description of
+// how reduce employs parallelism, more examples
+// - Role of stream flags in various operations, specifically ordering
+// - Whether each op preserves encounter order
+// @@@ Specification to-do list @@@
+
+/**
+ * A sequence of 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.
+ *
+ * <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. 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(Consumer)}), are explicitly nondeterministic for parallel
+ * execution of stream pipelines.
+ *
+ * <p>Unless otherwise noted, passing a {@code null} argument to any stream
+ * method may result in a {@link NullPointerException}.
+ *
+ * @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.
+ *
+ * @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>> {
+
+ /**
+ * Returns 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
+ */
+ Stream<T> filter(Predicate<? super T> predicate);
+
+ /**
+ * Returns 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 <R> The element type of the new stream
+ * @param mapper a <a href="package-summary.html#NonInterference">
+ * non-interfering, stateless</a> function to apply to each
+ * element
+ * @return the new stream
+ */
+ <R> Stream<R> map(Function<? super T, ? extends R> mapper);
+
+ /**
+ * Returns 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 apply to each
+ * element
+ * @return the new stream
+ */
+ IntStream mapToInt(ToIntFunction<? super T> mapper);
+
+ /**
+ * Returns 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 apply to each
+ * element
+ * @return the new stream
+ */
+ LongStream mapToLong(ToLongFunction<? super T> mapper);
+
+ /**
+ * Returns 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 apply to each
+ * element
+ * @return the new stream
+ */
+ DoubleStream mapToDouble(ToDoubleFunction<? super T> mapper);
+
+ /**
+ * 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. If the result of the mapping
+ * function is {@code null}, this is treated as if the result is 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 <R> The element type of the new stream
+ * @param mapper a <a href="package-summary.html#NonInterference">
+ * non-interfering, stateless</a> function to apply to each
+ * element which produces a stream of new values
+ * @return the new stream
+ */
+ <R> Stream<R> flatMap(Function<? super T, ? extends Stream<? extends R>> mapper);
+
+ /**
+ * Returns an {@code IntStream} 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. If the result of
+ * the mapping function is {@code null}, this is treated as if the result is
+ * an empty 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 apply to each
+ * element which produces a stream of new values
+ * @return the new stream
+ */
+ IntStream flatMapToInt(Function<? super T, ? extends IntStream> mapper);
+
+ /**
+ * Returns a {@code LongStream} 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. If the result
+ * of the mapping function is {@code null}, this is treated as if the
+ * result is an empty 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 apply to
+ * each element which produces a stream of new values
+ * @return the new stream
+ */
+ LongStream flatMapToLong(Function<? super T, ? extends LongStream> mapper);
+
+ /**
+ * Returns a {@code DoubleStream} 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. If the result
+ * of the mapping function is {@code null}, this is treated as if the result
+ * is an empty 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 apply to each
+ * element which produces a stream of new values
+ * @return the new stream
+ */
+ DoubleStream flatMapToDouble(Function<? super T, ? extends DoubleStream> mapper);
+
+ /**
+ * Returns 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>.
+ *
+ * @return the new stream
+ */
+ Stream<T> distinct();
+
+ /**
+ * Returns 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>.
+ *
+ * @return the new stream
+ */
+ Stream<T> sorted();
+
+ /**
+ * Returns a stream consisting of the elements of this stream, sorted
+ * according to the provided {@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
+ * @return the new stream
+ */
+ Stream<T> sorted(Comparator<? super T> comparator);
+
+ /**
+ * Returns 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>{@code
+ * list.stream()
+ * .filter(filteringFunction)
+ * .peek(e -> {System.out.println("Filtered value: " + e); });
+ * .map(mappingFunction)
+ * .peek(e -> {System.out.println("Mapped value: " + e); });
+ * .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
+ * @return the new stream
+ */
+ Stream<T> peek(Consumer<? super T> consumer);
+
+ /**
+ * Returns 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
+ * @throws IllegalArgumentException if {@code maxSize} is negative
+ */
+ Stream<T> limit(long maxSize);
+
+ /**
+ * 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
+ * empty stream will be returned.
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">stateful
+ * intermediate operation</a>.
+ *
+ * @param startInclusive the number of leading elements to skip
+ * @return the new stream
+ * @throws IllegalArgumentException if {@code startInclusive} is negative
+ */
+ Stream<T> substream(long startInclusive);
+
+ /**
+ * 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.
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+ * stateful intermediate operation</a>.
+ *
+ * @param startInclusive the starting position of the substream, inclusive
+ * @param endExclusive the ending position of the substream, exclusive
+ * @return the new stream
+ * @throws IllegalArgumentException if {@code startInclusive} or
+ * {@code endExclusive} is negative or {@code startInclusive} is greater
+ * than {@code endExclusive}
+ */
+ Stream<T> substream(long startInclusive, long endExclusive);
+
+ /**
+ * Performs an action 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 action accesses shared state, it is
+ * responsible for providing the required synchronization.
+ *
+ * @param action a <a href="package-summary.html#NonInterference">
+ * non-interfering</a> action to perform on the elements
+ */
+ void forEach(Consumer<? super T> action);
+
+ /**
+ * Performs an action 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 action a <a href="package-summary.html#NonInterference">
+ * non-interfering</a> action to perform on the elements
+ * @see #forEach(Consumer)
+ */
+ void forEachOrdered(Consumer<? super T> action);
+
+ /**
+ * Returns 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();
+
+ /**
+ * Returns 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>.
+ *
+ * @param <A> the element type of the resulting array
+ * @param generator a function which produces a new array of the desired
+ * type and the provided length
+ * @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
+ */
+ <A> A[] toArray(IntFunction<A[]> generator);
+
+ /**
+ * 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 returns the reduced value. This is equivalent
+ * to:
+ * <pre>{@code
+ * T result = identity;
+ * for (T 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 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>.
+ *
+ * @apiNote Sum, min, max, average, and string concatenation are all special
+ * cases of reduction. Summing a stream of numbers can be expressed as:
+ *
+ * <pre>{@code
+ * Integer sum = integers.reduce(0, (a, b) -> a+b);
+ * }</pre>
+ *
+ * or more compactly:
+ *
+ * <pre>{@code
+ * 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.
+ *
+ * @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
+ * @return the result of the reduction
+ */
+ T reduce(T identity, BinaryOperator<T> accumulator);
+
+ /**
+ * 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 returns an {@code Optional} describing the reduced value,
+ * if any. This is equivalent to:
+ * <pre>{@code
+ * boolean foundAny = false;
+ * T result = null;
+ * for (T element : this stream) {
+ * if (!foundAny) {
+ * foundAny = true;
+ * result = element;
+ * }
+ * else
+ * result = accumulator.apply(result, element);
+ * }
+ * return foundAny ? Optional.of(result) : Optional.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 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
+ * @return the result of the reduction
+ * @see #reduce(Object, BinaryOperator)
+ * @see #min(java.util.Comparator)
+ * @see #max(java.util.Comparator)
+ */
+ Optional<T> reduce(BinaryOperator<T> accumulator);
+
+ /**
+ * 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>{@code
+ * U result = identity;
+ * for (T 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 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>{@code
+ * 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.
+ *
+ * @param <U> The type of the result
+ * @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
+ * @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
+ * @return the result of the reduction
+ * @see #reduce(BinaryOperator)
+ * @see #reduce(Object, BinaryOperator)
+ */
+ <U> U reduce(U identity,
+ BiFunction<U, ? super T, U> accumulator,
+ BinaryOperator<U> combiner);
+
+ /**
+ * 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>{@code
+ * R result = resultFactory.get();
+ * for (T element : this stream)
+ * accumulator.accept(result, element);
+ * return result;
+ * }</pre>
+ *
+ * <p>Like {@link #reduce(Object, BinaryOperator)}, {@code collect} operations
+ * can be parallelized without requiring additional synchronization.
+ *
+ * <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:
+ * <pre>{@code
+ * List<String> asList = stringStream.collect(ArrayList::new, ArrayList::add, ArrayList::addAll);
+ * }</pre>
+ *
+ * <p>The following will take a stream of strings and concatenates them into a
+ * single string:
+ * <pre>{@code
+ * String concat = stringStream.collect(StringBuilder::new, StringBuilder::append,
+ * StringBuilder::append)
+ * .toString();
+ * }</pre>
+ *
+ * @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 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
+ * @return the result of the reduction
+ */
+ <R> R collect(Supplier<R> resultFactory,
+ BiConsumer<R, ? super T> accumulator,
+ BiConsumer<R, R> combiner);
+
+ /**
+ * 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>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:
+ * <pre>{@code
+ * List<String> asList = stringStream.collect(Collectors.toList());
+ * }</pre>
+ *
+ * <p>The following will classify {@code Person} objects by city:
+ * <pre>{@code
+ * Map<String, Collection<Person>> peopleByCity
+ * = personStream.collect(Collectors.groupBy(Person::getCity));
+ * }</pre>
+ *
+ * <p>The following will classify {@code Person} objects by state and city,
+ * cascading two {@code Collector}s together:
+ * <pre>{@code
+ * Map<String, Map<String, Collection<Person>>> peopleByStateAndCity
+ * = personStream.collect(Collectors.groupBy(Person::getState,
+ * Collectors.groupBy(Person::getCity)));
+ * }</pre>
+ *
+ * @param <R> the type of the result
+ * @param collector the {@code Collector} describing the reduction
+ * @return the result of the reduction
+ * @see #collect(Supplier, BiConsumer, BiConsumer)
+ * @see Collectors
+ */
+ <R> R collect(Collector<? super T, R> collector);
+
+ /**
+ * Returns the minimum 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 minimum element of this stream,
+ * or an empty {@code Optional} if the stream is empty
+ */
+ Optional<T> min(Comparator<? super T> comparator);
+
+ /**
+ * Returns the maximum 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 maximum element of this stream,
+ * or an empty {@code Optional} if the stream is empty
+ */
+ Optional<T> max(Comparator<? super T> comparator);
+
+ /**
+ * 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>{@code
+ * return mapToLong(e -> 1L).sum();
+ * }</pre>
+ *
+ * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+ *
+ * @return the count of elements in this stream
+ */
+ long count();
+
+ /**
+ * 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 {@code true} if any elements of the stream match the provided
+ * predicate otherwise {@code false}
+ */
+ boolean anyMatch(Predicate<? super T> 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 {@code true} if all elements of the stream match the provided
+ * predicate otherwise {@code false}
+ */
+ boolean allMatch(Predicate<? super T> 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 {@code true} if no elements of the stream match the provided
+ * predicate otherwise {@code false}
+ */
+ boolean noneMatch(Predicate<? super T> predicate);
+
+ /**
+ * 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. If the stream has no encounter order, than any element may be
+ * returned.
+ *
+ * <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
+ * @throws NullPointerException if the element selected is null
+ */
+ Optional<T> findFirst();
+
+ /**
+ * 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>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
+ * @throws NullPointerException if the element selected is null
+ * @see #findFirst()
+ */
+ Optional<T> findAny();
+}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/util/stream/package-info.java Wed Apr 17 14:39:04 2013 -0400
@@ -0,0 +1,566 @@
+/*
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+ * <h1>java.util.stream</h1>
+ *
+ * Classes to support functional-style operations on streams of values, as in the following:
+ *
+ * <pre>{@code
+ * int sumOfWeights = blocks.stream().filter(b -> b.getColor() == RED)
+ * .mapToInt(b -> b.getWeight())
+ * .sum();
+ * }</pre>
+ *
+ * <p>Here we use {@code blocks}, which might be a {@code Collection}, as a source for a stream,
+ * and then perform a filter-map-reduce ({@code sum()} is an example of a <a href="package-summary.html#Reduction">reduction</a>
+ * operation) on the stream to obtain the sum of the weights of the red blocks.
+ *
+ * <p>The key abstraction used in this approach is {@link java.util.stream.Stream}, as well as its primitive
+ * specializations {@link java.util.stream.IntStream}, {@link java.util.stream.LongStream},
+ * and {@link java.util.stream.DoubleStream}. Streams differ from Collections in several ways:
+ *
+ * <ul>
+ * <li>No storage. A stream is not a data structure that stores elements; instead, they
+ * carry values from a source (which could be a data structure, a generator, an IO channel, etc)
+ * through a pipeline of computational operations.</li>
+ * <li>Functional in nature. An operation on a stream produces a result, but does not modify
+ * its underlying data source. For example, filtering a {@code Stream} produces a new {@code Stream},
+ * rather than removing elements from the underlying source.</li>
+ * <li>Laziness-seeking. Many stream operations, such as filtering, mapping, or duplicate removal,
+ * can be implemented lazily, exposing opportunities for optimization. (For example, "find the first
+ * {@code String} matching a pattern" need not examine all the input strings.) Stream operations
+ * are divided into intermediate ({@code Stream}-producing) operations and terminal (value-producing)
+ * operations; all intermediate operations are lazy.</li>
+ * <li>Possibly unbounded. While collections have a finite size, streams need not. Operations
+ * such as {@code limit(n)} or {@code findFirst()} can allow computations on infinite streams
+ * to complete in finite time.</li>
+ * </ul>
+ *
+ * <h2><a name="StreamPipelines">Stream pipelines</a></h2>
+ *
+ * <p>Streams are used to create <em>pipelines</em> of <a href="package-summary.html#StreamOps">operations</a>. A
+ * complete stream pipeline has several components: a source (which may be a {@code Collection},
+ * an array, a generator function, or an IO channel); zero or more <em>intermediate operations</em>
+ * such as {@code Stream.filter} or {@code Stream.map}; and a <em>terminal operation</em> such
+ * as {@code Stream.forEach} or {@code java.util.stream.Stream.reduce}. Stream operations may take as parameters
+ * <em>function values</em> (which are often lambda expressions, but could be method references
+ * or objects) which parameterize the behavior of the operation, such as a {@code Predicate}
+ * passed to the {@code Stream#filter} method.
+ *
+ * <p>Intermediate operations return a new {@code Stream}. They are lazy; executing an
+ * intermediate operation such as {@link java.util.stream.Stream#filter Stream.filter} does
+ * not actually perform any filtering, instead creating a new {@code Stream} that, when
+ * traversed, contains the elements of the initial {@code Stream} that match the
+ * given {@code Predicate}. Consuming elements from the stream source does not
+ * begin until the terminal operation is executed.
+ *
+ * <p>Terminal operations consume the {@code Stream} and produce a result or a side-effect.
+ * After a terminal operation is performed, the stream can no longer be used and you must
+ * return to the data source, or select a new data source, to get a new stream. For example,
+ * obtaining the sum of weights of all red blocks, and then of all blue blocks, requires a
+ * filter-map-reduce on two different streams:
+ * <pre>{@code
+ * int sumOfRedWeights = blocks.stream().filter(b -> b.getColor() == RED)
+ * .mapToInt(b -> b.getWeight())
+ * .sum();
+ * int sumOfBlueWeights = blocks.stream().filter(b -> b.getColor() == BLUE)
+ * .mapToInt(b -> b.getWeight())
+ * .sum();
+ * }</pre>
+ *
+ * <p>However, there are other techniques that allow you to obtain both results in a single
+ * pass if multiple traversal is impractical or inefficient. TODO provide link
+ *
+ * <h3><a name="StreamOps">Stream operations</a></h3>
+ *
+ * <p>Intermediate stream operation (such as {@code filter} or {@code sorted}) always produce a
+ * new {@code Stream}, and are always<em>lazy</em>. Executing a lazy operations does not
+ * trigger processing of the stream contents; all processing is deferred until the terminal
+ * operation commences. Processing streams lazily allows for significant efficiencies; in a
+ * pipeline such as the filter-map-sum example above, filtering, mapping, and addition can be
+ * fused into a single pass, with minimal intermediate state. Laziness also enables us to avoid
+ * examining all the data when it is not necessary; for operations such as "find the first
+ * string longer than 1000 characters", one need not examine all the input strings, just enough
+ * to find one that has the desired characteristics. (This behavior becomes even more important
+ * when the input stream is infinite and not merely large.)
+ *
+ * <p>Intermediate operations are further divided into <em>stateless</em> and <em>stateful</em>
+ * operations. Stateless operations retain no state from previously seen values when processing
+ * a new value; examples of stateless intermediate operations include {@code filter} and
+ * {@code map}. Stateful operations may incorporate state from previously seen elements in
+ * processing new values; examples of stateful intermediate operations include {@code distinct}
+ * and {@code sorted}. Stateful operations may need to process the entire input before
+ * producing a result; for example, one cannot produce any results from sorting a stream until
+ * one has seen all elements of the stream. As a result, under parallel computation, some
+ * pipelines containing stateful intermediate operations have to be executed in multiple passes.
+ * Pipelines containing exclusively stateless intermediate operations can be processed in a
+ * single pass, whether sequential or parallel.
+ *
+ * <p>Further, some operations are deemed <em>short-circuiting</em> operations. An intermediate
+ * operation is short-circuiting if, when presented with infinite input, it may produce a
+ * finite stream as a result. A terminal operation is short-circuiting if, when presented with
+ * infinite input, it may terminate in finite time. (Having a short-circuiting operation is a
+ * necessary, but not sufficient, condition for the processing of an infinite stream to
+ * terminate normally in finite time.)
+ *
+ * Terminal operations (such as {@code forEach} or {@code findFirst}) are always eager
+ * (they execute completely before returning), and produce a non-{@code Stream} result, such
+ * as a primitive value or a {@code Collection}, or have side-effects.
+ *
+ * <h3>Parallelism</h3>
+ *
+ * <p>By recasting aggregate operations as a pipeline of operations on a stream of values, many
+ * aggregate operations can be more easily parallelized. A {@code Stream} can execute either
+ * in serial or in parallel. When streams are created, they are either created as sequential
+ * or parallel streams; the parallel-ness of streams can also be switched by the
+ * {@link java.util.stream Stream#sequential()} and {@link java.util.stream.Stream#parallel()}
+ * operations. The {@code Stream} implementations in the JDK create serial streams unless
+ * parallelism is explicitly requested. For example, {@code Collection} has methods
+ * {@link java.util.Collection#stream} and {@link java.util.Collection#parallelStream},
+ * which produce sequential and parallel streams respectively; other stream-bearing methods
+ * such as {@link java.util.stream.Streams#intRange(int, int)} produce sequential
+ * streams but these can be efficiently parallelized by calling {@code parallel()} on the
+ * result. The set of operations on serial and parallel streams is identical. To execute the
+ * "sum of weights of blocks" query in parallel, we would do:
+ *
+ * <pre>{@code
+ * int sumOfWeights = blocks.parallelStream().filter(b -> b.getColor() == RED)
+ * .mapToInt(b -> b.getWeight())
+ * .sum();
+ * }</pre>
+ *
+ * <p>The only difference between the serial and parallel versions of this example code is
+ * the creation of the initial {@code Stream}. Whether a {@code Stream} will execute in serial
+ * or parallel can be determined by the {@code Stream#isParallel} method. When the terminal
+ * operation is initiated, the entire stream pipeline is either executed sequentially or in
+ * parallel, determined by the last operation that affected the stream's serial-parallel
+ * orientation (which could be the stream source, or the {@code sequential()} or
+ * {@code parallel()} methods.)
+ *
+ * <p>In order for the results of parallel operations to be deterministic and consistent with
+ * their serial equivalent, the function values passed into the various stream operations should
+ * be <a href="#NonInteference"><em>stateless</em></a>.
+ *
+ * <h3><a name="Ordering">Ordering</a></h3>
+ *
+ * <p>Streams may or may not have an <em>encounter order</em>. An encounter
+ * order specifies the order in which elements are provided by the stream to the
+ * operations pipeline. Whether or not there is an encounter order 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()}, and others may render an
+ * ordered stream unordered (such as {@link java.util.stream.Stream#unordered()}).
+ * Some terminal operations may ignore encounter order, such as
+ * {@link java.util.stream.Stream#forEach}.
+ *
+ * <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 of the six permutations of the values {@code [2, 4, 6]} would
+ * be a valid result. Many operations can still be efficiently parallelized even
+ * under ordering constraints.
+ *
+ * <p>For sequential streams, ordering is only relevant to the determinism
+ * of operations performed repeatedly on the same source. (An {@code ArrayList}
+ * is constrained to iterate elements in order; a {@code HashSet} is not, and
+ * repeated iteration might produce a different order.)
+ *
+ * <p>For parallel streams, relaxing the ordering constraint can enable
+ * optimized implementation for some operations. For example, duplicate
+ * filtration on an ordered stream must completely process the first partition
+ * before it can return any elements from a subsequent partition, even if those
+ * elements are available earlier. On the other hand, without the constraint of
+ * ordering, duplicate filtration can be done more efficiently by using
+ * a shared {@code ConcurrentHashSet}. There will be cases where the stream
+ * is structurally ordered (the source is ordered and the intermediate
+ * operations are order-preserving), but the user does not particularly care
+ * about the encounter order. In some cases, explicitly de-ordering the stream
+ * with the {@link java.util.stream.Stream#unordered()} method may result in
+ * improved parallel performance for some stateful or terminal operations.
+ *
+ * <h3><a name="Non-Interference">Non-interference</a></h3>
+ *
+ * The {@code java.util.stream} package enables you to execute possibly-parallel
+ * bulk-data operations over a variety of data sources, including even non-thread-safe
+ * collections such as {@code ArrayList}. This is possible only if we can
+ * prevent <em>interference</em> with the data source during the execution of a
+ * stream pipeline. (Execution begins when the terminal operation is invoked, and ends
+ * when the terminal operation completes.) For most data sources, preventing interference
+ * means ensuring that the data source is <em>not modified at all</em> during the execution
+ * of the stream pipeline. (Some data sources, such as concurrent collections, are
+ * specifically designed to handle concurrent modification.)
+ *
+ * <p>Accordingly, lambda expressions (or other objects implementing the appropriate functional
+ * interface) passed to stream methods should never modify the stream's data source. An
+ * implementation is said to <em>interfere</em> with the data source if it modifies, or causes
+ * to be modified, the stream's data source. The need for non-interference applies to all
+ * pipelines, not just parallel ones. Unless the stream source is concurrent, modifying a
+ * stream's data source during execution of a stream pipeline can cause exceptions, incorrect
+ * answers, or nonconformant results.
+ *
+ * <p>Further, results may be nondeterministic or incorrect if the lambda expressions passed to
+ * stream operations are <em>stateful</em>. A stateful lambda (or other object implementing the
+ * appropriate functional interface) is one whose result depends on any state which might change
+ * during the execution of the stream pipeline. An example of a stateful lambda is:
+ * <pre>{@code
+ * Set<Integer> seen = Collections.synchronizedSet(new HashSet<>());
+ * stream.parallel().map(e -> { if (seen.add(e)) return 0; else return e; })...
+ * }</pre>
+ * Here, if the mapping operation is performed in parallel, the results for the same input
+ * could vary from run to run, due to thread scheduling differences, whereas, with a stateless
+ * lambda expression the results would always be the same.
+ *
+ * <h3>Side-effects</h3>
+ *
+ * <h2><a name="Reduction">Reduction operations</a></h2>
+ *
+ * A <em>reduction</em> operation takes a stream of elements and processes them in a way
+ * that reduces to a single value or summary description, such as finding the sum or maximum
+ * of a set of numbers. (In more complex scenarios, the reduction operation might need to
+ * extract data from the elements before reducing that data to a single value, such as
+ * finding the sum of weights of a set of blocks. This would require extracting the weight
+ * from each block before summing up the weights.)
+ *
+ * <p>Of course, such operations can be readily implemented as simple sequential loops, as in:
+ * <pre>{@code
+ * int sum = 0;
+ * for (int x : numbers) {
+ * sum += x;
+ * }
+ * }</pre>
+ * However, there may be a significant advantage to preferring a {@link java.util.stream.Stream#reduce reduce operation}
+ * over a mutative accumulation such as the above -- a properly constructed reduce operation is
+ * inherently parallelizable so long as the
+ * {@link java.util.function.BinaryOperator reduction operaterator}
+ * has the right characteristics. Specifically the operator must be
+ * <a href="#Associativity">associative</a>. For example, given a
+ * stream of numbers for which we want to find the sum, we can write:
+ * <pre>{@code
+ * int sum = numbers.reduce(0, (x,y) -> x+y);
+ * }</pre>
+ * or more succinctly:
+ * <pre>{@code
+ * int sum = numbers.reduce(0, Integer::sum);
+ * }</pre>
+ *
+ * <p>(The primitive specializations of {@link java.util.stream.Stream}, such as
+ * {@link java.util.stream.IntStream}, even have convenience methods for common reductions,
+ * such as {@link java.util.stream.IntStream#sum() sum} and {@link java.util.stream.IntStream#max() max},
+ * which are implemented as simple wrappers around reduce.)
+ *
+ * <p>Reduction parallellizes well since the implementation of {@code reduce} can operate on
+ * subsets of the stream in parallel, and then combine the intermediate results to get the final
+ * correct answer. Even if you were to use a parallelizable form of the
+ * {@link java.util.stream.Stream#forEach(Consumer) forEach()} method
+ * in place of the original for-each loop above, you would still have to provide thread-safe
+ * updates to the shared accumulating variable {@code sum}, and the required synchronization
+ * would likely eliminate any performance gain from parallelism. Using a {@code reduce} method
+ * instead removes all of the burden of parallelizing the reduction operation, and the library
+ * can provide an efficient parallel implementation with no additional synchronization needed.
+ *
+ * <p>The "blocks" examples shown earlier shows how reduction combines with other operations
+ * to replace for loops with bulk operations. If {@code blocks} is a collection of {@code Block}
+ * objects, which have a {@code getWeight} method, we can find the heaviest block with:
+ * <pre>{@code
+ * OptionalInt heaviest = blocks.stream()
+ * .mapToInt(Block::getWeight)
+ * .reduce(Integer::max);
+ * }</pre>
+ *
+ * <p>In its more general form, a {@code reduce} operation on elements of type {@code <T>}
+ * yielding a result of type {@code <U>} requires three parameters:
+ * <pre>{@code
+ * <U> U reduce(U identity,
+ * BiFunction<U, ? super T, U> accumlator,
+ * BinaryOperator<U> combiner);
+ * }</pre>
+ * Here, the <em>identity</em> element is both an initial seed for the reduction, and a default
+ * result if there are no elements. The <em>accumulator</em> function takes a partial result and
+ * the next element, and produce a new partial result. The <em>combiner</em> function combines
+ * the partial results of two accumulators to produce a new partial result, and eventually the
+ * final result.
+ *
+ * <p>This form is a generalization of the two-argument form, and is also a generalization of
+ * the map-reduce construct illustrated above. If we wanted to re-cast the simple {@code sum}
+ * example using the more general form, {@code 0} would be the identity element, while
+ * {@code Integer::sum} would be both the accumulator and combiner. For the sum-of-weights
+ * example, this could be re-cast as:
+ * <pre>{@code
+ * int sumOfWeights = blocks.stream().reduce(0,
+ * (sum, b) -> sum + b.getWeight())
+ * Integer::sum);
+ * }</pre>
+ * though the map-reduce form is more readable and generally preferable. The generalized form
+ * is provided for cases where significant work can be optimized away by combining mapping and
+ * reducing into a single function.
+ *
+ * <p>More formally, the {@code identity} value must be an <em>identity</em> for the combiner
+ * function. This means that for all {@code u}, {@code combiner.apply(identity, u)} is equal
+ * to {@code u}. Additionally, the {@code combiner} function must be
+ * <a href="#Associativity">associative</a> and must be compatible with the {@code accumulator}
+ * function; for all {@code u} and {@code t}, the following must hold:
+ * <pre>{@code
+ * combiner.apply(u, accumulator.apply(identity, t)) == accumulator.apply(u, t)
+ * }</pre>
+ *
+ * <h3><a name="MutableReduction">Mutable Reduction</a></h3>
+ *
+ * A <em>mutable</em> reduction operation is similar to an ordinary reduction, in that it reduces
+ * a stream of values to a single value, but instead of producing a distinct single-valued result, it
+ * mutates a general <em>result container</em>, such as a {@code Collection} or {@code StringBuilder},
+ * as it processes the elements in the stream.
+ *
+ * <p>For example, if we wanted to take a stream of strings and concatenate them into a single
+ * long string, we <em>could</em> achieve this with ordinary reduction:
+ * <pre>{@code
+ * String concatenated = strings.reduce("", String::concat)
+ * }</pre>
+ *
+ * We would get the desired result, and it would even work in parallel. However, we might not
+ * be happy about the performance! Such an implementation would do a great deal of string
+ * copying, and the run time would be <em>O(n^2)</em> in the number of elements. A more
+ * performant approach would be to accumulate the results into a {@link java.lang.StringBuilder}, which
+ * is a mutable container for accumulating strings. We can use the same technique to
+ * parallelize mutable reduction as we do with ordinary reduction.
+ *
+ * <p>The mutable reduction operation is called {@link java.util.stream.Stream#collect(Collector) collect()}, as it
+ * collects together the desired results into a result container such as {@code StringBuilder}.
+ * A {@code collect} operation requires three things: a factory function which will construct
+ * new instances of the result container, an accumulating function that will update a result
+ * container by incorporating a new element, and a combining function that can take two
+ * result containers and merge their contents. The form of this is very similar to the general
+ * form of ordinary reduction:
+ * <pre>{@code
+ * <R> R collect(Supplier<R> resultFactory,
+ * BiConsumer<R, ? super T> accumulator,
+ * BiConsumer<R, R> combiner);
+ * }</pre>
+ * As with {@code reduce()}, the benefit of expressing {@code collect} in this abstract way is
+ * that it is directly amenable to parallelization: we can accumulate partial results in parallel
+ * and then combine them. For example, to collect the String representations of the elements
+ * in a stream into an {@code ArrayList}, we could write the obvious sequential for-each form:
+ * <pre>{@code
+ * ArrayList<String> strings = new ArrayList<>();
+ * for (T element : stream) {
+ * strings.add(element.toString());
+ * }
+ * }</pre>
+ * Or we could use a parallelizable collect form:
+ * <pre>{@code
+ * ArrayList<String> strings = stream.collect(() -> new ArrayList<>(),
+ * (c, e) -> c.add(e.toString()),
+ * (c1, c2) -> c1.addAll(c2));
+ * }</pre>
+ * or, noting that we have buried a mapping operation inside the accumulator function, more
+ * succinctly as:
+ * <pre>{@code
+ * ArrayList<String> strings = stream.map(Object::toString)
+ * .collect(ArrayList::new, ArrayList::add, ArrayList::addAll);
+ * }</pre>
+ * Here, our supplier is just the {@link java.util.ArrayList#ArrayList() ArrayList constructor}, the
+ * accumulator adds the stringified element to an {@code ArrayList}, and the combiner simply
+ * uses {@link java.util.ArrayList#addAll addAll} to copy the strings from one container into the other.
+ *
+ * <p>As with the regular reduction operation, the ability to parallelize only comes if an
+ * <a href="package-summary.html#Associativity">associativity</a> condition is met. The {@code combiner} is associative
+ * if for result containers {@code r1}, {@code r2}, and {@code r3}:
+ * <pre>{@code
+ * combiner.accept(r1, r2);
+ * combiner.accept(r1, r3);
+ * }</pre>
+ * is equivalent to
+ * <pre>{@code
+ * combiner.accept(r2, r3);
+ * combiner.accept(r1, r2);
+ * }</pre>
+ * where equivalence means that {@code r1} is left in the same state (according to the meaning
+ * of {@link java.lang.Object#equals equals} for the element types). Similarly, the {@code resultFactory}
+ * must act as an <em>identity</em> with respect to the {@code combiner} so that for any result
+ * container {@code r}:
+ * <pre>{@code
+ * combiner.accept(r, resultFactory.get());
+ * }</pre>
+ * does not modify the state of {@code r} (again according to the meaning of
+ * {@link java.lang.Object#equals equals}). Finally, the {@code accumulator} and {@code combiner} must be
+ * compatible such that for a result container {@code r} and element {@code t}:
+ * <pre>{@code
+ * r2 = resultFactory.get();
+ * accumulator.accept(r2, t);
+ * combiner.accept(r, r2);
+ * }</pre>
+ * is equivalent to:
+ * <pre>{@code
+ * accumulator.accept(r,t);
+ * }</pre>
+ * where equivalence means that {@code r} is left in the same state (again according to the
+ * meaning of {@link java.lang.Object#equals equals}).
+ *
+ * <p> The three aspects of {@code collect}: supplier, accumulator, and combiner, are often very
+ * tightly coupled, and it is convenient to introduce the notion of a {@link java.util.stream.Collector} as
+ * being an object that embodies all three aspects. There is a {@link java.util.stream.Stream#collect(Collector) collect}
+ * method that simply takes a {@code Collector} and returns the resulting container.
+ * The above example for collecting strings into a {@code List} can be rewritten using a
+ * standard {@code Collector} as:
+ * <pre>{@code
+ * ArrayList<String> strings = stream.map(Object::toString)
+ * .collect(Collectors.toList());
+ * }</pre>
+ *
+ * <h3><a name="ConcurrentReduction">Reduction, Concurrency, and Ordering</a></h3>
+ *
+ * With some complex reduction operations, for example a collect that produces a
+ * {@code Map}, such as:
+ * <pre>{@code
+ * Map<Buyer, List<Transaction>> salesByBuyer
+ * = txns.parallelStream()
+ * .collect(Collectors.groupingBy(Transaction::getBuyer));
+ * }</pre>
+ * (where {@link java.util.stream.Collectors#groupingBy} is a utility function
+ * that returns a {@link java.util.stream.Collector} for grouping sets of elements based on some key)
+ * it may actually be counterproductive to perform the operation in parallel.
+ * This is because the combining step (merging one {@code Map} into another by key)
+ * can be expensive for some {@code Map} implementations.
+ *
+ * <p>Suppose, however, that the result container used in this reduction
+ * was a concurrently modifiable collection -- such as a
+ * {@link java.util.concurrent.ConcurrentHashMap ConcurrentHashMap}. In that case,
+ * the parallel invocations of the accumulator could actually deposit their results
+ * concurrently into the same shared result container, eliminating the need for the combiner to
+ * merge distinct result containers. This potentially provides a boost
+ * to the parallel execution performance. We call this a <em>concurrent</em> reduction.
+ *
+ * <p>A {@link java.util.stream.Collector} that supports concurrent reduction is marked with the
+ * {@link java.util.stream.Collector.Characteristics#CONCURRENT} characteristic.
+ * Having a concurrent collector is a necessary condition for performing a
+ * concurrent reduction, but that alone is not sufficient. If you imagine multiple
+ * accumulators depositing results into a shared container, the order in which
+ * results are deposited is non-deterministic. Consequently, a concurrent reduction
+ * is only possible if ordering is not important for the stream being processed.
+ * The {@link java.util.stream.Stream#collect(Collector)}
+ * implementation will only perform a concurrent reduction if
+ * <ul>
+ * <li>The stream is parallel;</li>
+ * <li>The collector has the
+ * {@link java.util.stream.Collector.Characteristics#CONCURRENT} characteristic,
+ * and;</li>
+ * <li>Either the stream is unordered, or the collector has the
+ * {@link java.util.stream.Collector.Characteristics#UNORDERED} characteristic.
+ * </ul>
+ * For example:
+ * <pre>{@code
+ * Map<Buyer, List<Transaction>> salesByBuyer
+ * = txns.parallelStream()
+ * .unordered()
+ * .collect(groupingByConcurrent(Transaction::getBuyer));
+ * }</pre>
+ * (where {@link java.util.stream.Collectors#groupingByConcurrent} is the concurrent companion
+ * to {@code groupingBy}).
+ *
+ * <p>Note that if it is important that the elements for a given key appear in the
+ * order they appear in the source, then we cannot use a concurrent reduction,
+ * as ordering is one of the casualties of concurrent insertion. We would then
+ * be constrained to implement either a sequential reduction or a merge-based
+ * parallel reduction.
+ *
+ * <h2><a name="Associativity">Associativity</a></h2>
+ *
+ * An operator or function {@code op} is <em>associative</em> if the following holds:
+ * <pre>{@code
+ * (a op b) op c == a op (b op c)
+ * }</pre>
+ * The importance of this to parallel evaluation can be seen if we expand this to four terms:
+ * <pre>{@code
+ * a op b op c op d == (a op b) op (c op d)
+ * }</pre>
+ * So we can evaluate {@code (a op b)} in parallel with {@code (c op d)} and then invoke {@code op} on
+ * the results.
+ * TODO what does associative mean for mutative combining functions?
+ * FIXME: we described mutative associativity above.
+ *
+ * <h2><a name="StreamSources">Stream sources</a></h2>
+ * TODO where does this section go?
+ *
+ * XXX - change to section to stream construction gradually introducing more
+ * complex ways to construct
+ * - construction from Collection
+ * - construction from Iterator
+ * - construction from array
+ * - construction from generators
+ * - construction from spliterator
+ *
+ * XXX - the following is quite low-level but important aspect of stream constriction
+ *
+ * <p>A pipeline is initially constructed from a spliterator (see {@link java.util.Spliterator}) supplied by a stream source.
+ * The spliterator covers elements of the source and provides element traversal operations
+ * for a possibly-parallel computation. See methods on {@link java.util.stream.Streams} for construction
+ * of pipelines using spliterators.
+ *
+ * <p>A source may directly supply a spliterator. If so, the spliterator is traversed, split, or queried
+ * for estimated size after, and never before, the terminal operation commences. It is strongly recommended
+ * that the spliterator report a characteristic of {@code IMMUTABLE} or {@code CONCURRENT}, or be
+ * <em>late-binding</em> and not bind to the elements it covers until traversed, split or queried for
+ * estimated size.
+ *
+ * <p>If a source cannot directly supply a recommended spliterator then it may indirectly supply a spliterator
+ * using a {@code Supplier}. The spliterator is obtained from the supplier after, and never before, the terminal
+ * operation of the stream pipeline commences.
+ *
+ * <p>Such requirements significantly reduce the scope of potential interference to the interval starting
+ * with the commencing of the terminal operation and ending with the producing a result or side-effect. See
+ * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
+ * more details.
+ *
+ * XXX - move the following to the non-interference section
+ *
+ * <p>A source can be modified before the terminal operation commences and those modifications will be reflected in
+ * the covered elements. Afterwards, and depending on the properties of the source, further modifications
+ * might not be reflected and the throwing of a {@code ConcurrentModificationException} may occur.
+ *
+ * <p>For example, consider the following code:
+ * <pre>{@code
+ * List<String> l = new ArrayList(Arrays.asList("one", "two"));
+ * Stream<String> sl = l.stream();
+ * l.add("three");
+ * String s = sl.collect(toStringJoiner(" ")).toString();
+ * }</pre>
+ * First a list is created consisting of two strings: "one"; and "two". Then a stream is created from that list.
+ * Next the list is modified by adding a third string: "three". Finally the elements of the stream are collected
+ * and joined together. Since the list was modified before the terminal {@code collect} operation commenced
+ * the result will be a string of "one two three". However, if the list is modified after the terminal operation
+ * commences, as in:
+ * <pre>{@code
+ * List<String> l = new ArrayList(Arrays.asList("one", "two"));
+ * Stream<String> sl = l.stream();
+ * String s = sl.peek(s -> l.add("BAD LAMBDA")).collect(toStringJoiner(" ")).toString();
+ * }</pre>
+ * then a {@code ConcurrentModificationException} will be thrown since the {@code peek} operation will attempt
+ * to add the string "BAD LAMBDA" to the list after the terminal operation has commenced.
+ */
+
+package java.util.stream;