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