Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance. Project price only 1 $
You can buy this project and download/modify it how often you want.
/*
* Copyright (c) 2012, 2021, 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.nio.file.Files;
import java.nio.file.Path;
import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
import java.util.function.BiConsumer;
import java.util.function.BiFunction;
import java.util.function.BinaryOperator;
import java.util.function.Consumer;
import java.util.function.DoubleConsumer;
import java.util.function.Function;
import java.util.function.IntConsumer;
import java.util.function.IntFunction;
import java.util.function.LongConsumer;
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;
import java.util.function.UnaryOperator;
/**
* A sequence of elements supporting sequential and parallel aggregate
* operations. The following example illustrates an aggregate operation using
* {@link Stream} and {@link IntStream}:
*
*
{@code
* int sum = widgets.stream()
* .filter(w -> w.getColor() == RED)
* .mapToInt(w -> w.getWeight())
* .sum();
* }
*
* In this example, {@code widgets} is a {@code Collection}. We create
* a stream of {@code Widget} objects via {@link Collection#stream Collection.stream()},
* filter it to produce a stream containing only the red widgets, and then
* transform it into a stream of {@code int} values representing the weight of
* each red widget. Then this stream is summed to produce a total weight.
*
*
In addition to {@code Stream}, which is a stream of object references,
* there are primitive specializations for {@link IntStream}, {@link LongStream},
* and {@link DoubleStream}, all of which are referred to as "streams" and
* conform to the characteristics and restrictions described here.
*
*
To perform a computation, stream
* operations are composed into a
* stream pipeline. A stream pipeline consists of a source (which
* might be an array, a collection, a generator function, an I/O channel,
* etc), zero or more intermediate operations (which transform a
* stream into another stream, such as {@link Stream#filter(Predicate)}), and a
* terminal operation (which produces a result or side-effect, such
* as {@link Stream#count()} or {@link Stream#forEach(Consumer)}).
* Streams are lazy; computation on the source data is only performed when the
* terminal operation is initiated, and source elements are consumed only
* as needed.
*
*
A stream implementation is permitted significant latitude in optimizing
* the computation of the result. For example, a stream implementation is free
* to elide operations (or entire stages) from a stream pipeline -- and
* therefore elide invocation of behavioral parameters -- if it can prove that
* it would not affect the result of the computation. This means that
* side-effects of behavioral parameters may not always be executed and should
* not be relied upon, unless otherwise specified (such as by the terminal
* operations {@code forEach} and {@code forEachOrdered}). (For a specific
* example of such an optimization, see the API note documented on the
* {@link #count} operation. For more detail, see the
* side-effects section of the
* stream package documentation.)
*
*
Collections and streams, while bearing some superficial similarities,
* have different goals. Collections are primarily concerned with the efficient
* management of, and access to, their elements. By contrast, streams do not
* provide a means to directly access or manipulate their elements, and are
* instead concerned with declaratively describing their source and the
* computational operations which will be performed in aggregate on that source.
* However, if the provided stream operations do not offer the desired
* functionality, the {@link #iterator()} and {@link #spliterator()} operations
* can be used to perform a controlled traversal.
*
*
A stream pipeline, like the "widgets" example above, can be viewed as
* a query on the stream source. Unless the source was explicitly
* designed for concurrent modification (such as a {@link ConcurrentHashMap}),
* unpredictable or erroneous behavior may result from modifying the stream
* source while it is being queried.
*
*
Most stream operations accept parameters that describe user-specified
* behavior, such as the lambda expression {@code w -> w.getWeight()} passed to
* {@code mapToInt} in the example above. To preserve correct behavior,
* these behavioral parameters:
*
*
must be non-interfering
* (they do not modify the stream source); and
*
in most cases must be stateless
* (their result should not depend on any state that might change during execution
* of the stream pipeline).
*
*
*
Such parameters are always instances of a
* functional interface such
* as {@link java.util.function.Function}, and are often lambda expressions or
* method references. Unless otherwise specified these parameters must be
* non-null.
*
*
A stream should be operated on (invoking an intermediate or terminal stream
* operation) only once. This rules out, for example, "forked" streams, where
* the same source feeds two or more pipelines, or multiple traversals of the
* same stream. A stream implementation may throw {@link IllegalStateException}
* if it detects that the stream is being reused. However, since some stream
* operations may return their receiver rather than a new stream object, it may
* not be possible to detect reuse in all cases.
*
*
Streams have a {@link #close()} method and implement {@link AutoCloseable}.
* Operating on a stream after it has been closed will throw {@link IllegalStateException}.
* Most stream instances do not actually need to be closed after use, as they
* are backed by collections, arrays, or generating functions, which require no
* special resource management. Generally, only streams whose source is an IO channel,
* such as those returned by {@link Files#lines(Path)}, will require closing. If a
* stream does require closing, it must be opened as a resource within a try-with-resources
* statement or similar control structure to ensure that it is closed promptly after its
* operations have completed.
*
*
Stream pipelines may execute either sequentially or in
* parallel. This
* execution mode is a property of the stream. Streams are created
* with an initial choice of sequential or parallel execution. (For example,
* {@link Collection#stream() Collection.stream()} creates a sequential stream,
* and {@link Collection#parallelStream() Collection.parallelStream()} creates
* a parallel one.) This choice of execution mode may be modified by the
* {@link #sequential()} or {@link #parallel()} methods, and may be queried with
* the {@link #isParallel()} method.
*
* @param the type of the stream elements
* @since 1.8
* @see IntStream
* @see LongStream
* @see DoubleStream
* @see java.util.stream
*/
public interface Stream extends BaseStream> {
/**
* Returns a stream consisting of the elements of this stream that match
* the given predicate.
*
*
This is an intermediate
* operation.
*
* @param predicate a non-interfering,
* stateless
* predicate to apply to each element to determine if it
* should be included
* @return the new stream
*/
Stream filter(Predicate super T> predicate);
/**
* Returns a stream consisting of the results of applying the given
* function to the elements of this stream.
*
*
This is an intermediate
* operation.
*
* @param The element type of the new stream
* @param mapper a non-interfering,
* stateless
* function to apply to each element
* @return the new stream
*/
Stream 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.
*
*
This is an
* intermediate operation.
*
* @param mapper a non-interfering,
* stateless
* 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.
*
*
This is an intermediate
* operation.
*
* @param mapper a non-interfering,
* stateless
* 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.
*
*
This is an intermediate
* operation.
*
* @param mapper a non-interfering,
* stateless
* 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 a mapped stream produced by applying
* the provided mapping function to each element. Each mapped stream is
* {@link java.util.stream.BaseStream#close() closed} after its contents
* have been placed into this stream. (If a mapped stream is {@code null}
* an empty stream is used, instead.)
*
*
This is an intermediate
* operation.
*
* @apiNote
* The {@code flatMap()} operation has the effect of applying a one-to-many
* transformation to the elements of the stream, and then flattening the
* resulting elements into a new stream.
*
*
Examples.
*
*
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 containing all the line items in all the orders:
*
* The {@code mapper} function passed to {@code flatMap} splits a line,
* using a simple regular expression, into an array of words, and then
* creates a stream of words from that array.
*
* @param The element type of the new stream
* @param mapper a non-interfering,
* stateless
* function to apply to each element which produces a stream
* of new values
* @return the new stream
* @see #mapMulti
*/
Stream 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 a mapped stream produced by
* applying the provided mapping function to each element. Each mapped
* stream is {@link java.util.stream.BaseStream#close() closed} after its
* contents have been placed into this stream. (If a mapped stream is
* {@code null} an empty stream is used, instead.)
*
*
This is an intermediate
* operation.
*
* @param mapper a non-interfering,
* stateless
* function to apply to each element which produces a stream
* of new values
* @return the new stream
* @see #flatMap(Function)
*/
IntStream flatMapToInt(Function super T, ? extends IntStream> mapper);
/**
* Returns an {@code LongStream} consisting of the results of replacing each
* element of this stream with the contents of a mapped stream produced by
* applying the provided mapping function to each element. Each mapped
* stream is {@link java.util.stream.BaseStream#close() closed} after its
* contents have been placed into this stream. (If a mapped stream is
* {@code null} an empty stream is used, instead.)
*
*
This is an intermediate
* operation.
*
* @param mapper a non-interfering,
* stateless
* function to apply to each element which produces a stream
* of new values
* @return the new stream
* @see #flatMap(Function)
*/
LongStream flatMapToLong(Function super T, ? extends LongStream> mapper);
/**
* Returns an {@code DoubleStream} consisting of the results of replacing
* each element of this stream with the contents of a mapped stream produced
* by applying the provided mapping function to each element. Each mapped
* stream is {@link java.util.stream.BaseStream#close() closed} after its
* contents have placed been into this stream. (If a mapped stream is
* {@code null} an empty stream is used, instead.)
*
*
This is an intermediate
* operation.
*
* @param mapper a non-interfering,
* stateless
* function to apply to each element which produces a stream
* of new values
* @return the new stream
* @see #flatMap(Function)
*/
DoubleStream flatMapToDouble(Function super T, ? extends DoubleStream> mapper);
// THE EXAMPLES USED IN THE JAVADOC MUST BE IN SYNC WITH THEIR CORRESPONDING
// TEST IN test/jdk/java/util/stream/examples/JavadocExamples.java.
/**
* Returns a stream consisting of the results of replacing each element of
* this stream with multiple elements, specifically zero or more elements.
* Replacement is performed by applying the provided mapping function to each
* element in conjunction with a {@linkplain Consumer consumer} argument
* that accepts replacement elements. The mapping function calls the consumer
* zero or more times to provide the replacement elements.
*
*
If the {@linkplain Consumer consumer} argument is used outside the scope of
* its application to the mapping function, the results are undefined.
*
* @implSpec
* The default implementation invokes {@link #flatMap flatMap} on this stream,
* passing a function that behaves as follows. First, it calls the mapper function
* with a {@code Consumer} that accumulates replacement elements into a newly created
* internal buffer. When the mapper function returns, it creates a stream from the
* internal buffer. Finally, it returns this stream to {@code flatMap}.
*
* @apiNote
* This method is similar to {@link #flatMap flatMap} in that it applies a one-to-many
* transformation to the elements of the stream and flattens the result elements
* into a new stream. This method is preferable to {@code flatMap} in the following
* circumstances:
*
*
When replacing each stream element with a small (possibly zero) number of
* elements. Using this method avoids the overhead of creating a new Stream instance
* for every group of result elements, as required by {@code flatMap}.
*
When it is easier to use an imperative approach for generating result
* elements than it is to return them in the form of a Stream.
*
*
*
If a lambda expression is provided as the mapper function argument, additional type
* information may be necessary for proper inference of the element type {@code } of
* the returned stream. This can be provided in the form of explicit type declarations for
* the lambda parameters or as an explicit type argument to the {@code mapMulti} call.
*
*
Examples
*
*
Given a stream of {@code Number} objects, the following
* produces a list containing only the {@code Integer} objects:
*