RFR 8071597 Add Stream dropWhile and takeWhile operations

[Chris Hegarty]

I think the original version reads better. Remember that the method summary description contains only the first sentence.

I disagree with the objection about ordering. The stream has some order in which is "sees" elements. That order may be non-deterministic, but it still exists, we just don’t know what it is. takeWhile will still operate on a stream with non-deterministic order, and return the longest prefix, you just don’t know what that is. An appropriate note in the API warning about this should be sufficient.

-Chris.

> On 7 Jun 2015, at 13:57, Paul Sandoz <paul.sandoz at oracle.com> wrote:
> 
> 
> On Jun 6, 2015, at 1:20 AM, Stuart Marks <stuart.marks at oracle.com> wrote:
> 
>> On 6/3/15 9:21 AM, Paul Sandoz wrote:
>>> 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?
>>> 
>>>     /**
>>> -     * 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.
>> 
>> Well, I'm sorry to say, this reminds me of that old tech support joke about the answer that is technically true but completely useless. :-)
>> 
> 
> LOL. It does have a vacuity about it. I would argue it's mostly useless :-)
> 
> Here is another variant:
> 
> /**
> * Returns, if this stream is ordered, a stream consisting of the longest
> * prefix of elements taken from this stream that match the given predicate.
> * Otherwise returns, if this stream is unordered, a stream consisting of a
> * subset of elements taken from this stream that match the given predicate.
> *
> * <p>If this stream is ordered then the longest prefix is a contiguous
> * sequence of elements of this stream that 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 behavior of this operation is
> * nondeterministic; it is free to take any valid subset.
> *
> ...
> */
> default Stream<T> takeWhile(Predicate<? super T> predicate) {
> 
> 
> /**
> * Returns, if this stream is ordered, a stream consisting of the remaining
> * elements of this stream after dropping the longest prefix of elements
> * that match the given predicate.  Otherwise returns, if this stream is
> * unordered, a stream consisting of the remaining elements of this stream
> * after dropping a subset of elements that match the given predicate.
> *
> * <p>If this stream is ordered then the longest prefix is a contiguous
> * sequence of elements of this stream that 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 behavior of this operation is
> * nondeterministic; it is free to drop any valid subset.
> *
> ...
> */
> default Stream<T> dropWhile(Predicate<? super T> predicate) {
> 
> Unless there are strong objects i will stick with that layout.
> 
> Paul.
> 
>> It's not incorrect, of course, but it's almost indistinguishable from the first sentence of Stream.filter().
>> 
>> People who know what "takeWhile" means will raise an eyebrow at this, go read the rest of the doc, and go "ohhh, yeah there's this complication with unordered streams." People who are trying to learn the system will go "Huh?"
>> 
>> I agree on the need for a punchy first sentence since that's what goes into the Method Summary. The difficulty is making something sufficiently general that it covers all the cases, while not making it so vague as to be useless.
>> 
>> Sorry, but I don't have any better suggestions at the moment. I might be able to come up with something in the next few days... but don't let this hold you up if you need to press forward.
>> 
>> s'marks
>