From e77f64d8dda969971d342b1749b4619ce96c232e Mon Sep 17 00:00:00 2001 From: Paul Sandoz Date: Tue, 13 Aug 2013 11:16:37 +0200 Subject: [PATCH] 8022797: Clarify spliterator characteristics for collections containing no elements Reviewed-by: alanb, mduigou --- jdk/src/share/classes/java/util/Collection.java | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/jdk/src/share/classes/java/util/Collection.java b/jdk/src/share/classes/java/util/Collection.java index 7fe7a75bc44..00ddc1035ed 100644 --- a/jdk/src/share/classes/java/util/Collection.java +++ b/jdk/src/share/classes/java/util/Collection.java @@ -504,7 +504,10 @@ public interface Collection extends Iterable { * *

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). * *

The default implementation should be overridden by subclasses that * can return a more efficient spliterator. In order to @@ -535,6 +538,14 @@ public interface Collection extends Iterable { * The returned {@code Spliterator} additionally reports * {@link Spliterator#SUBSIZED}. * + *

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 */