RFR 8022797 Clarify spliterator characteristics for collections containing no elements

[Paul Sandoz]

On Aug 12, 2013, at 8:25 PM, Alan Bateman <Alan.Bateman at oracle.com> wrote:

> 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".
> 

Thanks there is a comma missing, it should be:

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

Paul.