348 * .peek(e -> System.out.println("Filtered value: " + e));
349 * .map(mappingFunction)
350 * .peek(e -> System.out.println("Mapped value: " + e));
351 * .collect(Collectors.intoList());
352 * }</pre>
353 *
354 * @param action a <a href="package-summary.html#NonInterference">
355 * non-interfering</a> action to perform on the elements as
356 * they are consumed from the stream
357 * @return the new stream
358 */
359 Stream<T> peek(Consumer<? super T> action);
360
361 /**
362 * Returns a stream consisting of the elements of this stream, truncated
363 * to be no longer than {@code maxSize} in length.
364 *
365 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
366 * stateful intermediate operation</a>.
367 *
368 * @param maxSize the number of elements the stream should be limited to
369 * @return the new stream
370 * @throws IllegalArgumentException if {@code maxSize} is negative
371 */
372 Stream<T> limit(long maxSize);
373
374 /**
375 * Returns a stream consisting of the remaining elements of this stream
376 * after discarding the first {@code startInclusive} elements of the stream.
377 * If this stream contains fewer than {@code startInclusive} elements then an
378 * empty stream will be returned.
379 *
380 * <p>This is a <a href="package-summary.html#StreamOps">stateful
381 * intermediate operation</a>.
382 *
383 * @param startInclusive the number of leading elements to skip
384 * @return the new stream
385 * @throws IllegalArgumentException if {@code startInclusive} is negative
386 */
387 Stream<T> substream(long startInclusive);
388
389 /**
390 * Returns a stream consisting of the remaining elements of this stream
391 * after discarding the first {@code startInclusive} elements and truncating
392 * the result to be no longer than {@code endExclusive - startInclusive}
393 * elements in length. If this stream contains fewer than
394 * {@code startInclusive} elements then an empty stream will be returned.
395 *
396 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
397 * stateful intermediate operation</a>.
398 *
399 * @param startInclusive the starting position of the substream, inclusive
400 * @param endExclusive the ending position of the substream, exclusive
401 * @return the new stream
402 * @throws IllegalArgumentException if {@code startInclusive} or
403 * {@code endExclusive} is negative or {@code startInclusive} is greater
404 * than {@code endExclusive}
405 */
406 Stream<T> substream(long startInclusive, long endExclusive);
407
408 /**
409 * Performs an action for each element of this stream.
410 *
411 * <p>This is a <a href="package-summary.html#StreamOps">terminal
412 * operation</a>.
413 *
414 * <p>For parallel stream pipelines, this operation does <em>not</em>
415 * guarantee to respect the encounter order of the stream, as doing so
416 * would sacrifice the benefit of parallelism. For any given element, the
417 * action may be performed at whatever time and in whatever thread the
418 * library chooses. If the action accesses shared state, it is
419 * responsible for providing the required synchronization.
420 *
421 * @param action a <a href="package-summary.html#NonInterference">
422 * non-interfering</a> action to perform on the elements
423 */
424 void forEach(Consumer<? super T> action);
425
426 /**
|
348 * .peek(e -> System.out.println("Filtered value: " + e));
349 * .map(mappingFunction)
350 * .peek(e -> System.out.println("Mapped value: " + e));
351 * .collect(Collectors.intoList());
352 * }</pre>
353 *
354 * @param action a <a href="package-summary.html#NonInterference">
355 * non-interfering</a> action to perform on the elements as
356 * they are consumed from the stream
357 * @return the new stream
358 */
359 Stream<T> peek(Consumer<? super T> action);
360
361 /**
362 * Returns a stream consisting of the elements of this stream, truncated
363 * to be no longer than {@code maxSize} in length.
364 *
365 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
366 * stateful intermediate operation</a>.
367 *
368 * @apiNote
369 * While {@code limit()} is generally a cheap operation on sequential
370 * stream pipelines, it can be quite expensive on ordered parallel pipelines,
371 * especially for large values of {@code maxSize}, since {@code limit(n)}
372 * is constrained to return not just any <em>n</em> elements, but the
373 * <em>first n</em> elements in the encounter order. Using an unordered
374 * stream source (such as {@link #generate(Supplier)}) or removing the
375 * ordering constraint with {@link #unordered()} may result in significant
376 * speedups of {@code limit()} in parallel pipelines, if the semantics of
377 * your situation permit. If consistency with encounter order is required,
378 * and you are experiencing poor performance or memory utilization with
379 * {@code limit()} in parallel pipelines, switching to sequential execution
380 * with {@link #sequential()} may improve performance.
381 *
382 * @param maxSize the number of elements the stream should be limited to
383 * @return the new stream
384 * @throws IllegalArgumentException if {@code maxSize} is negative
385 */
386 Stream<T> limit(long maxSize);
387
388 /**
389 * Returns a stream consisting of the remaining elements of this stream
390 * after discarding the first {@code n} elements of the stream.
391 * If this stream contains fewer than {@code n} elements then an
392 * empty stream will be returned.
393 *
394 * <p>This is a <a href="package-summary.html#StreamOps">stateful
395 * intermediate operation</a>.
396 *
397 * @apiNote
398 * While {@code skip()} is generally a cheap operation on sequential
399 * stream pipelines, it can be quite expensive on ordered parallel pipelines,
400 * especially for large values of {@code n}, since {@code skip(n)}
401 * is constrained to skip not just any <em>n</em> elements, but the
402 * <em>first n</em> elements in the encounter order. Using an unordered
403 * stream source (such as {@link #generate(Supplier)}) or removing the
404 * ordering constraint with {@link #unordered()} may result in significant
405 * speedups of {@code skip()} in parallel pipelines, if the semantics of
406 * your situation permit. If consistency with encounter order is required,
407 * and you are experiencing poor performance or memory utilization with
408 * {@code skip()} in parallel pipelines, switching to sequential execution
409 * with {@link #sequential()} may improve performance.
410 *
411 * @param n the number of leading elements to skip
412 * @return the new stream
413 * @throws IllegalArgumentException if {@code n} is negative
414 */
415 Stream<T> skip(long n);
416
417 /**
418 * Performs an action for each element of this stream.
419 *
420 * <p>This is a <a href="package-summary.html#StreamOps">terminal
421 * operation</a>.
422 *
423 * <p>For parallel stream pipelines, this operation does <em>not</em>
424 * guarantee to respect the encounter order of the stream, as doing so
425 * would sacrifice the benefit of parallelism. For any given element, the
426 * action may be performed at whatever time and in whatever thread the
427 * library chooses. If the action accesses shared state, it is
428 * responsible for providing the required synchronization.
429 *
430 * @param action a <a href="package-summary.html#NonInterference">
431 * non-interfering</a> action to perform on the elements
432 */
433 void forEach(Consumer<? super T> action);
434
435 /**
|