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.IntSummaryStatistics;
28 import java.util.OptionalDouble;
29 import java.util.OptionalInt;
30 import java.util.PrimitiveIterator;
31 import java.util.Spliterator;
32 import java.util.function.BiConsumer;
33 import java.util.function.Function;
34 import java.util.function.IntBinaryOperator;
35 import java.util.function.IntConsumer;
36 import java.util.function.IntFunction;
37 import java.util.function.IntPredicate;
38 import java.util.function.IntToDoubleFunction;
39 import java.util.function.IntToLongFunction;
40 import java.util.function.IntUnaryOperator;
41 import java.util.function.ObjIntConsumer;
42 import java.util.function.Supplier;
43
44 /**
45 * A sequence of primitive integer elements supporting sequential and parallel
46 * bulk operations. Streams support lazy intermediate operations (transforming
47 * a stream to another stream) such as {@code filter} and {@code map}, and terminal
48 * operations (consuming the contents of a stream to produce a result or
49 * side-effect), such as {@code forEach}, {@code findFirst}, and {@code
50 * iterator}. Once an operation has been performed on a stream, it
51 * is considered <em>consumed</em> and no longer usable for other operations.
52 *
53 * <p>For sequential stream pipelines, all operations are performed in the
54 * <a href="package-summary.html#Ordering">encounter order</a> of the pipeline
55 * source, if the pipeline source has a defined encounter order.
56 *
57 * <p>For parallel stream pipelines, unless otherwise specified, intermediate
58 * stream operations preserve the <a href="package-summary.html#Ordering">
59 * encounter order</a> of their source, and terminal operations
60 * respect the encounter order of their source, if the source
61 * has an encounter order. Provided that and parameters to stream operations
62 * satisfy the <a href="package-summary.html#NonInterference">non-interference
63 * requirements</a>, and excepting differences arising from the absence of
64 * a defined encounter order, the result of a stream pipeline should be the
65 * stable across multiple executions of the same operations on the same source.
66 * However, the timing and thread in which side-effects occur (for those
67 * operations which are allowed to produce side-effects, such as
68 * {@link #forEach(IntConsumer)}), are explicitly nondeterministic for parallel
69 * execution of stream pipelines.
70 *
71 * <p>Unless otherwise noted, passing a {@code null} argument to any stream
72 * method may result in a {@link NullPointerException}.
73 *
74 * @apiNote
75 * Streams are not data structures; they do not manage the storage for their
76 * elements, nor do they support access to individual elements. However,
77 * you can use the {@link #iterator()} or {@link #spliterator()} operations to
78 * perform a controlled traversal.
79 *
80 * @since 1.8
81 * @see <a href="package-summary.html">java.util.stream</a>
82 */
83 public interface IntStream extends BaseStream<Integer, IntStream> {
84
85 /**
86 * Returns a stream consisting of the elements of this stream that match
87 * the given predicate.
88 *
89 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
90 * operation</a>.
91 *
92 * @param predicate a <a href="package-summary.html#NonInterference">
93 * non-interfering, stateless</a> predicate to apply to
94 * each element to determine if it should be included
95 * @return the new stream
96 */
97 IntStream filter(IntPredicate predicate);
98
99 /**
100 * Returns a stream consisting of the results of applying the given
101 * function to the elements of this stream.
102 *
103 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
104 * operation</a>.
105 *
106 * @param mapper a <a href="package-summary.html#NonInterference">
107 * non-interfering, stateless</a> function to apply to each
108 * element
109 * @return the new stream
110 */
111 IntStream map(IntUnaryOperator mapper);
112
113 /**
114 * Returns an object-valued {@code Stream} consisting of the results of
115 * applying the given function to the elements of this stream.
116 *
117 * <p>This is an <a href="package-summary.html#StreamOps">
118 * intermediate operation</a>.
119 *
120 * @param <U> the element type of the new stream
121 * @param mapper a <a href="package-summary.html#NonInterference">
122 * non-interfering, stateless</a> function to apply to each
123 * element
124 * @return the new stream
125 */
126 <U> Stream<U> mapToObj(IntFunction<? extends U> mapper);
127
128 /**
129 * Returns a {@code LongStream} consisting of the results of applying the
130 * given function to the elements of this stream.
131 *
132 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
133 * operation</a>.
134 *
135 * @param mapper a <a href="package-summary.html#NonInterference">
136 * non-interfering, stateless</a> function to apply to each
137 * element
138 * @return the new stream
139 */
140 LongStream mapToLong(IntToLongFunction mapper);
141
142 /**
143 * Returns a {@code DoubleStream} consisting of the results of applying the
144 * given function to the elements of this stream.
145 *
146 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
147 * operation</a>.
148 *
149 * @param mapper a <a href="package-summary.html#NonInterference">
150 * non-interfering, stateless</a> function to apply to each
151 * element
152 * @return the new stream
153 */
154 DoubleStream mapToDouble(IntToDoubleFunction mapper);
155
156 /**
157 * Returns a stream consisting of the results of replacing each element of
158 * this stream with the contents of the stream produced by applying the
159 * provided mapping function to each element.
160 *
161 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
162 * operation</a>.
163 *
164 * @apiNote
165 * The {@code flatMap()} operation has the effect of applying a one-to-many
166 * tranformation to the elements of the stream, and then flattening the
167 * resulting elements into a new stream. For example, if {@code orders}
168 * is a stream of purchase orders, and each purchase order contains a
169 * collection of line items, then the following produces a stream of line
170 * items:
171 * <pre>{@code
172 * orderStream.flatMap(order -> order.getLineItems().stream())...
173 * }</pre>
174 *
175 * @param mapper a <a href="package-summary.html#NonInterference">
176 * non-interfering, stateless</a> function to apply to
177 * each element which produces an {@code IntStream} of new
178 * values
179 * @return the new stream
180 * @see Stream#flatMap(Function)
181 */
182 IntStream flatMap(IntFunction<? extends IntStream> mapper);
183
184 /**
185 * Returns a stream consisting of the distinct elements of this stream.
186 *
187 * <p>This is a <a href="package-summary.html#StreamOps">stateful
188 * intermediate operation</a>.
189 *
190 * @return the new stream
191 */
192 IntStream distinct();
193
194 /**
195 * Returns a stream consisting of the elements of this stream in sorted
196 * order.
197 *
198 * <p>This is a <a href="package-summary.html#StreamOps">stateful
199 * intermediate operation</a>.
200 *
201 * @return the new stream
202 */
203 IntStream sorted();
204
205 /**
206 * Returns a stream consisting of the elements of this stream, additionally
207 * performing the provided action on each element as elements are consumed
208 * from the resulting stream.
209 *
210 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
211 * operation</a>.
212 *
213 * <p>For parallel stream pipelines, the action may be called at
214 * whatever time and in whatever thread the element is made available by the
215 * upstream operation. If the action modifies shared state,
216 * it is responsible for providing the required synchronization.
217 *
218 * @apiNote This method exists mainly to support debugging, where you want
219 * to see the elements as they flow past a certain point in a pipeline:
220 * <pre>{@code
221 * list.stream()
222 * .filter(filteringFunction)
223 * .peek(e -> {System.out.println("Filtered value: " + e); });
224 * .map(mappingFunction)
225 * .peek(e -> {System.out.println("Mapped value: " + e); });
226 * .collect(Collectors.toIntSummaryStastistics());
227 * }</pre>
228 *
229 * @param consumer a <a href="package-summary.html#NonInterference">
230 * non-interfering</a> action to perform on the elements as
231 * they are consumed from the stream
232 * @return the new stream
233 */
234 IntStream peek(IntConsumer consumer);
235
236 /**
237 * Returns a stream consisting of the elements of this stream,
238 * truncated to be no longer than {@code maxSize} in length.
239 *
240 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
241 * stateful intermediate operation</a>.
242 *
243 * @param maxSize the number of elements the stream should be limited to
244 * @return the new stream
245 * @throws IllegalArgumentException if {@code maxSize} is negative
246 */
247 IntStream limit(long maxSize);
248
249 /**
250 * Returns a stream consisting of the remaining elements of this stream
251 * after discarding the first {@code startingOffset} elements (or all
252 * elements if the stream has fewer than {@code startingOffset} elements).
253 *
254 * <p>This is a <a href="package-summary.html#StreamOps">stateful
255 * intermediate operation</a>.
256 *
257 * @param startingOffset the number of leading elements to skip
258 * @return the new stream
259 * @throws IllegalArgumentException if {@code startingOffset} is negative
260 */
261 IntStream substream(long startingOffset);
262
263 /**
264 * Returns a stream consisting of the elements of this stream after
265 * discarding the first {@code startingOffset} elements (or all elements
266 * if the stream has fewer than {@code startingOffset} elements), and
267 * truncating the remainder to be no longer than
268 * {@code endingOffset - startOffset} in length.
269 *
270 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
271 * stateful intermediate operation</a>.
272 *
273 * @param startingOffset the starting position of the substream, inclusive
274 * @param endingOffset the ending position of the substream, exclusive
275 * @return the new stream
276 * @throws IllegalArgumentException if {@code startingOffset} or
277 * {@code endingOffset} is negative or {@code startingOffset} is greater
278 * than {@code endingOffset}
279 */
280 IntStream substream(long startingOffset, long endingOffset);
281
282 /**
283 * Performs an action for each element of this stream.
284 *
285 * <p>This is a <a href="package-summary.html#StreamOps">terminal
286 * operation</a>.
287 *
288 * <p>For parallel stream pipelines, this operation does <em>not</em>
289 * guarantee to respect the encounter order of the stream, as doing so
290 * would sacrifice the benefit of parallelism. For any given element, the
291 * action may be performed at whatever time and in whatever thread the
292 * library chooses. If the action accesses shared state, it is
293 * responsible for providing the required synchronization.
294 *
295 * @param action a <a href="package-summary.html#NonInterference">
296 * non-interfering</a> action to perform on the elements
297 */
298 void forEach(IntConsumer action);
299
300 /**
301 * Performs an action for each element of this stream, guaranteeing that
302 * each element is processed in encounter order for streams that have a
303 * defined encounter order.
304 *
305 * <p>This is a <a href="package-summary.html#StreamOps">terminal
306 * operation</a>.
307 *
308 * @param action a <a href="package-summary.html#NonInterference">
309 * non-interfering</a> action to perform on the elements
310 * @see #forEach(IntConsumer)
311 */
312 void forEachOrdered(IntConsumer action);
313
314 /**
315 * Returns an array containing the elements of this stream.
316 *
317 * <p>This is a <a href="package-summary.html#StreamOps">terminal
318 * operation</a>.
319 *
320 * @return an array containing the elements of this stream
321 */
322 int[] toArray();
323
324 /**
325 * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
326 * elements of this stream, using the provided identity value and an
327 * <a href="package-summary.html#Associativity">associative</a>
328 * accumulation function, and returns the reduced value. This is equivalent
329 * to:
330 * <pre>{@code
331 * int result = identity;
332 * for (int element : this stream)
333 * result = accumulator.apply(result, element)
334 * return result;
335 * }</pre>
336 *
337 * but is not constrained to execute sequentially.
338 *
339 * <p>The {@code identity} value must be an identity for the accumulator
340 * function. This means that for all {@code x},
341 * {@code accumulator.apply(identity, x)} is equal to {@code x}.
342 * The {@code accumulator} function must be an
343 * <a href="package-summary.html#Associativity">associative</a> function.
344 *
345 * <p>This is a <a href="package-summary.html#StreamOps">terminal
346 * operation</a>.
347 *
348 * @apiNote Sum, min, max, and average are all special cases of reduction.
349 * Summing a stream of numbers can be expressed as:
350 *
351 * <pre>{@code
352 * int sum = integers.reduce(0, (a, b) -> a+b);
353 * }</pre>
354 *
355 * or more compactly:
356 *
357 * <pre>{@code
358 * int sum = integers.reduce(0, Integer::sum);
359 * }</pre>
360 *
361 * <p>While this may seem a more roundabout way to perform an aggregation
362 * compared to simply mutating a running total in a loop, reduction
363 * operations parallelize more gracefully, without needing additional
364 * synchronization and with greatly reduced risk of data races.
365 *
366 * @param identity the identity value for the accumulating function
367 * @param op an <a href="package-summary.html#Associativity">associative</a>
368 * <a href="package-summary.html#NonInterference">non-interfering,
369 * stateless</a> function for combining two values
370 * @return the result of the reduction
371 * @see #sum()
372 * @see #min()
373 * @see #max()
374 * @see #average()
375 */
376 int reduce(int identity, IntBinaryOperator op);
377
378 /**
379 * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
380 * elements of this stream, using an
381 * <a href="package-summary.html#Associativity">associative</a> accumulation
382 * function, and returns an {@code OptionalInt} describing the reduced value,
383 * if any. This is equivalent to:
384 * <pre>{@code
385 * boolean foundAny = false;
386 * int result = null;
387 * for (int element : this stream) {
388 * if (!foundAny) {
389 * foundAny = true;
390 * result = element;
391 * }
392 * else
393 * result = accumulator.apply(result, element);
394 * }
395 * return foundAny ? OptionalInt.of(result) : OptionalInt.empty();
396 * }</pre>
397 *
398 * but is not constrained to execute sequentially.
399 *
400 * <p>The {@code accumulator} function must be an
401 * <a href="package-summary.html#Associativity">associative</a> function.
402 *
403 * <p>This is a <a href="package-summary.html#StreamOps">terminal
404 * operation</a>.
405 *
406 * @param op an <a href="package-summary.html#Associativity">associative</a>
407 * <a href="package-summary.html#NonInterference">non-interfering,
408 * stateless</a> function for combining two values
409 * @return the result of the reduction
410 * @see #reduce(int, IntBinaryOperator)
411 */
412 OptionalInt reduce(IntBinaryOperator op);
413
414 /**
415 * Performs a <a href="package-summary.html#MutableReduction">mutable
416 * reduction</a> operation on the elements of this stream. A mutable
417 * reduction is one in which the reduced value is a mutable value holder,
418 * such as an {@code ArrayList}, and elements are incorporated by updating
419 * the state of the result, rather than by replacing the result. This
420 * produces a result equivalent to:
421 * <pre>{@code
422 * R result = resultFactory.get();
423 * for (int element : this stream)
424 * accumulator.accept(result, element);
425 * return result;
426 * }</pre>
427 *
428 * <p>Like {@link #reduce(int, IntBinaryOperator)}, {@code collect} operations
429 * can be parallelized without requiring additional synchronization.
430 *
431 * <p>This is a <a href="package-summary.html#StreamOps">terminal
432 * operation</a>.
433 *
434 * @param <R> type of the result
435 * @param resultFactory a function that creates a new result container.
436 * For a parallel execution, this function may be
437 * called multiple times and must return a fresh value
438 * each time.
439 * @param accumulator an <a href="package-summary.html#Associativity">associative</a>
440 * <a href="package-summary.html#NonInterference">non-interfering,
441 * stateless</a> function for incorporating an additional
442 * element into a result
443 * @param combiner an <a href="package-summary.html#Associativity">associative</a>
444 * <a href="package-summary.html#NonInterference">non-interfering,
445 * stateless</a> function for combining two values, which
446 * must be compatible with the accumulator function
447 * @return the result of the reduction
448 * @see Stream#collect(Supplier, BiConsumer, BiConsumer)
449 */
450 <R> R collect(Supplier<R> resultFactory,
451 ObjIntConsumer<R> accumulator,
452 BiConsumer<R, R> combiner);
453
454 /**
455 * Returns the sum of elements in this stream. This is a special case
456 * of a <a href="package-summary.html#MutableReduction">reduction</a>
457 * and is equivalent to:
458 * <pre>{@code
459 * return reduce(0, Integer::sum);
460 * }</pre>
461 *
462 * @return the sum of elements in this stream
463 */
464 int sum();
465
466 /**
467 * Returns an {@code OptionalInt} describing the minimum element of this
468 * stream, or an empty optional if this stream is empty. This is a special
469 * case of a <a href="package-summary.html#MutableReduction">reduction</a>
470 * and is equivalent to:
471 * <pre>{@code
472 * return reduce(Integer::min);
473 * }</pre>
474 *
475 * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
476 *
477
478 * @return an {@code OptionalInt} containing the minimum element of this
479 * stream, or an empty {@code OptionalInt} if the stream is empty
480 */
481 OptionalInt min();
482
483 /**
484 * Returns an {@code OptionalInt} describing the maximum element of this
485 * stream, or an empty optional if this stream is empty. This is a special
486 * case of a <a href="package-summary.html#MutableReduction">reduction</a>
487 * and is equivalent to:
488 * <pre>{@code
489 * return reduce(Integer::max);
490 * }</pre>
491 *
492 * <p>This is a <a href="package-summary.html#StreamOps">terminal
493 * operation</a>.
494 *
495 * @return an {@code OptionalInt} containing the maximum element of this
496 * stream, or an empty {@code OptionalInt} if the stream is empty
497 */
498 OptionalInt max();
499
500 /**
501 * Returns the count of elements in this stream. This is a special case of
502 * a <a href="package-summary.html#MutableReduction">reduction</a> and is
503 * equivalent to:
504 * <pre>{@code
505 * return mapToLong(e -> 1L).sum();
506 * }</pre>
507 *
508 * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
509 *
510 * @return the count of elements in this stream
511 */
512 long count();
513
514 /**
515 * Returns an {@code OptionalDouble} describing the average of elements of
516 * this stream, or an empty optional if this stream is empty. This is a
517 * special case of a
518 * <a href="package-summary.html#MutableReduction">reduction</a>.
519 *
520 * @return an {@code OptionalDouble} containing the average element of this
521 * stream, or an empty optional if the stream is empty
522 */
523 OptionalDouble average();
524
525 /**
526 * Returns an {@code IntSummaryStatistics} describing various
527 * summary data about the elements of this stream. This is a special
528 * case of a <a href="package-summary.html#MutableReduction">reduction</a>.
529 *
530 * @return an {@code IntSummaryStatistics} describing various summary data
531 * about the elements of this stream
532 */
533 IntSummaryStatistics summaryStatistics();
534
535 /**
536 * Returns whether any elements of this stream match the provided
537 * predicate. May not evaluate the predicate on all elements if not
538 * necessary for determining the result.
539 *
540 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
541 * terminal operation</a>.
542 *
543 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
544 * stateless</a> predicate to apply to elements of this
545 * stream
546 * @return {@code true} if any elements of the stream match the provided
547 * predicate otherwise {@code false}
548 */
549 boolean anyMatch(IntPredicate predicate);
550
551 /**
552 * Returns whether all elements of this stream match the provided predicate.
553 * May not evaluate the predicate on all elements if not necessary for
554 * determining the result.
555 *
556 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
557 * terminal operation</a>.
558 *
559 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
560 * stateless</a> predicate to apply to elements of this
561 * stream
562 * @return {@code true} if all elements of the stream match the provided
563 * predicate otherwise {@code false}
564 */
565 boolean allMatch(IntPredicate predicate);
566
567 /**
568 * Returns whether no elements of this stream match the provided predicate.
569 * May not evaluate the predicate on all elements if not necessary for
570 * determining the result.
571 *
572 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
573 * terminal operation</a>.
574 *
575 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
576 * stateless</a> predicate to apply to elements of this
577 * stream
578 * @return {@code true} if no elements of the stream match the provided
579 * predicate otherwise {@code false}
580 */
581 boolean noneMatch(IntPredicate predicate);
582
583 /**
584 * Returns an {@link OptionalInt} describing the first element of this
585 * stream (in the encounter order), or an empty {@code OptionalInt} if the
586 * stream is empty. If the stream has no encounter order, than any element
587 * may be returned.
588 *
589 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
590 * terminal operation</a>.
591 *
592 * @return an {@code OptionalInt} describing the first element of this stream,
593 * or an empty {@code OptionalInt} if the stream is empty
594 */
595 OptionalInt findFirst();
596
597 /**
598 * Returns an {@link OptionalInt} describing some element of the stream, or
599 * an empty {@code OptionalInt} if the stream is empty.
600 *
601 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
602 * terminal operation</a>.
603 *
604 * <p>The behavior of this operation is explicitly nondeterministic; it is
605 * free to select any element in the stream. This is to allow for maximal
606 * performance in parallel operations; the cost is that multiple invocations
607 * on the same source may not return the same result. (If the first element
608 * in the encounter order is desired, use {@link #findFirst()} instead.)
609 *
610 * @return an {@code OptionalInt} describing some element of this stream, or
611 * an empty {@code OptionalInt} if the stream is empty
612 * @see #findFirst()
613 */
614 OptionalInt findAny();
615
616 /**
617 * Returns a {@code LongStream} consisting of the elements of this stream,
618 * converted to {@code long}.
619 *
620 * @return a {@code LongStream} consisting of the elements of this stream,
621 * converted to {@code long}
622 */
623 LongStream longs();
624
625 /**
626 * Returns a {@code DoubleStream} consisting of the elements of this stream,
627 * converted to {@code double}.
628 *
629 * @return a {@code DoubleStream} consisting of the elements of this stream,
630 * converted to {@code double}
631 */
632 DoubleStream doubles();
633
634 /**
635 * Returns a {@code Stream} consisting of the elements of this stream,
636 * each boxed to an {@code Integer}.
637 *
638 * @return a {@code Stream} consistent of the elements of this stream,
639 * each boxed to an {@code Integer}
640 */
641 Stream<Integer> boxed();
642
643 @Override
644 IntStream sequential();
645
646 @Override
647 IntStream parallel();
648
649 @Override
650 PrimitiveIterator.OfInt iterator();
651
652 @Override
653 Spliterator.OfInt spliterator();
654 }