src/share/classes/java/util/stream/IntStream.java
Print this page
rev 8376 : 8025910: rename substream(long) -> skip and remove substream(long,long)
Reviewed-by: duke
*** 285,333 ****
* to be no longer than {@code maxSize} in length.
*
* <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
* stateful intermediate operation</a>.
*
* @param maxSize the number of elements the stream should be limited to
* @return the new stream
* @throws IllegalArgumentException if {@code maxSize} is negative
*/
IntStream limit(long maxSize);
/**
* Returns a stream consisting of the remaining elements of this stream
! * after discarding the first {@code startInclusive} elements of the stream.
! * If this stream contains fewer than {@code startInclusive} elements then an
* empty stream will be returned.
*
* <p>This is a <a href="package-summary.html#StreamOps">stateful
* intermediate operation</a>.
*
! * @param startInclusive the number of leading elements to skip
! * @return the new stream
! * @throws IllegalArgumentException if {@code startInclusive} is negative
! */
! IntStream substream(long startInclusive);
!
! /**
! * Returns a stream consisting of the remaining elements of this stream
! * after discarding the first {@code startInclusive} elements and truncating
! * the result to be no longer than {@code endExclusive - startInclusive}
! * elements in length. If this stream contains fewer than
! * {@code startInclusive} elements then an empty stream will be returned.
! *
! * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
! * stateful intermediate operation</a>.
*
! * @param startInclusive the starting position of the substream, inclusive
! * @param endExclusive the ending position of the substream, exclusive
* @return the new stream
! * @throws IllegalArgumentException if {@code startInclusive} or
! * {@code endExclusive} is negative or {@code startInclusive} is greater
! * than {@code endExclusive}
*/
! IntStream substream(long startInclusive, long endExclusive);
/**
* Performs an action for each element of this stream.
*
* <p>This is a <a href="package-summary.html#StreamOps">terminal
--- 285,342 ----
* to be no longer than {@code maxSize} in length.
*
* <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
* stateful intermediate operation</a>.
*
+ * @apiNote
+ * While {@code limit()} is generally a cheap operation on sequential
+ * stream pipelines, it can be quite expensive on ordered parallel pipelines,
+ * especially for large values of {@code maxSize}, since {@code limit(n)}
+ * is constrained to return not just any <em>n</em> elements, but the
+ * <em>first n</em> elements in the encounter order. Using an unordered
+ * stream source (such as {@link #generate(IntSupplier)}) or removing the
+ * ordering constraint with {@link #unordered()} may result in significant
+ * speedups of {@code limit()} in parallel pipelines, if the semantics of
+ * your situation permit. If consistency with encounter order is required,
+ * and you are experiencing poor performance or memory utilization with
+ * {@code limit()} in parallel pipelines, switching to sequential execution
+ * with {@link #sequential()} may improve performance.
+ *
* @param maxSize the number of elements the stream should be limited to
* @return the new stream
* @throws IllegalArgumentException if {@code maxSize} is negative
*/
IntStream limit(long maxSize);
/**
* Returns a stream consisting of the remaining elements of this stream
! * after discarding the first {@code n} elements of the stream.
! * If this stream contains fewer than {@code n} elements then an
* empty stream will be returned.
*
* <p>This is a <a href="package-summary.html#StreamOps">stateful
* intermediate operation</a>.
*
! * @apiNote
! * While {@code skip()} is generally a cheap operation on sequential
! * stream pipelines, it can be quite expensive on ordered parallel pipelines,
! * especially for large values of {@code n}, since {@code skip(n)}
! * is constrained to skip not just any <em>n</em> elements, but the
! * <em>first n</em> elements in the encounter order. Using an unordered
! * stream source (such as {@link #generate(Supplier)}) or removing the
! * ordering constraint with {@link #unordered()} may result in significant
! * speedups of {@code skip()} in parallel pipelines, if the semantics of
! * your situation permit. If consistency with encounter order is required,
! * and you are experiencing poor performance or memory utilization with
! * {@code skip()} in parallel pipelines, switching to sequential execution
! * with {@link #sequential()} may improve performance.
*
! * @param n the number of leading elements to skip
* @return the new stream
! * @throws IllegalArgumentException if {@code n} is negative
*/
! IntStream skip(long n);
/**
* Performs an action for each element of this stream.
*
* <p>This is a <a href="package-summary.html#StreamOps">terminal