80 * as {@link Stream#count()} or {@link Stream#forEach(Consumer)}). |
80 * as {@link Stream#count()} or {@link Stream#forEach(Consumer)}). |
81 * Streams are lazy; computation on the source data is only performed when the |
81 * Streams are lazy; computation on the source data is only performed when the |
82 * terminal operation is initiated, and source elements are consumed only |
82 * terminal operation is initiated, and source elements are consumed only |
83 * as needed. |
83 * as needed. |
84 * |
84 * |
|
85 * <p>A stream implementation is permitted significant latitude in optimizing |
|
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 * strean package documentation.) |
|
97 * |
85 * <p>Collections and streams, while bearing some superficial similarities, |
98 * <p>Collections and streams, while bearing some superficial similarities, |
86 * have different goals. Collections are primarily concerned with the efficient |
99 * have different goals. Collections are primarily concerned with the efficient |
87 * management of, and access to, their elements. By contrast, streams do not |
100 * management of, and access to, their elements. By contrast, streams do not |
88 * provide a means to directly access or manipulate their elements, and are |
101 * provide a means to directly access or manipulate their elements, and are |
89 * instead concerned with declaratively describing their source and the |
102 * instead concerned with declaratively describing their source and the |
412 * .peek(e -> System.out.println("Filtered value: " + e)) |
425 * .peek(e -> System.out.println("Filtered value: " + e)) |
413 * .map(String::toUpperCase) |
426 * .map(String::toUpperCase) |
414 * .peek(e -> System.out.println("Mapped value: " + e)) |
427 * .peek(e -> System.out.println("Mapped value: " + e)) |
415 * .collect(Collectors.toList()); |
428 * .collect(Collectors.toList()); |
416 * }</pre> |
429 * }</pre> |
|
430 * |
|
431 * <p>In cases where stream implementation is able to optimize away the |
|
432 * production of some or all the elements (such as with short-circuiting |
|
433 * operations like {@code findFirst}, or in the example described in |
|
434 * {@link #count}), the action will not be invoked for those elements. |
417 * |
435 * |
418 * @param action a <a href="package-summary.html#NonInterference"> |
436 * @param action a <a href="package-summary.html#NonInterference"> |
419 * non-interfering</a> action to perform on the elements as |
437 * non-interfering</a> action to perform on the elements as |
420 * they are consumed from the stream |
438 * they are consumed from the stream |
421 * @return the new stream |
439 * @return the new stream |