Spliterator

[Brian Goetz]

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?

On 12/18/2012 2:02 PM, Doug Lea wrote:
>
> Having gotten Stream-compatible Spliterators to "work"
> with ConcurrentHashMap view classes (keySet, values, entrySet),
> here's a another try at recommending some reworking of
> the Spliterator interface.
>
> This time, I'm trying hard to make the smallest
> changes that support what Brian et al are already doing.
> (Although changing one of those things.)
> Pasted below (minus top-level javadoc, that would need
> at most a small touch-ip.)
>
> Main issues:
>
> 1. At the moment, unless you implement "sizeIfKnown"
> of top-level Spliterator as non-negative, no splitting
> takes place, even if you implement estimatedSize.
> (Only implementing estimatedSize seemed like the right
> thing to do for CHM; among other reasons because
> its size might change while traversing. But I had
> to lie in getSizeIfKnown to make it do approximately
> the right thing.)
>
> So I tried to clearly spec the cases for
> (renamed) "exactSize" and "estimatedSize", and
> similarly spec (renamed) hasExactSplits.
>
> If we go with this (or even if not), the stream
> implementation should be changed accordingly.
>
> 2. Because split() is stateful, it is unclear at
> best what a return value > 1 for getNaturalSplits
> might mean? All the child splits and their descendents?
> Only the next #getNaturalSplits calls?
> Flailing around left me with the conclusion that
> the only sensible way to spec this is to rename as
> boolean isSplittable(), thus clearly referring only to the
> next call to split.
>
> Comments? Complaints?
>
>
> public interface Spliterator<T> {
>
>      /**
>       * Returns a Spliterator covering some portion of the elements,
>       * guaranteed not to overlap with those retained by this
>       * Spliterator. After invoking this method, the current
>       * Spliterator will <em>not</em> cover the elements of the
>       * returned Spliterator.
>       *
>       * <p>This method may throw an IllegalStateException if a
>       * traversal via {@link #iterator} or {@link @forEach} has already
>       * commenced.
>       *
>       * @return a Spliterator covering the some portion, possibly empty,
> of the
>       * data structure elements.
>       * @throws IllegalStateException if traversal has already commenced
>       */
>      Spliterator<T> split();
>
>      /**
>       * Returns {@code false} if an invocation of {@code split()} is
>       * guaranteed to return an empty Spliterator. Otherwise the method
>       * implementation may choose a return value based on data
>       * structure constraints and efficiency considerations.
>       */
>      boolean isSplittable();
>
>      /**
>       * Return the Iterator covering the remaining elements. The same
>       * iterator instance must be returned for every invocation.  This
>       * method initiates the traversal phase.  <p/>
>       * @return the iterator of the remaining elements.
>       */
>      Iterator<T> iterator();
>
>      /**
>       * Performs the given action for all remaining elements.
>       *
>       * @param block The action
>       */
>      default void forEach(Block<? super T> block) {
>          iterator().forEach(block);
>      }
>
>      /**
>       * Returns the number of elements that would be encountered by an
>       * {@link #iterator} or {@link @forEach} traversal, or returns a
>       * negative value if unknown, or if computing this value may
>       * itself require traversal or significant computation.
>       */
>      default long exactSize() {
>          return -1;
>      }
>
>      /**
>       * Returns an estimate of the number of elements that would be
>       * encountered by an {@link #iterator} or {@link @forEach}
>       * traversal, or returns a negative value if unknown, or if
>       * computing this value may itself require traversal or
>       * significant computation.
>       *
>       * <p>For example, a sub-spliterator of an approximately balanced
>       * tree may return a value that estimates the number of elements
>       * to be half of that of its parent.
>       */
>      default long estimatedSize() {
>          return exactSize();
>      }
>
>      /**
>       * Return {@code true} if the {@link #exactSize} method of this
>       * Spliterator and all of those split from it return non-negative
>       * results.
>       */
>      boolean hasExactSplits();
> }