Hi,
Please review these specification clarifications to the methods
Iterator.forEachRemaining and Iterator.remove.
Implementations of Iterator.forEachRemaining should have some wiggle room to
optimize traversal. (In hindsight we could have done a better job locking such
behaviour down in Java 8.)
I also took the opportunity to update the Iterable.forEach method.
Thanks,
Paul.
diff -r 4bf7aaa0d611 src/java.base/share/classes/java/lang/Iterable.java
--- a/src/java.base/share/classes/java/lang/Iterable.java Thu Nov 17
12:24:51 2016 -0800
+++ b/src/java.base/share/classes/java/lang/Iterable.java Mon Nov 21
10:55:21 2016 -0800
@@ -53,10 +53,12 @@
/**
* Performs the given action for each element of the {@code Iterable}
* until all elements have been processed or the action throws an
- * exception. Unless otherwise specified by the implementing class,
- * actions are performed in the order of iteration (if an iteration order
- * is specified). Exceptions thrown by the action are relayed to the
+ * 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 behaviour of this method is unspecified if the action performs
+ * side-effects that modify the underlying source of elements.
*
* @implSpec
* <p>The default implementation behaves as if:
diff -r 4bf7aaa0d611 src/java.base/share/classes/java/util/Iterator.java
--- a/src/java.base/share/classes/java/util/Iterator.java Thu Nov 17
12:24:51 2016 -0800
+++ b/src/java.base/share/classes/java/util/Iterator.java Mon Nov 21
10:55:21 2016 -0800
@@ -76,10 +76,15 @@
/**
* Removes from the underlying collection the last element returned
* by this iterator (optional operation). This method can be called
- * only once per call to {@link #next}. The behavior of an iterator
- * is unspecified if the underlying collection is modified while the
- * iteration is in progress in any way other than by calling this
- * method.
+ * only once per call to {@link #next}.
+ * <p>
+ * The behavior of an iterator is unspecified if:
+ * <ul>
+ * <li>the underlying collection is modified while the iteration is in
+ * progress in any way other than by calling this method; or
+ * <li>this method is called after a call to the
+ * {@link #forEachRemaining forEachRemaining} method.
+ * </ul>
*
* @implSpec
* The default implementation throws an instance of
@@ -102,6 +107,16 @@
* 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 performs the
+ * following side-effects:
+ * <ul>
+ * <li>modifies the underlying collection; or
+ * <li>calls the {@link #remove remove} method.
+ * </ul>
+ * <p>
+ * Subsequent behavior of an iterator is unspecified if the action throws
an
+ * exception.
*
* @implSpec
* <p>The default implementation behaves as if:
