RFR 8071597 Add Stream dropWhile and takeWhile operations

[Paul Sandoz]

Hi Stuart,

I had prepared an alternative rendition stashed away just in case this came up :-)

I still want to retain a punchy short first paragraph. What do you think about the following?

     Stream<T> skip(long n);
 
     /**
-     * Returns a stream consisting of the longest prefix of elements taken from
-     * this stream that match the given predicate.
+     * Returns a stream consisting of elements taken from this stream that match
+     * the given predicate.
      *
-     * <p>If this stream is ordered then the prefix is a contiguous sequence of
-     * elements of this stream.  All elements of the sequence match the given
-     * predicate, the first element of the sequence is the first element
-     * (if any) of this stream, and the element (if any) immediately following
-     * the last element of the sequence does not match the given predicate.
+     * <p>If this stream is ordered then the longest prefix of elements is
+     * taken from this stream.  The prefix is a contiguous sequence of elements
+     * of this stream. All elements of the sequence match the given predicate.
+     * The first element of the sequence is the first element (if any) of this
+     * stream, and the element (if any) immediately following the last element
+     * of the sequence does not match the given predicate.
      *
-     * <p>If this stream is unordered then the prefix is a subset of elements of
+     * <p>If this stream is unordered then a subset of elements is taken from
      * this stream.  All elements (if any) of the subset match the given
      * predicate.  In this case the behavior of this operation is
-     * nondeterministic; it is free to select any valid subset as the prefix.
+     * nondeterministic; it is free to take any valid subset.
      *
      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
      * stateful intermediate operation</a>.
@@ -521,8 +522,8 @@
      *
      * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
      *                  <a href="package-summary.html#Statelessness">stateless</a>
-     *                  predicate to apply to elements to determine the longest
-     *                  prefix of elements.
+     *                  predicate to apply to elements to determine if they
+     *                  should be taken.
      * @return the new stream
      */
     default Stream<T> takeWhile(Predicate<? super T> predicate) {
@@ -535,20 +536,20 @@
     }
 
     /**
-     * Returns a stream consisting of the remaining elements of this stream
-     * after dropping the longest prefix of elements that match the given
-     * predicate.
+     * Returns a stream consistent of the remaining elements of this stream
+     * after dropping elements that match the given predicate.
      *
-     * <p>If this stream is ordered then the prefix is a contiguous sequence of
-     * elements of this stream.  All elements of the sequence match the given
-     * predicate, the first element of the sequence is the first element
-     * (if any) of this stream, and the element (if any) immediately following
-     * the last element of the sequence does not match the given predicate.
+     * <p>If this stream is ordered then the longest prefix of elements is
+     * dropped from this stream.  The prefix is a contiguous sequence of
+     * elements of this stream. All elements of the sequence match the given
+     * predicate. The first element of the sequence is the first element (if
+     * any) of this stream, and the element (if any) immediately following the
+     * last element of the sequence does not match the given predicate.
      *
-     * <p>If this stream is unordered then the prefix is a subset of elements of
+     * <p>If this stream is unordered then a subset of elements is dropped from
      * this stream.  All elements (if any) of the subset match the given
      * predicate.  In this case the behavior of this operation is
-     * nondeterministic; it is free to select any valid subset as the prefix.
+     * nondeterministic; it is free to take any valid subset.
      *
      * <p>This is a <a href="package-summary.html#StreamOps">stateful
      * intermediate operation</a>.
@@ -577,8 +578,8 @@
      *
      * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
      *                  <a href="package-summary.html#Statelessness">stateless</a>
-     *                  predicate to apply to elements to determine the longest
-     *                  prefix of elements.
+     *                  predicate to apply to elements to determine if they
+     *                  should be dropped.
      * @return the new stream
      */
     default Stream<T> dropWhile(Predicate<? super T> predicate) {

Paul.

On Jun 3, 2015, at 4:05 AM, Stuart Marks <stuart.marks at oracle.com> wrote:

> Hi Paul,
> 
> Some comments on the spec.
> 
> On 6/2/15 6:13 AM, Paul Sandoz wrote:
>>   http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8071597-take-drop-while/webrev/
>> 
>> I opted to weight the documentation of the operations towards ordered streams in the first paragraph. That is what makes most sense in terms of usage and what most people will read. Thus i refer to the "longest prefix" in the first paragraph then define what that means in subsequent paragraphs for ordered and unordered streams:
> 
> I see what you're trying to do here. The first sentence of a doc comment is special and so it needs to describe concisely but very generally what the method is trying to do.
> 
> The problem is that the first sentence is flatly contradicted by the third paragraph. If the stream is unordered "longest prefix" is completely ill-defined. "Prefix" is nonsensical for an unordered stream, but the third paragraph attempts to redefine it to fit. "Longest" doesn't apply, since any subset may be returned.
> 
> Maybe the thing to do just give up on the idea of the first sentence trying to cover the semantics for both ordered and unordered streams. The problem is that something like "takeWhile" is really mostly applicable to ordered streams, so in the first paragraph just give people what they're expecting to see. Then have the second paragraph cover the case of unordered streams.
> 
> Maybe something like this:
> 
> ----------
> If this stream is ordered, returns a stream consisting of the longest prefix of elements taken from this stream, where the elements all match the given predicate. The prefix is a contiguous sequence of elements of this stream.  The first element of the sequence is the first element (if any) of this stream, and the element (if any) immediately following the last element of the sequence does not match the given predicate.
> 
> If this stream is unordered, this method returns a subset of elements of this stream.  All elements (if any) of the subset match the given predicate.  In this case the behavior of this operation is nondeterministic; it is free to select any valid subset of elements that match the predicate.
> ----------
> 
> s'marks
>