On Jun 6, 2015, at 1:20 AM, Stuart Marks <[email protected]> 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
