1 /*
2 * Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
86 * the computation of the result. For example, a stream implementation is free
87 * to elide operations (or entire stages) from a stream pipeline -- and
88 * therefore elide invocation of behavioral parameters -- if it can prove that
89 * it would not affect the result of the computation. This means that
90 * side-effects of behavioral parameters may not always be executed and should
91 * not be relied upon, unless otherwise specified (such as by the terminal
92 * operations {@code forEach} and {@code forEachOrdered}). (For a specific
93 * example of such an optimization, see the API note documented on the
94 * {@link #count} operation. For more detail, see the
95 * <a href="package-summary.html#SideEffects">side-effects</a> section of the
96 * stream package documentation.)
97 *
98 * <p>Collections and streams, while bearing some superficial similarities,
99 * have different goals. Collections are primarily concerned with the efficient
100 * management of, and access to, their elements. By contrast, streams do not
101 * provide a means to directly access or manipulate their elements, and are
102 * instead concerned with declaratively describing their source and the
103 * computational operations which will be performed in aggregate on that source.
104 * However, if the provided stream operations do not offer the desired
105 * functionality, the {@link #iterator()} and {@link #spliterator()} operations
106 * can be used to perform a controlled traversal.
107 *
108 * <p>A stream pipeline, like the "widgets" example above, can be viewed as
109 * a <em>query</em> on the stream source. Unless the source was explicitly
110 * designed for concurrent modification (such as a {@link ConcurrentHashMap}),
111 * unpredictable or erroneous behavior may result from modifying the stream
112 * source while it is being queried.
113 *
114 * <p>Most stream operations accept parameters that describe user-specified
115 * behavior, such as the lambda expression {@code w -> w.getWeight()} passed to
116 * {@code mapToInt} in the example above. To preserve correct behavior,
117 * these <em>behavioral parameters</em>:
118 * <ul>
119 * <li>must be <a href="package-summary.html#NonInterference">non-interfering</a>
120 * (they do not modify the stream source); and</li>
121 * <li>in most cases must be <a href="package-summary.html#Statelessness">stateless</a>
122 * (their result should not depend on any state that might change during execution
123 * of the stream pipeline).</li>
124 * </ul>
125 *
126 * <p>Such parameters are always instances of a
147 * statement or similar control structure to ensure that it is closed promptly after its
148 * operations have completed.
149 *
150 * <p>Stream pipelines may execute either sequentially or in
151 * <a href="package-summary.html#Parallelism">parallel</a>. This
152 * execution mode is a property of the stream. Streams are created
153 * with an initial choice of sequential or parallel execution. (For example,
154 * {@link Collection#stream() Collection.stream()} creates a sequential stream,
155 * and {@link Collection#parallelStream() Collection.parallelStream()} creates
156 * a parallel one.) This choice of execution mode may be modified by the
157 * {@link #sequential()} or {@link #parallel()} methods, and may be queried with
158 * the {@link #isParallel()} method.
159 *
160 * @param <T> the type of the stream elements
161 * @since 1.8
162 * @see IntStream
163 * @see LongStream
164 * @see DoubleStream
165 * @see <a href="package-summary.html">java.util.stream</a>
166 */
167 public interface Stream<T> extends BaseStream<T, Stream<T>> {
168
169 /**
170 * Returns a stream consisting of the elements of this stream that match
171 * the given predicate.
172 *
173 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
174 * operation</a>.
175 *
176 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
177 * <a href="package-summary.html#Statelessness">stateless</a>
178 * predicate to apply to each element to determine if it
179 * should be included
180 * @return the new stream
181 */
182 Stream<T> filter(Predicate<? super T> predicate);
183
184 /**
185 * Returns a stream consisting of the results of applying the given
186 * function to the elements of this stream.
187 *
|
1 /*
2 * Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
86 * the computation of the result. For example, a stream implementation is free
87 * to elide operations (or entire stages) from a stream pipeline -- and
88 * therefore elide invocation of behavioral parameters -- if it can prove that
89 * it would not affect the result of the computation. This means that
90 * side-effects of behavioral parameters may not always be executed and should
91 * not be relied upon, unless otherwise specified (such as by the terminal
92 * operations {@code forEach} and {@code forEachOrdered}). (For a specific
93 * example of such an optimization, see the API note documented on the
94 * {@link #count} operation. For more detail, see the
95 * <a href="package-summary.html#SideEffects">side-effects</a> section of the
96 * stream package documentation.)
97 *
98 * <p>Collections and streams, while bearing some superficial similarities,
99 * have different goals. Collections are primarily concerned with the efficient
100 * management of, and access to, their elements. By contrast, streams do not
101 * provide a means to directly access or manipulate their elements, and are
102 * instead concerned with declaratively describing their source and the
103 * computational operations which will be performed in aggregate on that source.
104 * However, if the provided stream operations do not offer the desired
105 * functionality, the {@link #iterator()} and {@link #spliterator()} operations
106 * can be used to perform a controlled traversal. Stream implements the
107 * {@link IterableOnce} interface, allowing a stream instance to be used
108 * in an enhanced-for ("for each") statement. Note that this statement implicitly
109 * calls the {@code iterator()} method, which consumes the stream. The stream
110 * thus cannot be used for any subsequent operations.
111 *
112 * <p>A stream pipeline, like the "widgets" example above, can be viewed as
113 * a <em>query</em> on the stream source. Unless the source was explicitly
114 * designed for concurrent modification (such as a {@link ConcurrentHashMap}),
115 * unpredictable or erroneous behavior may result from modifying the stream
116 * source while it is being queried.
117 *
118 * <p>Most stream operations accept parameters that describe user-specified
119 * behavior, such as the lambda expression {@code w -> w.getWeight()} passed to
120 * {@code mapToInt} in the example above. To preserve correct behavior,
121 * these <em>behavioral parameters</em>:
122 * <ul>
123 * <li>must be <a href="package-summary.html#NonInterference">non-interfering</a>
124 * (they do not modify the stream source); and</li>
125 * <li>in most cases must be <a href="package-summary.html#Statelessness">stateless</a>
126 * (their result should not depend on any state that might change during execution
127 * of the stream pipeline).</li>
128 * </ul>
129 *
130 * <p>Such parameters are always instances of a
151 * statement or similar control structure to ensure that it is closed promptly after its
152 * operations have completed.
153 *
154 * <p>Stream pipelines may execute either sequentially or in
155 * <a href="package-summary.html#Parallelism">parallel</a>. This
156 * execution mode is a property of the stream. Streams are created
157 * with an initial choice of sequential or parallel execution. (For example,
158 * {@link Collection#stream() Collection.stream()} creates a sequential stream,
159 * and {@link Collection#parallelStream() Collection.parallelStream()} creates
160 * a parallel one.) This choice of execution mode may be modified by the
161 * {@link #sequential()} or {@link #parallel()} methods, and may be queried with
162 * the {@link #isParallel()} method.
163 *
164 * @param <T> the type of the stream elements
165 * @since 1.8
166 * @see IntStream
167 * @see LongStream
168 * @see DoubleStream
169 * @see <a href="package-summary.html">java.util.stream</a>
170 */
171 public interface Stream<T> extends BaseStream<T, Stream<T>>, IterableOnce<T> {
172
173 // Need to re-abstract spliterator() to avoid inheriting the default
174 // method from Iterable.
175 /**
176 * {@inheritDoc}
177 * @return {@inheritDoc}
178 */
179 Spliterator<T> spliterator();
180
181 /**
182 * Returns a stream consisting of the elements of this stream that match
183 * the given predicate.
184 *
185 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
186 * operation</a>.
187 *
188 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
189 * <a href="package-summary.html#Statelessness">stateless</a>
190 * predicate to apply to each element to determine if it
191 * should be included
192 * @return the new stream
193 */
194 Stream<T> filter(Predicate<? super T> predicate);
195
196 /**
197 * Returns a stream consisting of the results of applying the given
198 * function to the elements of this stream.
199 *
|