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