8267939: Clarify the specification of iterator and spliterator forEachRemaining

Reviewed-by: smarks
This commit is contained in:
Paul Sandoz 2021-06-03 22:03:35 +00:00
parent 460ce5553c
commit c1f3094f81
2 changed files with 27 additions and 28 deletions
src/java.base/share/classes/java/util

@ -68,10 +68,18 @@ import java.util.function.LongConsumer;
public interface PrimitiveIterator<T, T_CONS> extends Iterator<T> {
/**
* Performs the given action for each remaining element, in the order
* elements occur when iterating, until all elements have been processed
* or the action throws an exception. Errors or runtime exceptions
* thrown by the action are relayed to the caller.
* 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.
* Exceptions thrown by the action are relayed to the caller.
* <p>
* 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 or other mutator methods of {@code Iterator} subtypes),
* unless an overriding class has specified a concurrent modification policy.
* <p>
* Subsequent behavior of an iterator is unspecified if the action throws an
* exception.
*
* @param action The action to be performed for each element
* @throws NullPointerException if the specified action is null
@ -94,20 +102,13 @@ public interface PrimitiveIterator<T, T_CONS> extends Iterator<T> {
int nextInt();
/**
* 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.
* Exceptions thrown by the action are relayed to the caller.
*
* {@inheritDoc}
* @implSpec
* <p>The default implementation behaves as if:
* <pre>{@code
* while (hasNext())
* action.accept(nextInt());
* }</pre>
*
* @param action The action to be performed for each element
* @throws NullPointerException if the specified action is null
*/
default void forEachRemaining(IntConsumer action) {
Objects.requireNonNull(action);
@ -168,20 +169,13 @@ public interface PrimitiveIterator<T, T_CONS> extends Iterator<T> {
long nextLong();
/**
* 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.
* Exceptions thrown by the action are relayed to the caller.
*
* {@inheritDoc}
* @implSpec
* <p>The default implementation behaves as if:
* <pre>{@code
* while (hasNext())
* action.accept(nextLong());
* }</pre>
*
* @param action The action to be performed for each element
* @throws NullPointerException if the specified action is null
*/
default void forEachRemaining(LongConsumer action) {
Objects.requireNonNull(action);
@ -241,20 +235,13 @@ public interface PrimitiveIterator<T, T_CONS> extends Iterator<T> {
double nextDouble();
/**
* 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.
* Exceptions thrown by the action are relayed to the caller.
*
* {@inheritDoc}
* @implSpec
* <p>The default implementation behaves as if:
* <pre>{@code
* while (hasNext())
* action.accept(nextDouble());
* }</pre>
*
* @param action The action to be performed for each element
* @throws NullPointerException if the specified action is null
*/
default void forEachRemaining(DoubleConsumer action) {
Objects.requireNonNull(action);

@ -300,6 +300,9 @@ public interface Spliterator<T> {
* Spliterator is {@link #ORDERED} the action is performed on the
* next element in encounter order. Exceptions thrown by the
* action are relayed to the caller.
* <p>
* Subsequent behavior of a spliterator is unspecified if the action throws
* an exception.
*
* @param action The action
* @return {@code false} if no remaining elements existed
@ -314,6 +317,9 @@ public interface Spliterator<T> {
* throws an exception. If this Spliterator is {@link #ORDERED}, actions
* are performed in encounter order. Exceptions thrown by the action
* are relayed to the caller.
* <p>
* Subsequent behavior of a spliterator is unspecified if the action throws
* an exception.
*
* @implSpec
* The default implementation repeatedly invokes {@link #tryAdvance} until
@ -613,6 +619,9 @@ public interface Spliterator<T> {
* Spliterator is {@link #ORDERED} the action is performed on the
* next element in encounter order. Exceptions thrown by the
* action are relayed to the caller.
* <p>
* Subsequent behavior of a spliterator is unspecified if the action throws
* an exception.
*
* @param action The action
* @return {@code false} if no remaining elements existed
@ -628,6 +637,9 @@ public interface Spliterator<T> {
* action throws an exception. If this Spliterator is {@link #ORDERED},
* actions are performed in encounter order. Exceptions thrown by the
* action are relayed to the caller.
* <p>
* Subsequent behavior of a spliterator is unspecified if the action throws
* an exception.
*
* @implSpec
* The default implementation repeatedly invokes {@link #tryAdvance}