Spliterator

[Tim Peierls]

On Tue, Dec 18, 2012 at 10:36 PM, Brian Goetz <brian.goetz at oracle.com>wrote:

> Committed recommended spec and method renamings that follow all of these,
> except changing the return type of getNaturalSplits.  Committed new text
> for getNaturalSplits which hopefully should be acceptable?


If the text below is the latest, then I don't think it's ready yet. In the
first paragraph, 0 means next split return guaranteed empty. In the second
paragraph 0 means further splitting is discouraged, but it doesn't seem to
require next split to return empty. "Discouraged" is a bit vauge, so why
not add a parenthetical clarification at the end of the second paragraph,
e.g., "... discourage further splitting (by advertising that the next call
to split will return an empty Spliterator)."

       51      * Return the number of calls to {@link #split} on this
spliterator that will

       52      * most naturally divide the remaining elements in a
balanced manner.

       53      * If this method returns 0, {@link #split} is
guaranteed to return an

       54      * empty {@code Spliterator}, where empty means also
returning zero from

       55      * {@link #exactSizeIfKnown}.

       56      *

       57      * <p>If it is difficult to ascertain the number of
splits that will result in

       58      * an optimal balance, implementations should return 1
if they wish to encourage

       59      * further splitting and 0 if they wish to discourage further
splitting.