8022797: Clarify spliterator characteristics for collections containing no elements
authorpsandoz
Tue, 13 Aug 2013 11:16:37 +0200
changeset 19424 c4524285927f
parent 19423 19249161b340
child 19425 fdde8b1f0397
child 19600 fce5c0729a1c
8022797: Clarify spliterator characteristics for collections containing no elements Reviewed-by: alanb, mduigou
jdk/src/share/classes/java/util/Collection.java
--- 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
      */