RFR: 8267939: Clarify the specification of iterator and spliterator forEachRemaining

[Stuart Marks]

On Tue, 1 Jun 2021 22:40:53 GMT, Paul Sandoz <psandoz at openjdk.org> wrote:

>> src/java.base/share/classes/java/util/PrimitiveIterator.java line 77:
>> 
>>> 75:      * <p>
>>> 76:      * The behavior of an iterator is unspecified if the action modifies the
>>> 77:      * collection in any way (even by calling the {@link #remove remove} method
>> 
>> It's kind of odd to mention "the collection" here. Iterator is defined as being over a collection, but strictly speaking this isn't true; it can be an iterator over anything. PrimitiveIterator doesn't say anything more specific than this, just that it's a base for iterating primitives... and collections cannot contain primitives.
>> 
>> I'm not sure what a better term for this is. Something like, "the underlying source of the Iterator"?
>
> Yeah, well spotted. I agree it's awkward. How about we lean on the behavior of the boxed counterpart:
> 
>     /**
>      * Performs the given action for each remaining element until all elements
>      * have been processed or the action throws an exception.  Actions are
>      * performed in the order of iteration, if that order is specified.
>      * <p>
>      * This primitive-based method conforms to the same behavior as its
>      * boxed counterpart with regards to the action's behavior.
> ?

Referring to the "boxed counterpart" is a bit too oblique, I think. The specification of Iterator itself isn't all that good to begin with. It's written as if the only possible source of an Iterator is a collection (which might have been true at first, but it isn't true any longer). But the rest of the Iterator spec refers to "the collection" so it kind of makes sense in that context.

Maybe just making a minimal change from "collection" to "source of elements" would make the most sense.

     * The behavior of an iterator is unspecified if the action modifies the source of
     * elements in any way (even by calling the {@link #remove remove} method

-------------

PR: https://git.openjdk.java.net/jdk/pull/4290