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 <[email protected]> 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
>
