changeset 8127:7b2f8860caed

reflow of some of the javadoc and minor changes.
author mduigou
date Mon, 15 Apr 2013 20:30:49 -0700
parents 53c48bc81402
children 966728ca3642
files src/share/classes/java/util/Spliterator.java
diffstat 1 files changed, 65 insertions(+), 73 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/Spliterator.java	Mon Apr 15 19:29:29 2013 -0700
+++ b/src/share/classes/java/util/Spliterator.java	Mon Apr 15 20:30:49 2013 -0700
@@ -390,6 +390,20 @@
     long estimateSize();
 
     /**
+     * Convenience method that returns {@link #estimateSize()} if this
+     * Spliterator is {@link #SIZED}, else {@code -1}.
+     * @implSpec
+     * The default returns the result of {@code estimateSize()} if the
+     * Spliterator reports a characteristic of {@code SIZED}, and {@code -1}
+     * otherwise.
+     *
+     * @return the exact size, if known, else {@code -1}.
+     */
+    default long getExactSizeIfKnown() {
+        return (characteristics() & SIZED) == 0 ? -1L : estimateSize();
+    }
+
+    /**
      * Returns a set of characteristics of this Spliterator and its
      * elements. The result is represented as ORed values from {@link
      * #ORDERED}, {@link #DISTINCT}, {@link #SORTED}, {@link #SIZED},
@@ -423,9 +437,9 @@
 
     /**
      * If this Spliterator's source is {@link #SORTED} by a {@link Comparator},
-     * returns that {@code Comparator}.  If the source is {@code SORTED}
-     * naturally, returns {@code null}.  Otherwise, if the source is not
-     * {@code SORTED}, throws {@link IllegalStateException}.
+     * returns that {@code Comparator}. If the source is {@code SORTED} in
+     * {@linkplain Comparable natural order, returns {@code null}.  Otherwise,
+     * if the source is not {@code SORTED}, throws {@link IllegalStateException}.
      *
      * @implSpec
      * The default implementation always throws {@link IllegalStateException}.
@@ -440,38 +454,22 @@
     }
 
     /**
-     * Convenience method that returns {@link #estimateSize()} if this
-     * Spliterator is {@link #SIZED}, else {@code -1}.
-     * @implSpec
-     * The default returns the result of {@code estimateSize()} if the
-     * Spliterator reports a characteristic of {@code SIZED}, and {@code -1}
-     * otherwise.
-     *
-     * @return the exact size, if known, else {@code -1}.
-     */
-    default long getExactSizeIfKnown() {
-        return (characteristics() & SIZED) == 0 ? -1L : estimateSize();
-    }
-
-    /**
-     * Characteristic value signifying that an encounter order is
-     * defined for elements.  If so, this Spliterator guarantees that
-     * method {@link #trySplit} splits a strict prefix of elements,
-     * that method {@link #tryAdvance} steps by one element in prefix
-     * order, and that {@link #forEachRemaining} performs actions in encounter
-     * order.
+     * Characteristic value signifying that an encounter order is defined for
+     * elements. If so, this Spliterator guarantees that method
+     * {@link #trySplit} splits a strict prefix of elements, that method
+     * {@link #tryAdvance} steps by one element in prefix order, and that
+     * {@link #forEachRemaining} performs actions in encounter order.
      *
      * <p>A {@link Collection} has an encounter order if the corresponding
-     * {@link Collection#iterator} documents an order.  If so, the encounter
-     * order is the same as the documented order.  Otherwise, a collection does
+     * {@link Collection#iterator} documents an order. If so, the encounter
+     * order is the same as the documented order. Otherwise, a collection does
      * not have an encounter order.
      *
-     * @apiNote
-     * Encounter order is guaranteed to be ascending index order
-     * for any {@link List}.  But no order is guaranteed for hash-based
-     * collections such as {@link HashSet}.  Clients of a Spliterator that
-     * reports {@code ORDERED} are expected to preserve ordering constraints
-     * in non-commutative parallel computations.
+     * @apiNote Encounter order is guaranteed to be ascending index order for
+     * any {@link List}. But no order is guaranteed for hash-based collections
+     * such as {@link HashSet}. Clients of a Spliterator that reports
+     * {@code ORDERED} are expected to preserve ordering constraints in
+     * non-commutative parallel computations.
      */
     public static final int ORDERED    = 0x00000010;
 
