RFR 8020061: Clarify reporting characteristics between splits

[Chris Hegarty]

Thanks Paul. In which case, the spec clarifications seem fine.

-Chris.

On 10/08/2013 02:10 PM, Paul Sandoz wrote:
>
> On Oct 8, 2013, at 3:02 PM, Chris Hegarty <chris.hegarty at oracle.com> wrote:
>
>> Sorry Paul, I know the apiNote says "for examples see ..." but would you mind providing an example. I'm scratching my head.
>>
>
>       * @apiNote Most Spliterators for Collections, that cover all elements of a
>       * {@code Collection} report this characteristic. Sub-spliterators, such as
>       * those for {@link HashSet}, that cover a sub-set of elements and
>       * approximate their reported size do not.
>       */
>      public static final int SIZED      = 0x00000040;
>
>          Set<Integer> s = new HashSet<>(Arrays.asList(1, 2, 3, 4));
>
>          Spliterator<Integer> split1 = s.spliterator();
>          System.out.println(split1.hasCharacteristics(Spliterator.SIZED));
>
>          Spliterator<Integer> split2 = split1.trySplit();
>          System.out.println(split1.hasCharacteristics(Spliterator.SIZED));
>          System.out.println(split2.hasCharacteristics(Spliterator.SIZED));
>
> Paul.
>
>
>> -Chris.
>>
>> On 10/08/2013 12:42 PM, Paul Sandoz wrote:
>>> Hi,
>>>
>>> The following patch is a minor clarification to the documentation of Spliterator.characteristics():
>>>
>>>    http://hg.openjdk.java.net/lambda/lambda/jdk/rev/653d17f35169
>>>
>>> Paul.
>>>
>>> --- a/src/share/classes/java/util/Spliterator.java	Tue Oct 01 12:10:04 2013 +0200
>>> +++ b/src/share/classes/java/util/Spliterator.java	Tue Oct 08 13:36:27 2013 +0200
>>> @@ -414,12 +414,18 @@ public interface Spliterator<T> {
>>>        * #ORDERED}, {@link #DISTINCT}, {@link #SORTED}, {@link #SIZED},
>>>        * {@link #NONNULL}, {@link #IMMUTABLE}, {@link #CONCURRENT},
>>>        * {@link #SUBSIZED}.  Repeated calls to {@code characteristics()} on
>>> -     * a given spliterator should always return the same result.
>>> +     * a given spliterator, prior to or in-between calls to {@code trySplit},
>>> +     * should always return the same result.
>>>        *
>>>        * <p>If a Spliterator reports an inconsistent set of
>>>        * characteristics (either those returned from a single invocation
>>>        * or across multiple invocations), no guarantees can be made
>>>        * about any computation using this Spliterator.
>>> +     *
>>> +     * @apiNote The characteristics of a given spliterator before splitting
>>> +     * may differ from the characteristics after splitting.  For specific
>>> +     * examples see the characteristic values {@link #SIZED}, {@link #SUBSIZED}
>>> +     * and {@link #CONCURRENT}.
>>>        *
>>>        * @return a representation of characteristics
>>>        */
>>>
>