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

[Stuart Marks]

On Tue, 1 Jun 2021 19:54:59 GMT, Paul Sandoz <psandoz 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.

Generally, adding the "unspecified after an exception" clause in those places seems to be the correct thing to do here.

Marked as reviewed by smarks (Reviewer).

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"?

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

Changes requested by smarks (Reviewer).

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