1 /*
2 * Copyright (c) 2012, 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
23 * questions.
24 */
25 package java.util.stream;
26
27 import java.util.Objects;
28 import java.util.Spliterator;
29 import java.util.function.Supplier;
30
31 /**
32 * Low-level utility methods for creating and manipulating streams.
33 *
34 * <p>This class is mostly for library writers presenting stream views
35 * of their data structures; most static stream methods for end users are in
36 * {@link Streams}.
37 *
38 * <p> Unless otherwise stated, streams are created as sequential
39 * streams. A sequential stream can be transformed into a parallel stream by
40 * calling the {@code parallel()} method on the created stream.
41 *
42 * @since 1.8
43 */
44 public class StreamSupport {
45 /**
46 * Creates a new sequential {@code Stream} from a {@code Spliterator}.
47 * <p>
48 * The spliterator is only traversed, split, or queried for estimated size
49 * after the terminal operation of the stream pipeline commences.
50 * <p>
51 * It is strongly recommended the spliterator report a characteristic of
52 * {@code IMMUTABLE} or {@code CONCURRENT}, or be
53 * <a href="Spliterator.html#binding">late-binding</a>. Otherwise,
54 * {@link #stream(Supplier, int)} should be used to
55 * reduce the scope of potential interference with the source. See
56 * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
57 * more details.
58 *
59 * @param spliterator A {@code Spliterator} describing the stream elements
60 * @param <T> The type of stream elements
61 * @return A new sequential {@code Stream}
62 */
63 public static<T> Stream<T> stream(Spliterator<T> spliterator) {
64 Objects.requireNonNull(spliterator);
65 return new ReferencePipeline.Head<>(spliterator,
66 StreamOpFlag.fromCharacteristics(spliterator),
67 false);
68 }
69
70 /**
71 * Creates a new parallel {@code Stream} from a {@code Spliterator}.
72 * <p>
73 * The spliterator is only traversed, split, or queried for estimated size
74 * after the terminal operation of the stream pipeline commences.
75 * <p>
76 * It is strongly recommended the spliterator report a characteristic of
77 * {@code IMMUTABLE} or {@code CONCURRENT}, or be
78 * <a href="Spliterator.html#binding">late-binding</a>. Otherwise,
79 * {@link #stream(Supplier, int)} should be used to
80 * reduce the scope of potential interference with the source. See
81 * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
82 * more details.
83 *
84 * @param spliterator A {@code Spliterator} describing the stream elements
85 * @param <T> The type of stream elements
86 * @return A new parallel {@code Stream}
87 */
88 public static<T> Stream<T> parallelStream(Spliterator<T> spliterator) {
89 Objects.requireNonNull(spliterator);
90 return new ReferencePipeline.Head<>(spliterator,
91 StreamOpFlag.fromCharacteristics(spliterator),
92 true);
93 }
94
95 /**
96 * Creates a new sequential {@code Stream} from a {@code Supplier} of
97 * {@code Spliterator}.
98 * <p>
99 * The {@link Supplier#get()} method will be invoked on the supplier no
100 * more than once, and after the terminal operation of the stream pipeline
101 * commences.
102 * <p>
103 * For spliterators that report a characteristic of {@code IMMUTABLE}
104 * or {@code CONCURRENT}, or that are
105 * <a href="Spliterator.html#binding">late-binding</a>, it is likely
106 * more efficient to use {@link #stream(java.util.Spliterator)} instead.
107 * The use of a {@code Supplier} in this form provides a level of
108 * indirection that reduces the scope of potential interference with the
109 * source. Since the supplier is only invoked after the terminal operation
110 * commences, any modifications to the source up to the start of the
111 * terminal operation are reflected in the stream result. See
112 * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
113 * more details.
114 *
115 * @param supplier A {@code Supplier} of a {@code Spliterator}
116 * @param characteristics Spliterator characteristics of the supplied
117 * {@code Spliterator}. The characteristics must be equal to
118 * {@code source.get().getCharacteristics()}
119 * @param <T> The type of stream elements
120 * @return A new sequential {@code Stream}
121 * @see #stream(Spliterator)
122 */
123 public static<T> Stream<T> stream(Supplier<? extends Spliterator<T>> supplier,
124 int characteristics) {
125 Objects.requireNonNull(supplier);
126 return new ReferencePipeline.Head<>(supplier,
127 StreamOpFlag.fromCharacteristics(characteristics),
128 false);
129 }
130
131 /**
132 * Creates a new parallel {@code Stream} from a {@code Supplier} of
133 * {@code Spliterator}.
134 * <p>
135 * The {@link Supplier#get()} method will be invoked on the supplier no
136 * more than once, and after the terminal operation of the stream pipeline
137 * commences.
138 * <p>
139 * For spliterators that report a characteristic of {@code IMMUTABLE}
140 * or {@code CONCURRENT}, or that are
141 * <a href="Spliterator.html#binding">late-binding</a>, it is likely
142 * more efficient to use {@link #stream(Spliterator)} instead.
143 * The use of a {@code Supplier} in this form provides a level of
144 * indirection that reduces the scope of potential interference with the
145 * source. Since the supplier is only invoked after the terminal operation
146 * commences, any modifications to the source up to the start of the
147 * terminal operation are reflected in the stream result. See
148 * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
149 * more details.
150 *
151 * @param supplier A {@code Supplier} of a {@code Spliterator}
152 * @param characteristics Spliterator characteristics of the supplied
153 * {@code Spliterator}. The characteristics must be equal to
154 * {@code source.get().getCharacteristics()}
155 * @param <T> The type of stream elements
156 * @return A new parallel {@code Stream}
157 * @see #parallelStream(Spliterator)
158 */
159 public static<T> Stream<T> parallelStream(Supplier<? extends Spliterator<T>> supplier,
160 int characteristics) {
161 Objects.requireNonNull(supplier);
162 return new ReferencePipeline.Head<>(supplier,
163 StreamOpFlag.fromCharacteristics(characteristics),
164 true);
165 }
166
167 /**
168 * Creates a new sequential {@code IntStream} from a {@code Spliterator.OfInt}.
169 * <p>
170 * The spliterator is only traversed, split, or queried for estimated size
171 * after the terminal operation of the stream pipeline commences.
172 * <p>
173 * It is strongly recommended the spliterator report a characteristic of
174 * {@code IMMUTABLE} or {@code CONCURRENT}, or be
175 * <a href="Spliterator.html#binding">late-binding</a>. Otherwise,
176 * {@link #stream(Supplier, int)}} should be used to
177 * reduce the scope of potential interference with the source. See
178 * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
179 * more details.
180 *
181 * @param spliterator A {@code Spliterator.OfInt} describing the stream elements
182 * @return A new sequential {@code IntStream}
183 */
184 public static IntStream intStream(Spliterator.OfInt spliterator) {
185 return new IntPipeline.Head<>(spliterator,
186 StreamOpFlag.fromCharacteristics(spliterator),
187 false);
188 }
189
190 /**
191 * Creates a new parallel {@code IntStream} from a {@code Spliterator.OfInt}.
192 * <p>
193 * The spliterator is only traversed, split, or queried for estimated size
194 * after the terminal operation of the stream pipeline commences.
195 * <p>
196 * It is strongly recommended the spliterator report a characteristic of
197 * {@code IMMUTABLE} or {@code CONCURRENT}, or be
198 * <a href="Spliterator.html#binding">late-binding</a>. Otherwise,
199 * {@link #stream(Supplier, int)}} should be used to
200 * reduce the scope of potential interference with the source. See
201 * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
202 * more details.
203 *
204 * @param spliterator A {@code Spliterator.OfInt} describing the stream elements
205 * @return A new parallel {@code IntStream}
206 */
207 public static IntStream intParallelStream(Spliterator.OfInt spliterator) {
208 return new IntPipeline.Head<>(spliterator,
209 StreamOpFlag.fromCharacteristics(spliterator),
210 true);
211 }
212
213 /**
214 * Creates a new sequential {@code IntStream} from a {@code Supplier} of
215 * {@code Spliterator.OfInt}.
216 * <p>
217 * The {@link Supplier#get()} method will be invoked on the supplier no
218 * more than once, and after the terminal operation of the stream pipeline
219 * commences.
220 * <p>
221 * For spliterators that report a characteristic of {@code IMMUTABLE}
222 * or {@code CONCURRENT}, or that are
223 * <a href="Spliterator.html#binding">late-binding</a>, it is likely
224 * more efficient to use {@link #intStream(Spliterator.OfInt)} instead.
225 * The use of a {@code Supplier} in this form provides a level of
226 * indirection that reduces the scope of potential interference with the
227 * source. Since the supplier is only invoked after the terminal operation
228 * commences, any modifications to the source up to the start of the
229 * terminal operation are reflected in the stream result. See
230 * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
231 * more details.
232 *
233 * @param supplier A {@code Supplier} of a {@code Spliterator.OfInt}
234 * @param characteristics Spliterator characteristics of the supplied
235 * {@code Spliterator.OfInt}. The characteristics must be equal to
236 * {@code source.get().getCharacteristics()}
237 * @return A new sequential {@code IntStream}
238 * @see #intStream(Spliterator.OfInt)
239 */
240 public static IntStream intStream(Supplier<? extends Spliterator.OfInt> supplier,
241 int characteristics) {
242 return new IntPipeline.Head<>(supplier,
243 StreamOpFlag.fromCharacteristics(characteristics),
244 false);
245 }
246
247 /**
248 * Creates a new parallel {@code IntStream} from a {@code Supplier} of
249 * {@code Spliterator.OfInt}.
250 * <p>
251 * The {@link Supplier#get()} method will be invoked on the supplier no
252 * more than once, and after the terminal operation of the stream pipeline
253 * commences.
254 * <p>
255 * For spliterators that report a characteristic of {@code IMMUTABLE}
256 * or {@code CONCURRENT}, or that are
257 * <a href="Spliterator.html#binding">late-binding</a>, it is likely
258 * more efficient to use {@link #intStream(Spliterator.OfInt)} instead.
259 * The use of a {@code Supplier} in this form provides a level of
260 * indirection that reduces the scope of potential interference with the
261 * source. Since the supplier is only invoked after the terminal operation
262 * commences, any modifications to the source up to the start of the
263 * terminal operation are reflected in the stream result. See
264 * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
265 * more details.
266 *
267 * @param supplier A {@code Supplier} of a {@code Spliterator.OfInt}
268 * @param characteristics Spliterator characteristics of the supplied
269 * {@code Spliterator.OfInt}. The characteristics must be equal to
270 * {@code source.get().getCharacteristics()}
271 * @return A new parallel {@code IntStream}
272 * @see #intParallelStream(Spliterator.OfInt)
273 */
274 public static IntStream intParallelStream(Supplier<? extends Spliterator.OfInt> supplier,
275 int characteristics) {
276 return new IntPipeline.Head<>(supplier,
277 StreamOpFlag.fromCharacteristics(characteristics),
278 true);
279 }
280
281 /**
282 * Creates a new sequential {@code LongStream} from a {@code Spliterator.OfLong}.
283 * <p>
284 * The spliterator is only traversed, split, or queried for estimated size
285 * after the terminal operation of the stream pipeline commences.
286 * <p>
287 * It is strongly recommended the spliterator report a characteristic of
288 * {@code IMMUTABLE} or {@code CONCURRENT}, or be
289 * <a href="Spliterator.html#binding">late-binding</a>. Otherwise,
290 * {@link #stream(Supplier, int)} should be used to
291 * reduce the scope of potential interference with the source. See
292 * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
293 * more details.
294 *
295 * @param spliterator A {@code Spliterator.OfLong} describing the stream elements
296 * @return A new sequential {@code LongStream}
297 */
298 public static LongStream longStream(Spliterator.OfLong spliterator) {
299 return new LongPipeline.Head<>(spliterator,
300 StreamOpFlag.fromCharacteristics(spliterator),
301 false);
302 }
303
304 /**
305 * Creates a new parallel {@code LongStream} from a {@code Spliterator.OfLong}.
306 * <p>
307 * The spliterator is only traversed, split, or queried for estimated size
308 * after the terminal operation of the stream pipeline commences.
309 * <p>
310 * It is strongly recommended the spliterator report a characteristic of
311 * {@code IMMUTABLE} or {@code CONCURRENT}, or be
312 * <a href="Spliterator.html#binding">late-binding</a>. Otherwise,
313 * {@link #stream(Supplier, int)} should be used to
314 * reduce the scope of potential interference with the source. See
315 * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
316 * more details.
317 *
318 * @param spliterator A {@code Spliterator.OfLong} describing the stream elements
319 * @return A new parallel {@code LongStream}
320 */
321 public static LongStream longParallelStream(Spliterator.OfLong spliterator) {
322 return new LongPipeline.Head<>(spliterator,
323 StreamOpFlag.fromCharacteristics(spliterator),
324 true);
325 }
326
327 /**
328 * Creates a new sequential {@code LongStream} from a {@code Supplier} of
329 * {@code Spliterator.OfLong}.
330 * <p>
331 * The {@link Supplier#get()} method will be invoked on the supplier no
332 * more than once, and after the terminal operation of the stream pipeline
333 * commences.
334 * <p>
335 * For spliterators that report a characteristic of {@code IMMUTABLE}
336 * or {@code CONCURRENT}, or that are
337 * <a href="Spliterator.html#binding">late-binding</a>, it is likely
338 * more efficient to use {@link #longStream(Spliterator.OfLong)} instead.
339 * The use of a {@code Supplier} in this form provides a level of
340 * indirection that reduces the scope of potential interference with the
341 * source. Since the supplier is only invoked after the terminal operation
342 * commences, any modifications to the source up to the start of the
343 * terminal operation are reflected in the stream result. See
344 * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
345 * more details.
346 *
347 * @param supplier A {@code Supplier} of a {@code Spliterator.OfLong}
348 * @param characteristics Spliterator characteristics of the supplied
349 * {@code Spliterator.OfLong}. The characteristics must be equal to
350 * {@code source.get().getCharacteristics()}
351 * @return A new sequential {@code LongStream}
352 * @see #longStream(Spliterator.OfLong)
353 */
354 public static LongStream longStream(Supplier<? extends Spliterator.OfLong> supplier,
355 int characteristics) {
356 return new LongPipeline.Head<>(supplier,
357 StreamOpFlag.fromCharacteristics(characteristics),
358 false);
359 }
360
361 /**
362 * Creates a new parallel {@code LongStream} from a {@code Supplier} of
363 * {@code Spliterator.OfLong}.
364 * <p>
365 * The {@link Supplier#get()} method will be invoked on the supplier no
366 * more than once, and after the terminal operation of the stream pipeline
367 * commences.
368 * <p>
369 * For spliterators that report a characteristic of {@code IMMUTABLE}
370 * or {@code CONCURRENT}, or that are
371 * <a href="Spliterator.html#binding">late-binding</a>, it is likely
372 * more efficient to use {@link #longStream(Spliterator.OfLong)} instead.
373 * The use of a {@code Supplier} in this form provides a level of
374 * indirection that reduces the scope of potential interference with the
375 * source. Since the supplier is only invoked after the terminal operation
376 * commences, any modifications to the source up to the start of the
377 * terminal operation are reflected in the stream result. See
378 * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
379 * more details.
380 *
381 * @param supplier A {@code Supplier} of a {@code Spliterator.OfLong}
382 * @param characteristics Spliterator characteristics of the supplied
383 * {@code Spliterator.OfLong}. The characteristics must be equal to
384 * {@code source.get().getCharacteristics()}
385 * @return A new parallel {@code LongStream}
386 * @see #longParallelStream(Spliterator.OfLong)
387 */
388 public static LongStream longParallelStream(Supplier<? extends Spliterator.OfLong> supplier,
389 int characteristics) {
390 return new LongPipeline.Head<>(supplier,
391 StreamOpFlag.fromCharacteristics(characteristics),
392 true);
393 }
394
395 /**
396 * Creates a new sequential {@code DoubleStream} from a {@code Spliterator.OfDouble}.
397 * <p>
398 * The spliterator is only traversed, split, or queried for estimated size
399 * after the terminal operation of the stream pipeline commences.
400 * <p>
401 * It is strongly recommended the spliterator report a characteristic of
402 * {@code IMMUTABLE} or {@code CONCURRENT}, or be
403 * <a href="Spliterator.html#binding">late-binding</a>. Otherwise,
404 * {@link #stream(Supplier, int)} should be used to
405 * reduce the scope of potential interference with the source. See
406 * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
407 * more details.
408 *
409 * @param spliterator A {@code Spliterator.OfDouble} describing the stream elements
410 * @return A new sequential {@code DoubleStream}
411 */
412 public static DoubleStream doubleStream(Spliterator.OfDouble spliterator) {
413 return new DoublePipeline.Head<>(spliterator,
414 StreamOpFlag.fromCharacteristics(spliterator),
415 false);
416 }
417
418 /**
419 * Creates a new parallel {@code DoubleStream} from a {@code Spliterator.OfDouble}.
420 * <p>
421 * The spliterator is only traversed, split, or queried for estimated size
422 * after the terminal operation of the stream pipeline commences.
423 * <p>
424 * It is strongly recommended the spliterator report a characteristic of
425 * {@code IMMUTABLE} or {@code CONCURRENT}, or be
426 * <a href="Spliterator.html#binding">late-binding</a>. Otherwise,
427 * {@link #stream(Supplier, int)} should be used to
428 * reduce the scope of potential interference with the source. See
429 * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
430 * more details.
431 *
432 * @param spliterator A {@code Spliterator.OfDouble} describing the stream elements
433 * @return A new parallel {@code DoubleStream}
434 */
435 public static DoubleStream doubleParallelStream(Spliterator.OfDouble spliterator) {
436 return new DoublePipeline.Head<>(spliterator,
437 StreamOpFlag.fromCharacteristics(spliterator),
438 true);
439 }
440
441 /**
442 * Creates a new sequential {@code DoubleStream} from a {@code Supplier} of
443 * {@code Spliterator.OfDouble}.
444 * <p>
445 * The {@link Supplier#get()} method will be invoked on the supplier no
446 * more than once, and after the terminal operation of the stream pipeline
447 * commences.
448 * <p>
449 * For spliterators that report a characteristic of {@code IMMUTABLE}
450 * or {@code CONCURRENT}, or that are
451 * <a href="Spliterator.html#binding">late-binding</a>, it is likely
452 * more efficient to use {@link #doubleStream(Spliterator.OfDouble)} instead.
453 * The use of a {@code Supplier} in this form provides a level of
454 * indirection that reduces the scope of potential interference with the
455 * source. Since the supplier is only invoked after the terminal operation
456 * commences, any modifications to the source up to the start of the
457 * terminal operation are reflected in the stream result. See
458 * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
459 * more details.
460 *
461 * @param supplier A {@code Supplier} of a {@code Spliterator.OfDouble}
462 * @param characteristics Spliterator characteristics of the supplied
463 * {@code Spliterator.OfDouble}. The characteristics must be equal to
464 * {@code source.get().getCharacteristics()}
465 * @return A new sequential {@code DoubleStream}
466 * @see #doubleStream(Spliterator.OfDouble)
467 */
468 public static DoubleStream doubleStream(Supplier<? extends Spliterator.OfDouble> supplier,
469 int characteristics) {
470 return new DoublePipeline.Head<>(supplier,
471 StreamOpFlag.fromCharacteristics(characteristics),
472 false);
473 }
474
475 /**
476 * Creates a new parallel {@code DoubleStream} from a {@code Supplier} of
477 * {@code Spliterator.OfDouble}.
478 * <p>
479 * The {@link Supplier#get()} method will be invoked on the supplier no
480 * more than once, and after the terminal operation of the stream pipeline
481 * commences.
482 * <p>
483 * For spliterators that report a characteristic of {@code IMMUTABLE}
484 * or {@code CONCURRENT}, or that are
485 * <a href="Spliterator.html#binding">late-binding</a>, it is likely
486 * more efficient to use {@link #doubleStream(Spliterator.OfDouble)} instead.
487 * The use of a {@code Supplier} in this form provides a level of
488 * indirection that reduces the scope of potential interference with the
489 * source. Since the supplier is only invoked after the terminal operation
490 * commences, any modifications to the source up to the start of the
491 * terminal operation are reflected in the stream result. See
492 * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
493 * more details.
494 *
495 * @param supplier A {@code Supplier} of a {@code Spliterator.OfDouble}
496 * @param characteristics Spliterator characteristics of the supplied
497 * {@code Spliterator.OfDouble}. The characteristics must be equal to
498 * {@code source.get().getCharacteristics()}
499 * @return A new parallel {@code DoubleStream}
500 * @see #doubleParallelStream(Spliterator.OfDouble)
501 */
502 public static DoubleStream doubleParallelStream(Supplier<? extends Spliterator.OfDouble> supplier,
503 int characteristics) {
504 return new DoublePipeline.Head<>(supplier,
505 StreamOpFlag.fromCharacteristics(characteristics),
506 true);
507 }
508 }