OpenJDK / lambda / lambda / jdk
changeset 8343:2a78d8f1fec1
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>
| author | briangoetz |
|---|---|
| date | Wed, 17 Apr 2013 14:39:04 -0400 |
| parents | 3ca33647db95 |
| children | 98a7bb7baa76 |
| files | src/share/classes/java/util/stream/BaseStream.java src/share/classes/java/util/stream/CloseableStream.java src/share/classes/java/util/stream/Collector.java src/share/classes/java/util/stream/DelegatingStream.java src/share/classes/java/util/stream/DoubleStream.java src/share/classes/java/util/stream/IntStream.java src/share/classes/java/util/stream/LongStream.java src/share/classes/java/util/stream/Stream.java src/share/classes/java/util/stream/package-info.java |
| diffstat | 9 files changed, 3985 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/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/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/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/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/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/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/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/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/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;