1 /*
2 * Copyright (c) 2012, 2013, 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.Arrays;
28 import java.util.DoubleSummaryStatistics;
29 import java.util.Objects;
30 import java.util.OptionalDouble;
31 import java.util.PrimitiveIterator;
32 import java.util.Spliterator;
33 import java.util.Spliterators;
34 import java.util.function.BiConsumer;
35 import java.util.function.DoubleBinaryOperator;
36 import java.util.function.DoubleConsumer;
37 import java.util.function.DoubleFunction;
38 import java.util.function.DoublePredicate;
39 import java.util.function.DoubleSupplier;
40 import java.util.function.DoubleToIntFunction;
41 import java.util.function.DoubleToLongFunction;
42 import java.util.function.DoubleUnaryOperator;
43 import java.util.function.Function;
44 import java.util.function.ObjDoubleConsumer;
45 import java.util.function.Supplier;
46
47 /**
48 * A sequence of primitive double elements supporting sequential and parallel
49 * bulk operations. Streams support lazy intermediate operations (transforming
50 * a stream to another stream) such as {@code filter} and {@code map}, and terminal
51 * operations (consuming the contents of a stream to produce a result or
52 * side-effect), such as {@code forEach}, {@code findFirst}, and {@code
53 * iterator}. Once an operation has been performed on a stream, it
54 * is considered <em>consumed</em> and no longer usable for other operations.
55 *
56 * <p>For sequential stream pipelines, all operations are performed in the
57 * <a href="package-summary.html#Ordering">encounter order</a> of the pipeline
58 * source, if the pipeline source has a defined encounter order.
59 *
60 * <p>For parallel stream pipelines, unless otherwise specified, intermediate
61 * stream operations preserve the <a href="package-summary.html#Ordering">
62 * encounter order</a> of their source, and terminal operations
63 * respect the encounter order of their source, if the source
64 * has an encounter order. Provided that and parameters to stream operations
65 * satisfy the <a href="package-summary.html#NonInterference">non-interference
66 * requirements</a>, and excepting differences arising from the absence of
67 * a defined encounter order, the result of a stream pipeline should be the
68 * stable across multiple executions of the same operations on the same source.
69 * However, the timing and thread in which side-effects occur (for those
70 * operations which are allowed to produce side-effects, such as
71 * {@link #forEach(DoubleConsumer)}), are explicitly nondeterministic for parallel
72 * execution of stream pipelines.
73 *
74 * <p>Unless otherwise noted, passing a {@code null} argument to any stream
75 * method may result in a {@link NullPointerException}.
76 *
77 * @apiNote
78 * Streams are not data structures; they do not manage the storage for their
79 * elements, nor do they support access to individual elements. However,
80 * you can use the {@link #iterator()} or {@link #spliterator()} operations to
81 * perform a controlled traversal.
82 *
83 * @since 1.8
84 * @see <a href="package-summary.html">java.util.stream</a>
85 */
86 public interface DoubleStream extends BaseStream<Double, DoubleStream> {
87
88 /**
89 * Returns a stream consisting of the elements of this stream that match
90 * the given predicate.
91 *
92 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
93 * operation</a>.
94 *
95 * @param predicate a <a href="package-summary.html#NonInterference">
96 * non-interfering, stateless</a> predicate to apply to
97 * each element to determine if it should be included
98 * @return the new stream
99 */
100 DoubleStream filter(DoublePredicate predicate);
101
102 /**
103 * Returns a stream consisting of the results of applying the given
104 * function to the elements of this stream.
105 *
106 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
107 * operation</a>.
108 *
109 * @param mapper a <a href="package-summary.html#NonInterference">
110 * non-interfering, stateless</a> function to apply to
111 * each element
112 * @return the new stream
113 */
114 DoubleStream map(DoubleUnaryOperator mapper);
115
116 /**
117 * Returns an object-valued {@code Stream} consisting of the results of
118 * applying the given function to the elements of this stream.
119 *
120 * <p>This is an <a href="package-summary.html#StreamOps">
121 * intermediate operation</a>.
122 *
123 * @param <U> the element type of the new stream
124 * @param mapper a <a href="package-summary.html#NonInterference">
125 * non-interfering, stateless</a> function to apply to each
126 * element
127 * @return the new stream
128 */
129 <U> Stream<U> mapToObj(DoubleFunction<? extends U> mapper);
130
131 /**
132 * Returns an {@code IntStream} consisting of the results of applying the
133 * given function to the elements of this stream.
134 *
135 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
136 * operation</a>.
137 *
138 * @param mapper a <a href="package-summary.html#NonInterference">
139 * non-interfering, stateless</a> function to apply to each
140 * element
141 * @return the new stream
142 */
143 IntStream mapToInt(DoubleToIntFunction mapper);
144
145 /**
146 * Returns a {@code LongStream} consisting of the results of applying the
147 * given function to the elements of this stream.
148 *
149 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
150 * operation</a>.
151 *
152 * @param mapper a <a href="package-summary.html#NonInterference">
153 * non-interfering, stateless</a> function to apply to each
154 * element
155 * @return the new stream
156 */
157 LongStream mapToLong(DoubleToLongFunction mapper);
158
159 /**
160 * Returns a stream consisting of the results of replacing each element of
161 * this stream with the contents of the stream produced by applying the
162 * provided mapping function to each element.
163 *
164 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
165 * operation</a>.
166 *
167 * @apiNote
168 * The {@code flatMap()} operation has the effect of applying a one-to-many
169 * tranformation to the elements of the stream, and then flattening the
170 * resulting elements into a new stream. For example, if {@code orders}
171 * is a stream of purchase orders, and each purchase order contains a
172 * collection of line items, then the following produces a stream of line
173 * items:
174 * <pre>{@code
175 * orderStream.flatMap(order -> order.getLineItems().stream())...
176 * }</pre>
177 *
178 * @param mapper a <a href="package-summary.html#NonInterference">
179 * non-interfering, stateless</a> function to apply to
180 * each element which produces an {@code DoubleStream} of new
181 * values
182 * @return the new stream
183 * @see Stream#flatMap(Function)
184 */
185 DoubleStream flatMap(DoubleFunction<? extends DoubleStream> mapper);
186
187 /**
188 * Returns a stream consisting of the distinct elements of this stream. The
189 * elements are compared for equality according to
190 * {@link java.lang.Double#compare(double, double)}.
191 *
192 * <p>This is a <a href="package-summary.html#StreamOps">stateful
193 * intermediate operation</a>.
194 *
195 * @return the result stream
196 */
197 DoubleStream distinct();
198
199 /**
200 * Returns a stream consisting of the elements of this stream in sorted
201 * order. The elements are compared for equality according to
202 * {@link java.lang.Double#compare(double, double)}.
203 *
204 * <p>This is a <a href="package-summary.html#StreamOps">stateful
205 * intermediate operation</a>.
206 *
207 * @return the result stream
208 */
209 DoubleStream sorted();
210
211 /**
212 * Returns a stream consisting of the elements of this stream, additionally
213 * performing the provided action on each element as elements are consumed
214 * from the resulting stream.
215 *
216 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
217 * operation</a>.
218 *
219 * <p>For parallel stream pipelines, the action may be called at
220 * whatever time and in whatever thread the element is made available by the
221 * upstream operation. If the action modifies shared state,
222 * it is responsible for providing the required synchronization.
223 *
224 * @apiNote This method exists mainly to support debugging, where you want
225 * to see the elements as they flow past a certain point in a pipeline:
226 * <pre>{@code
227 * list.stream()
228 * .filter(filteringFunction)
229 * .peek(e -> {System.out.println("Filtered value: " + e); });
230 * .map(mappingFunction)
231 * .peek(e -> {System.out.println("Mapped value: " + e); });
232 * .collect(Collectors.toDoubleSummaryStastistics());
233 * }</pre>
234 *
235 * @param consumer a <a href="package-summary.html#NonInterference">
236 * non-interfering</a> action to perform on the elements as
237 * they are consumed from the stream
238 * @return the new stream
239 */
240 DoubleStream peek(DoubleConsumer consumer);
241
242 /**
243 * Returns a stream consisting of the elements of this stream, truncated
244 * to be no longer than {@code maxSize} in length.
245 *
246 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
247 * stateful intermediate operation</a>.
248 *
249 * @param maxSize the number of elements the stream should be limited to
250 * @return the new stream
251 * @throws IllegalArgumentException if {@code maxSize} is negative
252 */
253 DoubleStream limit(long maxSize);
254
255 /**
256 * Returns a stream consisting of the remaining elements of this stream
257 * after indexing {@code startInclusive} elements into the stream. If the
258 * {@code startInclusive} index lies past the end of this stream then an
259 * empty stream will be returned.
260 *
261 * <p>This is a <a href="package-summary.html#StreamOps">stateful
262 * intermediate operation</a>.
263 *
264 * @param startInclusive the number of leading elements to skip
265 * @return the new stream
266 * @throws IllegalArgumentException if {@code startInclusive} is negative
267 */
268 DoubleStream substream(long startInclusive);
269
270 /**
271 * Returns a stream consisting of the remaining elements of this stream
272 * after indexing {@code startInclusive} elements into the stream and
273 * truncated to contain no more than {@code endExclusive - startInclusive}
274 * elements. If the {@code startInclusive} index lies past the end
275 * of this stream then an empty stream will be returned.
276 *
277 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
278 * stateful intermediate operation</a>.
279 *
280 * @param startInclusive the starting position of the substream, inclusive
281 * @param endExclusive the ending position of the substream, exclusive
282 * @return the new stream
283 * @throws IllegalArgumentException if {@code startInclusive} or
284 * {@code endExclusive} is negative or {@code startInclusive} is greater
285 * than {@code endExclusive}
286 */
287 DoubleStream substream(long startInclusive, long endExclusive);
288
289 /**
290 * Performs an action for each element of this stream.
291 *
292 * <p>This is a <a href="package-summary.html#StreamOps">terminal
293 * operation</a>.
294 *
295 * <p>For parallel stream pipelines, this operation does <em>not</em>
296 * guarantee to respect the encounter order of the stream, as doing so
297 * would sacrifice the benefit of parallelism. For any given element, the
298 * action may be performed at whatever time and in whatever thread the
299 * library chooses. If the action accesses shared state, it is
300 * responsible for providing the required synchronization.
301 *
302 * @param action a <a href="package-summary.html#NonInterference">
303 * non-interfering</a> action to perform on the elements
304 */
305 void forEach(DoubleConsumer action);
306
307 /**
308 * Performs an action for each element of this stream, guaranteeing that
309 * each element is processed in encounter order for streams that have a
310 * defined encounter order.
311 *
312 * <p>This is a <a href="package-summary.html#StreamOps">terminal
313 * operation</a>.
314 *
315 * @param action a <a href="package-summary.html#NonInterference">
316 * non-interfering</a> action to perform on the elements
317 * @see #forEach(DoubleConsumer)
318 */
319 void forEachOrdered(DoubleConsumer action);
320
321 /**
322 * Returns an array containing the elements of this stream.
323 *
324 * <p>This is a <a href="package-summary.html#StreamOps">terminal
325 * operation</a>.
326 *
327 * @return an array containing the elements of this stream
328 */
329 double[] toArray();
330
331 /**
332 * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
333 * elements of this stream, using the provided identity value and an
334 * <a href="package-summary.html#Associativity">associative</a>
335 * accumulation function, and returns the reduced value. This is equivalent
336 * to:
337 * <pre>{@code
338 * double result = identity;
339 * for (double element : this stream)
340 * result = accumulator.apply(result, element)
341 * return result;
342 * }</pre>
343 *
344 * but is not constrained to execute sequentially.
345 *
346 * <p>The {@code identity} value must be an identity for the accumulator
347 * function. This means that for all {@code x},
348 * {@code accumulator.apply(identity, x)} is equal to {@code x}.
349 * The {@code accumulator} function must be an
350 * <a href="package-summary.html#Associativity">associative</a> function.
351 *
352 * <p>This is a <a href="package-summary.html#StreamOps">terminal
353 * operation</a>.
354 *
355 * @apiNote Sum, min, max, and average are all special cases of reduction.
356 * Summing a stream of numbers can be expressed as:
357
358 * <pre>{@code
359 * double sum = numbers.reduce(0, (a, b) -> a+b);
360 * }</pre>
361 *
362 * or more compactly:
363 *
364 * <pre>{@code
365 * double sum = numbers.reduce(0, Double::sum);
366 * }</pre>
367 *
368 * <p>While this may seem a more roundabout way to perform an aggregation
369 * compared to simply mutating a running total in a loop, reduction
370 * operations parallelize more gracefully, without needing additional
371 * synchronization and with greatly reduced risk of data races.
372 *
373 * @param identity the identity value for the accumulating function
374 * @param op an <a href="package-summary.html#Associativity">associative</a>
375 * <a href="package-summary.html#NonInterference">non-interfering,
376 * stateless</a> function for combining two values
377 * @return the result of the reduction
378 * @see #sum()
379 * @see #min()
380 * @see #max()
381 * @see #average()
382 */
383 double reduce(double identity, DoubleBinaryOperator op);
384
385 /**
386 * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
387 * elements of this stream, using an
388 * <a href="package-summary.html#Associativity">associative</a> accumulation
389 * function, and returns an {@code OptionalDouble} describing the reduced
390 * value, if any. This is equivalent to:
391 * <pre>{@code
392 * boolean foundAny = false;
393 * double result = null;
394 * for (double element : this stream) {
395 * if (!foundAny) {
396 * foundAny = true;
397 * result = element;
398 * }
399 * else
400 * result = accumulator.apply(result, element);
401 * }
402 * return foundAny ? OptionalDouble.of(result) : OptionalDouble.empty();
403 * }</pre>
404 *
405 * but is not constrained to execute sequentially.
406 *
407 * <p>The {@code accumulator} function must be an
408 * <a href="package-summary.html#Associativity">associative</a> function.
409 *
410 * <p>This is a <a href="package-summary.html#StreamOps">terminal
411 * operation</a>.
412 *
413 * @param op an <a href="package-summary.html#Associativity">associative</a>
414 * <a href="package-summary.html#NonInterference">non-interfering,
415 * stateless</a> function for combining two values
416 * @return the result of the reduction
417 * @see #reduce(double, DoubleBinaryOperator)
418 */
419 OptionalDouble reduce(DoubleBinaryOperator op);
420
421 /**
422 * Performs a <a href="package-summary.html#MutableReduction">mutable
423 * reduction</a> operation on the elements of this stream. A mutable
424 * reduction is one in which the reduced value is a mutable value holder,
425 * such as an {@code ArrayList}, and elements are incorporated by updating
426 * the state of the result, rather than by replacing the result. This
427 * produces a result equivalent to:
428 * <pre>{@code
429 * R result = resultFactory.get();
430 * for (double element : this stream)
431 * accumulator.accept(result, element);
432 * return result;
433 * }</pre>
434 *
435 * <p>Like {@link #reduce(double, DoubleBinaryOperator)}, {@code collect}
436 * operations can be parallelized without requiring additional
437 * synchronization.
438 *
439 * <p>This is a <a href="package-summary.html#StreamOps">terminal
440 * operation</a>.
441 *
442 * @param <R> type of the result
443 * @param resultFactory a function that creates a new result container.
444 * For a parallel execution, this function may be
445 * called multiple times and must return a fresh value
446 * each time.
447 * @param accumulator an <a href="package-summary.html#Associativity">associative</a>
448 * <a href="package-summary.html#NonInterference">non-interfering,
449 * stateless</a> function for incorporating an additional
450 * element into a result
451 * @param combiner an <a href="package-summary.html#Associativity">associative</a>
452 * <a href="package-summary.html#NonInterference">non-interfering,
453 * stateless</a> function for combining two values, which
454 * must be compatible with the accumulator function
455 * @return the result of the reduction
456 * @see Stream#collect(Supplier, BiConsumer, BiConsumer)
457 */
458 <R> R collect(Supplier<R> resultFactory,
459 ObjDoubleConsumer<R> accumulator,
460 BiConsumer<R, R> combiner);
461
462 /**
463 * Returns the sum of elements in this stream. The sum returned can vary
464 * depending upon the order in which elements are encountered. This is due
465 * to accumulated rounding error in addition of values of differing
466 * magnitudes. Elements sorted by increasing absolute magnitude tend to
467 * yield more accurate results. If any stream element is a {@code NaN} or
468 * the sum is at any point a {@code NaN} then the sum will be {@code NaN}.
469 * This is a special case of a
470 * <a href="package-summary.html#MutableReduction">reduction</a> and is
471 * equivalent to:
472 * <pre>{@code
473 * return reduce(0, Double::sum);
474 * }</pre>
475 *
476 * @return the sum of elements in this stream
477 */
478 double sum();
479
480 /**
481 * Returns an {@code OptionalDouble} describing the minimum element of this
482 * stream, or an empty OptionalDouble if this stream is empty. The minimum
483 * element will be {@code Double.NaN} if any stream element was NaN. Unlike
484 * the numerical comparison operators, this method considers negative zero
485 * to be strictly smaller than positive zero. This is a special case of a
486 * <a href="package-summary.html#MutableReduction">reduction</a> and is
487 * equivalent to:
488 * <pre>{@code
489 * return reduce(Double::min);
490 * }</pre>
491 *
492 * @return an {@code OptionalDouble} containing the minimum element of this
493 * stream, or an empty optional if the stream is empty
494 */
495 OptionalDouble min();
496
497 /**
498 * Returns an {@code OptionalDouble} describing the maximum element of this
499 * stream, or an empty OptionalDouble if this stream is empty. The maximum
500 * element will be {@code Double.NaN} if any stream element was NaN. Unlike
501 * the numerical comparison operators, this method considers negative zero
502 * to be strictly smaller than positive zero. This is a
503 * special case of a
504 * <a href="package-summary.html#MutableReduction">reduction</a> and is
505 * equivalent to:
506 * <pre>{@code
507 * return reduce(Double::max);
508 * }</pre>
509 *
510 * @return an {@code OptionalDouble} containing the maximum element of this
511 * stream, or an empty optional if the stream is empty
512 */
513 OptionalDouble max();
514
515 /**
516 * Returns the count of elements in this stream. This is a special case of
517 * a <a href="package-summary.html#MutableReduction">reduction</a> and is
518 * equivalent to:
519 * <pre>{@code
520 * return mapToLong(e -> 1L).sum();
521 * }</pre>
522 *
523 * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
524 *
525 * @return the count of elements in this stream
526 */
527 long count();
528
529 /**
530 * Returns an {@code OptionalDouble} describing the arithmetic mean of elements of
531 * this stream, or an empty optional if this stream is empty. The average
532 * returned can vary depending upon the order in which elements are
533 * encountered. This is due to accumulated rounding error in addition of
534 * elements of differing magnitudes. Elements sorted by increasing absolute
535 * magnitude tend to yield more accurate results. If any recorded value is
536 * a {@code NaN} or the sum is at any point a {@code NaN} then the average
537 * will be {@code NaN}. This is a special case of a
538 * <a href="package-summary.html#MutableReduction">reduction</a>.
539 *
540 * @return an {@code OptionalDouble} containing the average element of this
541 * stream, or an empty optional if the stream is empty
542 */
543 OptionalDouble average();
544
545 /**
546 * Returns a {@code DoubleSummaryStatistics} describing various summary data
547 * about the elements of this stream. This is a special
548 * case of a <a href="package-summary.html#MutableReduction">reduction</a>.
549 *
550 * @return a {@code DoubleSummaryStatistics} describing various summary data
551 * about the elements of this stream
552 */
553 DoubleSummaryStatistics summaryStatistics();
554
555 /**
556 * Returns whether any elements of this stream match the provided
557 * predicate. May not evaluate the predicate on all elements if not
558 * necessary for determining the result.
559 *
560 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
561 * terminal operation</a>.
562 *
563 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
564 * stateless</a> predicate to apply to elements of this
565 * stream
566 * @return {@code true} if any elements of the stream match the provided
567 * predicate otherwise {@code false}
568 */
569 boolean anyMatch(DoublePredicate predicate);
570
571 /**
572 * Returns whether all elements of this stream match the provided predicate.
573 * May not evaluate the predicate on all elements if not necessary for
574 * determining the result.
575 *
576 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
577 * terminal operation</a>.
578 *
579 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
580 * stateless</a> predicate to apply to elements of this
581 * stream
582 * @return {@code true} if all elements of the stream match the provided
583 * predicate otherwise {@code false}
584 */
585 boolean allMatch(DoublePredicate predicate);
586
587 /**
588 * Returns whether no elements of this stream match the provided predicate.
589 * May not evaluate the predicate on all elements if not necessary for
590 * determining the result.
591 *
592 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
593 * terminal operation</a>.
594 *
595 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
596 * stateless</a> predicate to apply to elements of this
597 * stream
598 * @return {@code true} if no elements of the stream match the provided
599 * predicate otherwise {@code false}
600 */
601 boolean noneMatch(DoublePredicate predicate);
602
603 /**
604 * Returns an {@link OptionalDouble} describing the first element of this
605 * stream (in the encounter order), or an empty {@code OptionalDouble} if
606 * the stream is empty. If the stream has no encounter order, then any
607 * element may be returned.
608 *
609 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
610 * terminal operation</a>.
611 *
612 * @return an {@code OptionalDouble} describing the first element of this
613 * stream, or an empty {@code OptionalDouble} if the stream is empty
614 */
615 OptionalDouble findFirst();
616
617 /**
618 * Returns an {@link OptionalDouble} describing some element of the stream,
619 * or an empty {@code OptionalDouble} if the stream is empty.
620 *
621 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
622 * terminal operation</a>.
623 *
624 * <p>The behavior of this operation is explicitly nondeterministic; it is
625 * free to select any element in the stream. This is to allow for maximal
626 * performance in parallel operations; the cost is that multiple invocations
627 * on the same source may not return the same result. (If the first element
628 * in the encounter order is desired, use {@link #findFirst()} instead.)
629 *
630 * @return an {@code OptionalDouble} describing some element of this stream,
631 * or an empty {@code OptionalDouble} if the stream is empty
632 * @see #findFirst()
633 */
634 OptionalDouble findAny();
635
636 /**
637 * Returns a {@code Stream} consisting of the elements of this stream,
638 * boxed to {@code Double}.
639 *
640 * @return a {@code Stream} consistent of the elements of this stream,
641 * each boxed to a {@code Double}
642 */
643 Stream<Double> boxed();
644
645 @Override
646 DoubleStream sequential();
647
648 @Override
649 DoubleStream parallel();
650
651 @Override
652 PrimitiveIterator.OfDouble iterator();
653
654 @Override
655 Spliterator.OfDouble spliterator();
656
657
658 // Static factories
659
660 /**
661 * Returns a builder for a {@code DoubleStream}.
662 *
663 * @return a stream builder
664 */
665 public static Builder builder() {
666 return new Streams.DoubleStreamBuilderImpl();
667 }
668
669 /**
670 * Returns an empty sequential {@code DoubleStream}.
671 *
672 * @return an empty sequential stream
673 */
674 public static DoubleStream empty() {
675 return StreamSupport.doubleStream(Spliterators.emptyDoubleSpliterator(), false);
676 }
677
678 /**
679 * Returns a sequential {@code DoubleStream} containing a single element.
680 *
681 * @param t the single element
682 * @return a singleton sequential stream
683 */
684 public static DoubleStream of(double t) {
685 return StreamSupport.doubleStream(new Streams.DoubleStreamBuilderImpl(t), false);
686 }
687
688 /**
689 * Returns a sequential stream whose elements are the specified values.
690 *
691 * @param values the elements of the new stream
692 * @return the new stream
693 */
694 public static DoubleStream of(double... values) {
695 return Arrays.stream(values);
696 }
697
698 /**
699 * Returns an infinite sequential {@code DoubleStream} produced by iterative
700 * application of a function {@code f} to an initial element {@code seed},
701 * producing a {@code Stream} consisting of {@code seed}, {@code f(seed)},
702 * {@code f(f(seed))}, etc.
703 *
704 * <p>The first element (position {@code 0}) in the {@code DoubleStream}
705 * will be the provided {@code seed}. For {@code n > 0}, the element at
706 * position {@code n}, will be the result of applying the function {@code f}
707 * to the element at position {@code n - 1}.
708 *
709 * @param seed the initial element
710 * @param f a function to be applied to to the previous element to produce
711 * a new element
712 * @return a new sequential {@code DoubleStream}
713 */
714 public static DoubleStream iterate(final double seed, final DoubleUnaryOperator f) {
715 Objects.requireNonNull(f);
716 final PrimitiveIterator.OfDouble iterator = new PrimitiveIterator.OfDouble() {
717 double t = seed;
718
719 @Override
720 public boolean hasNext() {
721 return true;
722 }
723
724 @Override
725 public double nextDouble() {
726 double v = t;
727 t = f.applyAsDouble(t);
728 return v;
729 }
730 };
731 return StreamSupport.doubleStream(Spliterators.spliteratorUnknownSize(
732 iterator,
733 Spliterator.ORDERED | Spliterator.IMMUTABLE | Spliterator.NONNULL), false);
734 }
735
736 /**
737 * Returns a sequential {@code DoubleStream} where each element is
738 * generated by an {@code DoubleSupplier}. This is suitable for generating
739 * constant streams, streams of random elements, etc.
740 *
741 * @param s the {@code DoubleSupplier} for generated elements
742 * @return a new sequential {@code DoubleStream}
743 */
744 public static DoubleStream generate(DoubleSupplier s) {
745 Objects.requireNonNull(s);
746 return StreamSupport.doubleStream(
747 new StreamSpliterators.InfiniteSupplyingSpliterator.OfDouble(Long.MAX_VALUE, s), false);
748 }
749
750 /**
751 * Creates a lazy concatenated {@code DoubleStream} whose elements are all the
752 * elements of a first {@code DoubleStream} succeeded by all the elements of the
753 * second {@code DoubleStream}. The resulting stream is ordered if both
754 * of the input streams are ordered, and parallel if either of the input
755 * streams is parallel. When the resulting stream is closed, the close
756 * handlers for both input streams is invoked.
757 *
758 * @param a the first stream
759 * @param b the second stream to concatenate on to end of the first stream
760 * @return the concatenation of the two streams
761 */
762 public static DoubleStream concat(DoubleStream a, DoubleStream b) {
763 Objects.requireNonNull(a);
764 Objects.requireNonNull(b);
765
766 Spliterator.OfDouble split = new Streams.ConcatSpliterator.OfDouble(
767 a.spliterator(), b.spliterator());
768 DoubleStream stream = StreamSupport.doubleStream(split, a.isParallel() || b.isParallel());
769 return stream.onClose(Streams.composedClose(a, b));
770 }
771
772 /**
773 * A mutable builder for a {@code DoubleStream}.
774 *
775 * <p>A stream builder has a lifecycle, where it starts in a building
776 * phase, during which elements can be added, and then transitions to a
777 * built phase, after which elements may not be added. The built phase
778 * begins when the {@link #build()} method is called, which creates an
779 * ordered stream whose elements are the elements that were added to the
780 * stream builder, in the order they were added.
781 *
782 * @see DoubleStream#builder()
783 * @since 1.8
784 */
785 public interface Builder extends DoubleConsumer {
786
787 /**
788 * Adds an element to the stream being built.
789 *
790 * @throws IllegalStateException if the builder has already transitioned
791 * to the built state
792 */
793 @Override
794 void accept(double t);
795
796 /**
797 * Adds an element to the stream being built.
798 *
799 * @implSpec
800 * The default implementation behaves as if:
801 * <pre>{@code
802 * accept(t)
803 * return this;
804 * }</pre>
805 *
806 * @param t the element to add
807 * @return {@code this} builder
808 * @throws IllegalStateException if the builder has already transitioned
809 * to the built state
810 */
811 default Builder add(double t) {
812 accept(t);
813 return this;
814 }
815
816 /**
817 * Builds the stream, transitioning this builder to the built state.
818 * An {@code IllegalStateException} is thrown if there are further
819 * attempts to operate on the builder after it has entered the built
820 * state.
821 *
822 * @return the built stream
823 * @throws IllegalStateException if the builder has already transitioned
824 * to the built state
825 */
826 DoubleStream build();
827 }
828 }