@@ -483,18 +481,16 @@
     public static final int DISTINCT   = 0x00000001;
 
     /**
-     * Characteristic value signifying that encounter order follows a
-     * defined sort order. If so, method {@link #getComparator()}
-     * returns the associated Comparator, or {@code null} if all
-     * elements are {@link Comparable} and are sorted by their
-     * natural ordering.
+     * Characteristic value signifying that encounter order follows a defined
+     * sort order. If so, method {@link #getComparator()} returns the associated
+     * Comparator, or {@code null} if all elements are {@link Comparable} and
+     * are sorted by their natural ordering.
      *
      * <p>A Spliterator that reports {@code SORTED} must also report
      * {@code ORDERED}.
      *
-     * @apiNote
-     * The spliterators for {@code Collection} classes in the JDK that
-     * extend {@link NavigableSet} or {@link SortedSet} report {@code SORTED}.
+     * @apiNote The spliterators for {@code Collection} classes in the JDK that
+     * implement {@link NavigableSet} or {@link SortedSet} report {@code SORTED}.
      */
     public static final int SORTED     = 0x00000004;
 
@@ -505,11 +501,10 @@
      * represents an exact count of the number of elements that would be
      * encountered by a complete traversal.
      *
-     * @apiNote
-     * Most Spliterators, based on Collections, that cover all elements of a
-     * 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.
+     * @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;
 
@@ -521,37 +516,35 @@
     public static final int NONNULL    = 0x00000100;
 
     /**
-     * Characteristic value signifying that the element source cannot
-     * be structurally modified; that is, elements cannot be added,
-     * replaced, or removed, so such changes cannot occur during
-     * traversal. A Spliterator that does not report {@code IMMUTABLE}
-     * or {@code CONCURRENT} is expected to have a documented policy
-     * (for example throwing {@link ConcurrentModificationException})
-     * concerning structural interference detected during traversal.
+     * Characteristic value signifying that the element source cannot be
+     * structurally modified; that is, elements cannot be added, replaced, or
+     * removed, so such changes cannot occur during traversal. A Spliterator
+     * that does not report {@code IMMUTABLE} or {@code CONCURRENT} is expected
+     * to have a documented policy (for example throwing
+     * {@link ConcurrentModificationException}) concerning structural
+     * interference detected during traversal.
      */
     public static final int IMMUTABLE  = 0x00000400;
 
     /**
-     * Characteristic value signifying that the element source may be
-     * safely concurrently modified (allowing additions, replacements,
-     * and/or removals) by multiple threads without external
-     * synchronization. If so, the Spliterator is expected to have a
-     * documented policy concerning the impact of modifications during
-     * traversal.
+     * Characteristic value signifying that the element source may be safely
+     * concurrently modified (allowing additions, replacements, and/or removals)
+     * by multiple threads without external synchronization. If so, the
+     * Spliterator is expected to have a documented policy concerning the impact
+     * of modifications during traversal.
      *
      * <p>A top-level Spliterator should not report {@code CONCURRENT} and
-     * {@code SIZED}, since the finite size, if known, may change if the
-     * source is concurrently modified during traversal.  Such a Spliterator
-     * is inconsistent and no guarantees can be made about any computation
-     * using that Spliterator.  Sub-spliterators may report {@code SIZED} if
-     * the sub-split size is known and additions or removals to the source
-     * are not reflected when traversing.
+     * {@code SIZED}, since the finite size, if known, may change if the source
+     * is concurrently modified during traversal. Such a Spliterator is
+     * inconsistent and no guarantees can be made about any computation using
+     * that Spliterator. Sub-spliterators may report {@code SIZED} if the
+     * sub-split size is known and additions or removals to the source are not
+     * reflected when traversing.
      *
-     * @apiNote
-     * Most concurrent collections maintain a consistency policy guaranteeing
-     * accuracy with respect to elements present at the point of Spliterator
-     * construction, but possibly not reflecting subsequent additions or
-     * removals.
+     * @apiNote Most concurrent collections maintain a consistency policy
+     * guaranteeing accuracy with respect to elements present at the point of
+     * Spliterator construction, but possibly not reflecting subsequent
+     * additions or removals.
      */
     public static final int CONCURRENT = 0x00001000;
 
@@ -565,11 +558,10 @@
      * {@code SUBSIZED} is inconsistent and no guarantees can be made about any
      * computation using that Spliterator.
      *
-     * @apiNote
-     * Some spliterators, such as the top-level spliterator for an approximately
-     * balanced binary tree, will report {@code SIZED} but not {@code SUBSIZED},
-     * since it is common to know the size of the entire tree but not the exact
-     * sizes of subtrees.
+     * @apiNote Some spliterators, such as the top-level spliterator for an
+     * approximately balanced binary tree, will report {@code SIZED} but not
+     * {@code SUBSIZED}, since it is common to know the size of the entire tree
+     * but not the exact sizes of subtrees.
      */
     public static final int SUBSIZED = 0x00004000;