RFR: 8025910 : (s) rename substream(long) -> skip and substream(long, long) -> slice

[Paul Sandoz]

On Oct 9, 2013, at 5:38 AM, Mike Duigou <mike.duigou at oracle.com> wrote:

> Hello all;
> 
> Based upon feedback from the JavaOne Hands-On-Lab and other sources the 335 EG has decided to rename the two substream methods in the Streams interfaces to skip and slice.
> 
> Webrev:
> 
> http://cr.openjdk.java.net/~mduigou/JDK-8025910/0/webrev/
> 
> and the specdiff:
> 
> http://cr.openjdk.java.net/~mduigou/JDK-8025910/0/specdiff/overview-summary.html
> 
> Thanks, 
> 

Looks ok, but I have a preference to change the parameter name from "startInclusive" to say "n":

    /**
     * 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 startInclusive} is negative
     */
    Stream<T> skip(long n);

Paul.