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

[Paul Sandoz]

On Tue, 1 Jun 2021 21:34:10 GMT, Stuart Marks <smarks at openjdk.org> wrote:

>> The specification of `forEachRemaining`, accepting a primitive functional interface, on the primitive iterators is updated to be the same as for `Iterator.forEachRemaining`, specifically the following is added:
>> 
>> 
>>      * <p>
>>      * Subsequent behavior of an iterator is unspecified if the action throws an
>>      * exception.
>> 
>> 
>> In addition the specification of `tryAdvance` and `forEachRemaining` on `Spliterator` and the primitive specializations are also updated to include a similar statement:
>> 
>> 
>>      * Subsequent behavior of a spliterator is unspecified if the action throws
>>      * an exception.
>
> 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.
?

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

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