On 12/08/2013 16:24, Paul Sandoz wrote:
Hi,
Here is another go at characteristics reported for spliterators of empty
collections:
diff -r f8d92ce66886 src/share/classes/java/util/Collection.java
--- a/src/share/classes/java/util/Collection.java Mon Aug 12 13:59:01
2013 +0200
+++ b/src/share/classes/java/util/Collection.java Mon Aug 12 16:12:10
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 characteristics (if any).
*
*<p>The default implementation should be overridden by subclasses that
* can return a more efficient spliterator. In order to
@@ -535,6 +538,13 @@
* The returned {@code Spliterator} additionally reports
* {@link Spliterator#SUBSIZED}.
*
+ *<p>If a spliterator covers no elements then the reporting of additional
+ * characteristics, 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 empty spliterator (see
+ * {@link Spliterators#emptySpliterator()} for empty collections, and
+ * enables clients to determine if a spliterator covers no elements.
+ *
* @return a {@code Spliterator} over the elements in this collection
* @since 1.8
*/
It might be preferable to also document this on List/Set/SortedSet since the
documentation is overridden and i don't think we have many precedents for
overriding what the sub-types define (are there any?).
--
I logged issue 8022805 for Stream.concat(s, Stream.emptyStream()).
Paul.
The wording looks okay to me except "specialize" -> "specialization".
When the spec is overridden then it would require clicks on the link
under the "Specified by" but I think that should be okay here.
-Alan.
