RFR 8020061: Clarify reporting characteristics between splits

2013-10-08 Thread Paul Sandoz 
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 SpliteratorT {
  * #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.
  *
  * pIf 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
  */

Re: RFR 8020061: Clarify reporting characteristics between splits

2013-10-08 Thread Chris Hegarty 
Sorry Paul, I know the apiNote says for examples see ... but would you 
mind providing an example. I'm scratching my head.


-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 SpliteratorT {
   * #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.
   *
   * pIf 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
   */

Re: RFR 8020061: Clarify reporting characteristics between splits

2013-10-08 Thread Paul Sandoz 

On Oct 8, 2013, at 3:02 PM, Chris Hegarty chris.hega...@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  = 0x0040;

SetInteger s = new HashSet(Arrays.asList(1, 2, 3, 4));

SpliteratorInteger split1 = s.spliterator();
System.out.println(split1.hasCharacteristics(Spliterator.SIZED));

SpliteratorInteger 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 SpliteratorT {
   * #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.
   *
   * pIf 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
   */

Re: RFR 8020061: Clarify reporting characteristics between splits

2013-10-08 Thread 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.hega...@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  = 0x0040;

 SetInteger s = new HashSet(Arrays.asList(1, 2, 3, 4));

 SpliteratorInteger split1 = s.spliterator();
 System.out.println(split1.hasCharacteristics(Spliterator.SIZED));

 SpliteratorInteger 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 SpliteratorT {
   * #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.
   *
   * pIf 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
   */