8022797: Clarify spliterator characteristics for collections containing no elements
Reviewed-by: alanb, mduigou
--- a/jdk/src/share/classes/java/util/Collection.java Fri Aug 16 12:46:39 2013 +0200
+++ b/jdk/src/share/classes/java/util/Collection.java Tue Aug 13 11:16:37 2013 +0200
@@ -504,7 +504,10 @@
*
* <p>The returned {@code Spliterator} must report the characteristic
* {@link Spliterator#SIZED}; implementations should document any additional
- * characteristic values reported by the returned Spliterator.
+ * characteristic values reported by the returned spliterator. If
+ * this collection contains no elements then the returned spliterator is
+ * only required to report {@link Spliterator#SIZED} and is not required to
+ * report additional characteristic values (if any).
*
* <p>The default implementation should be overridden by subclasses that
* can return a more efficient spliterator. In order to
@@ -535,6 +538,14 @@
* The returned {@code Spliterator} additionally reports
* {@link Spliterator#SUBSIZED}.
*
+ * <p>If a spliterator covers no elements then the reporting of additional
+ * characteristic values, beyond that of {@code SIZED} and {@code SUBSIZED},
+ * does not aid clients to control, specialize or simplify computation.
+ * However, this does enable shared use of an immutable and empty
+ * spliterator instance (see {@link Spliterators#emptySpliterator()}) for
+ * empty collections, and enables clients to determine if such a spliterator
+ * covers no elements.
+ *
* @return a {@code Spliterator} over the elements in this collection
* @since 1.8
*/