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.san...@oracle.com> wrote:
>
>
> On Jun 6, 2015, at 1:20 AM, Stuart Marks <stuart.ma...@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
>
