RFR 8014824: Document Spliterator characteristics and binding policy of java util collection impls

[Paul Sandoz]

Hi Peter,

On Aug 8, 2013, at 12:44 PM, Peter Levart <peter.levart at gmail.com> wrote:

> Hi Paul,
> 
> Shouldn't Spliterators.EmptySpliterator also be IMMUTABLE, DISTINCT and ORDERED? Like Collections.singletonSpliterator...
> 

Perhaps, for consistency. IIRC at the time it was felt a little odd to declare such characteristics when no elements are present.


> Although a mutable Collection implementation or immutable with size()>1 can never be Set and List at the same time, A singleton immutable Collection I think could be. Likewise for empty immutable Collection... So why couldn't a spliterator obtained from singleton List be DISTINCT? Likewise why couldn't a spliterator obtained from singleton Set be ORDERED?...

That could be an option, but i was hesitant about explicitly stating such optional constraints on Set/List.

For the current Collection implementations i would prefer not to enforce the reporting of characteristics for a size of 0 or 1.


> These are runtime characteristics, not characteristics of a particular collection type.
> 

For N > 1 I would argue characteristics of top-level spliterators do map to a particular collection type. Nearly all of the characteristics for at most one element are irrelevant for optimizing computation (SIZED/SUBSIZED/IMMUTABLE/NONULL are probably the most useful of the not very useful). It's almost as if nothing == everything in this case i.e. reporting no/few characteristics is the same as reporting all/most characteristics :-)

There is now Collections.emptyNavigableMap/emptySortedMap implying SORTED should also be reported for the empty spliterator, unless we optionally constrain SortedSet. 

There are currently no type safe ways to obtain a singleton NavigableMap/SortedSet, but perhaps there could be in the future? (there was probably a good reason for not adding them with the empty versions but i dunno what that reason was). Reporting SORTED for all singletons is problematic because the singleton element may not be Comparable.

So i thought rather than attempting to be explicit about 0 or 1 element and the type holding that element it was just easier all round to do some hand-waving on Collections or Collection i.e. all bets are off as to what characteristics are reported (beyond that of SIZED/SUBSIZED/IMMUTABLE/NONNULL?) and it does not matter cause you will anyway not be able to to anything useful with them.

--

Perhaps i can separate out this webrev, i presume there is little issue with the other doc updates, if so i can commit those for this bug and spin up another for this aspect.

Paul.