changeset 7578:9d1608e74301

Docs on Spliterators.
author psandoz
date Fri, 08 Mar 2013 15:07:50 +0100
parents 5344e45a16c5
children 35b2aa2ab27c
files src/share/classes/java/util/Spliterators.java
diffstat 1 files changed, 204 insertions(+), 137 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/Spliterators.java	Fri Mar 08 14:04:14 2013 +0100
+++ b/src/share/classes/java/util/Spliterators.java	Fri Mar 08 15:07:50 2013 +0100
@@ -30,27 +30,53 @@
 import java.util.function.LongConsumer;
 
 /**
- * This class contains various methods that operate on or return instances of {@link Spliterator}.
+ * This class contains various methods that operate on or create instances of
+ * {@link Spliterator}, as well as the primitive specializations
+ * {@link Spliterator.OfInt}, {@link Spliterator.OfLong}, and
+ * {@link Spliterator.OfDouble}.
+ *
+ * @since 1.8
  */
-public class Spliterators {
+public final class Spliterators {
 
     // Suppresses default constructor, ensuring non-instantiability.
     private Spliterators() {}
 
     // Empty spliterators
 
+    /**
+     * Creates an empty {@code Spliterator}
+     *
+     * @param <T> Type of elements
+     * @return An empty {@code Spliterator}
+     */
     public static <T> Spliterator<T> emptySpliterator() {
         return new EmptySpliterator<>();
     }
 
+    /**
+     * Creates an empty {@code Spliterator.OfInt}
+     *
+     * @return An empty {@code Spliterator.OfInt}
+     */
     public static Spliterator.OfInt emptyIntSpliterator() {
         return new EmptySpliterator.OfInt();
     }
 
+    /**
+     * Creates an empty {@code Spliterator.OfLong}
+     *
+     * @return An empty {@code Spliterator.OfLong}
+     */
     public static Spliterator.OfLong emptyLongSpliterator() {
         return new EmptySpliterator.OfLong();
     }
 
+    /**
+     * Creates an empty {@code Spliterator.OfDouble}
+     *
+     * @return An empty {@code Spliterator.OfDouble}
+     */
     public static Spliterator.OfDouble emptyDoubleSpliterator() {
         return new EmptySpliterator.OfDouble();
     }
@@ -58,29 +84,31 @@
     // Array-based spliterators
 
     /**
-     * Creates a new Spliterator covering all of the given array.
+     * Creates a new {@code Spliterator} covering all of the given array.
      *
-     * @param array the array, assumed to be unmodified during use
-     * @param characteristics properties of this spliterator's
-     * source or elements ({@code SIZED} and {@code SUBSIZED}
-     * are always reported, so need not be supplied.)
-     * @since 1.8
+     * @param array The array, assumed to be unmodified during use
+     * @param characteristics Properties of this spliterator's source or
+     *        elements ({@code SIZED} and {@code SUBSIZED} are always reported,
+     *        so need not be supplied.)
+     * @param <T> Type of elements
+     * @return A new spliterator from an array
      */
     public static <T> Spliterator<T> spliterator(Object[] array, int characteristics) {
         return new ArraySpliterator<>(array, characteristics);
     }
 
     /**
-     * Creates a new Spliterator covering the given range of the given
+     * Creates a new {@code Spliterator} covering the given range of the given
      * array.
      *
-     * @param array the array, assumed to be unmodified during use
-     * @param origin the least index (inclusive) to cover
-     * @param fence one past the greatest index to cover
-     * @param characteristics properties of this spliterator's
-     * source or elements ({@code SIZED} and {@code SUBSIZED}
-     * are always reported, so need not be supplied.)
-     * @since 1.8
+     * @param array The array, assumed to be unmodified during use
+     * @param origin The least index (inclusive) to cover
+     * @param fence One past the greatest index to cover
+     * @param characteristics Properties of this spliterator's source or
+     *        elements ({@code SIZED} and {@code SUBSIZED} are always reported,
+     *        so need not be supplied.)
+     * @param <T> Type of elements
+     * @return A new spliterator from an array
      */
     public static <T> Spliterator<T> spliterator(Object[] array, int origin, int fence, int characteristics) {
         checkFromToBounds(array.length, origin, fence);
@@ -88,29 +116,29 @@
     }
 
     /**
-     * Creates a new Spliterator.OfInt covering all of the given array.
+     * Creates a new {@code Spliterator.OfInt} covering all of the given array.
      *
-     * @param array the array, assumed to be unmodified during use
-     * @param characteristics properties of this spliterator's
-     * source or elements ({@code SIZED} and {@code SUBSIZED}
-     * are always reported, so need not be supplied.)
-     * @since 1.8
+     * @param array The array, assumed to be unmodified during use
+     * @param characteristics Properties of this spliterator's source or
+     *        elements ({@code SIZED} and {@code SUBSIZED} are always reported,
+     *        so need not be supplied.)
+     * @return A new spliterator from an array
      */
     public static Spliterator.OfInt spliterator(int[] array, int characteristics) {
         return new IntArraySpliterator(array, characteristics);
     }
 
     /**
-     * Creates a new Spliterator.OfInt covering the given range of the given
-     * array.
+     * Creates a new {@code Spliterator.OfInt} covering the given range of the
+     * given array.
      *
-     * @param array the array, assumed to be unmodified during use
-     * @param origin the least index (inclusive) to cover
-     * @param fence one past the greatest index to cover
-     * @param characteristics properties of this spliterator's
-     * source or elements ({@code SIZED} and {@code SUBSIZED}
-     * are always reported, so need not be supplied.)
-     * @since 1.8
+     * @param array The array, assumed to be unmodified during use
+     * @param origin The least index (inclusive) to cover
+     * @param fence One past the greatest index to cover
+     * @param characteristics Properties of this spliterator's source or
+     *        elements ({@code SIZED} and {@code SUBSIZED} are always reported,
+     *        so need not be supplied.)
+     * @return A new spliterator from an array
      */
     public static Spliterator.OfInt spliterator(int[] array, int origin, int fence, int characteristics) {
         checkFromToBounds(array.length, origin, fence);
@@ -118,29 +146,29 @@
     }
 
     /**
-     * Creates a new Spliterator.OfLong covering all of the given array.
+     * Creates a new {@code Spliterator.OfLong} covering all of the given array.
      *
-     * @param array the array, assumed to be unmodified during use
-     * @param characteristics properties of this spliterator's
-     * source or elements ({@code SIZED} and {@code SUBSIZED}
-     * are always reported, so need not be supplied.)
-     * @since 1.8
+     * @param array The array, assumed to be unmodified during use
+     * @param characteristics Properties of this spliterator's source or
+     *        elements ({@code SIZED} and {@code SUBSIZED} are always reported,
+     *        so need not be supplied.)
+     * @return A new spliterator from an array
      */
     public static Spliterator.OfLong spliterator(long[] array, int characteristics) {
         return new LongArraySpliterator(array, characteristics);
     }
 
     /**
-     * Creates a new Spliterator.OfLong covering the given range of the given
-     * array.
+     * Creates a new {@code Spliterator.OfLong} covering the given range of the
+     * given array.
      *
-     * @param array the array, assumed to be unmodified during use
-     * @param origin the least index (inclusive) to cover
-     * @param fence one past the greatest index to cover
-     * @param characteristics properties of this spliterator's
-     * source or elements ({@code SIZED} and {@code SUBSIZED}
-     * are always reported, so need not be supplied.)
-     * @since 1.8
+     * @param array The array, assumed to be unmodified during use
+     * @param origin The least index (inclusive) to cover
+     * @param fence One past the greatest index to cover
+     * @param characteristics Properties of this spliterator's source or
+     *        elements ({@code SIZED} and {@code SUBSIZED} are always reported,
+     *        so need not be supplied.)
+     * @return A new spliterator from an array
      */
     public static Spliterator.OfLong spliterator(long[] array, int origin, int fence, int characteristics) {
         checkFromToBounds(array.length, origin, fence);
@@ -148,29 +176,30 @@
     }
 
     /**
-     * Creates a new Spliterator.OfDouble covering all of the given array.
+     * Creates a new {@code Spliterator.OfDouble} covering all of the given
+     * array.
      *
-     * @param array the array, assumed to be unmodified during use
-     * @param characteristics properties of this spliterator's
-     * source or elements ({@code SIZED} and {@code SUBSIZED}
-     * are always reported, so need not be supplied.)
-     * @since 1.8
+     * @param array The array, assumed to be unmodified during use
+     * @param characteristics Properties of this spliterator's source or
+     *        elements ({@code SIZED} and {@code SUBSIZED} are always reported,
+     *        so need not be supplied.)
+     * @return A new spliterator from an array
      */
     public static Spliterator.OfDouble spliterator(double[] array, int characteristics) {
         return new DoubleArraySpliterator(array, characteristics);
     }
 
     /**
-     * Creates a new Spliterator.OfDouble covering the given range of the given
-     * array.
+     * Creates a new {@code Spliterator.OfDouble} covering the given range of
+     * the given array.
      *
-     * @param array the array, assumed to be unmodified during use
-     * @param origin the least index (inclusive) to cover
-     * @param fence one past the greatest index to cover
-     * @param characteristics properties of this spliterator's
-     * source or elements ({@code SIZED} and {@code SUBSIZED}
-     * are always reported, so need not be supplied.)
-     * @since 1.8
+     * @param array The array, assumed to be unmodified during use
+     * @param origin The least index (inclusive) to cover
+     * @param fence One past the greatest index to cover
+     * @param characteristics Properties of this spliterator's source or
+     *        elements ({@code SIZED} and {@code SUBSIZED} are always reported,
+     *        so need not be supplied.)
+     * @return A new spliterator from an array
      */
     public static Spliterator.OfDouble spliterator(double[] array, int origin, int fence, int characteristics) {
         checkFromToBounds(array.length, origin, fence);
@@ -193,139 +222,145 @@
     // Iterator-based spliterators
 
     /**
-     * Returns a new basic Spliterator using the given collection's
+     * Creates a new basic {@code Spliterator} using the given collection's
      * {@link java.util.Collection#iterator()} for traversal, and reporting its
      * {@link java.util.Collection#size()} as its initial size.  The spliterator
-     * implements {@code trySplit} to permit limited parallelism.
+     * is <em>last-binding</em> and implements {@code trySplit} to permit
+     * limited parallelism.
      *
-     * @param c the collection
-     * @param characteristics properties of this spliterator's
-     * source or elements.
-     * @since 1.8
+     * @param c The collection
+     * @param characteristics Properties of this spliterator's source or
+     *        elements.
+     * @param <T> Type of elements
+     * @return A new basic spliterator from an iterator
      */
     public static <T> Spliterator<T> spliterator(Collection<T> c, int characteristics) {
         return new IteratorSpliterator<>(c, characteristics);
     }
 
     /**
-     * Returns a new basic Spliterator using a given Iterator for
-     * element operations, and with a given initially reported
-     * size. The spliterator implements {@code trySplit} to permit
-     * limited parallelism.
+     * Creates a new basic {@code Spliterator} using a given {@code Iterator}
+     * for element operations, and with a given initially reported size.  The
+     * spliterator implements {@code trySplit} to permit limited parallelism.
      *
-     * @param iterator the iterator for the source
-     * @param size the number of elements in the source, to be reported
-     * as initial {@code estimateSize}.
-     * @param characteristics properties of this spliterator's
-     * source or elements.
-     * @since 1.8
+     * @param iterator The iterator for the source
+     * @param size The number of elements in the source, to be reported as
+     *        initial {@code estimateSize}
+     * @param characteristics Properties of this spliterator's source or
+     *        elements
+     * @param <T> Type of elements
+     * @return A new basic spliterator from an iterator
      */
     public static <T> Spliterator<T> spliterator(Iterator<T> iterator, long size, int characteristics) {
         return new IteratorSpliterator<>(iterator, size, characteristics);
     }
 
     /**
-     * Returns a basic Spliterator using a given Iterator for element
-     * operations, with no initial size estimate. The spliterator
+     * Creates a new basic {@code Spliterator} using a given {@code Iterator}
+     * for element operations, with no initial size estimate.  The spliterator
      * implements {@code trySplit} to permit limited parallelism.
      *
-     * @param iterator the iterator for the source
-     * @param characteristics properties of this spliterator's
-     * source or elements.
-     * @since 1.8
+     * @param iterator The iterator for the source
+     * @param characteristics Properties of this spliterator's source or
+     *        elements
+     * @param <T> Type of elements
+     * @return A new basic spliterator from an iterator
      */
     public static <T> Spliterator<T> spliteratorUnknownSize(Iterator<T> iterator, int characteristics) {
         return new IteratorSpliterator<>(iterator, characteristics);
     }
 
     /**
-     * Returns a new basic Spliterator.OfInt using a given IntStream.IntIterator for
-     * element operations, and with a given initially reported
-     * size. The spliterator implements {@code trySplit} to permit
-     * limited parallelism.
+     * Creates a new basic {@code Spliterator.OfInt} using a given
+     * {@code IntStream.IntIterator} for element operations, and with a given
+     * initially reported size.  The spliterator implements {@code trySplit} to
+     * permit limited parallelism.
      *
-     * @param iterator the iterator for the source
-     * @param size the number of elements in the source, to be reported
-     * as initial {@code estimateSize}.
-     * @param characteristics properties of this spliterator's
-     * source or elements.
-     * @since 1.8
+     * @param iterator The iterator for the source
+     * @param size The number of elements in the source, to be reported as
+     *        initial {@code estimateSize}.
+     * @param characteristics Properties of this spliterator's source or
+     *        elements
+     * @return A new basic spliterator from an iterator
      */
     public static Spliterator.OfInt spliterator(PrimitiveIterator.OfInt iterator, long size, int characteristics) {
         return new IntIteratorSpliterator(iterator, size, characteristics);
     }
 
     /**
-     * Returns a basic Spliterator.OfInt using a given IntStream.IntIterator for element
-     * operations, with no initial size estimate. The spliterator
-     * implements {@code trySplit} to permit limited parallelism.
+     * Creates a new basic {@code Spliterator.OfInt} using a given
+     * {@code IntStream.IntIterator} for element operations, with no initial
+     * size estimate.  The spliterator implements {@code trySplit} to permit
+     * limited parallelism.
      *
-     * @param iterator the iterator for the source
-     * @param characteristics properties of this spliterator's
-     * source or elements.
-     * @since 1.8
+     * @param iterator The iterator for the source
+     * @param characteristics Properties of this spliterator's source or
+     *        elements
+     * @return A new basic spliterator from an iterator
      */
     public static Spliterator.OfInt spliteratorUnknownSize(PrimitiveIterator.OfInt iterator, int characteristics) {
         return new IntIteratorSpliterator(iterator, characteristics);
     }
 
     /**
-     * Returns a new basic Spliterator.OfLong using a given LongStream.LongIterator for
-     * element operations, and with a given initially reported
-     * size. The spliterator implements {@code trySplit} to permit
-     * limited parallelism.
+     * Creates a new basic {@code Spliterator.OfLong} using a given
+     * {@code LongStream.LongIterator} for element operations, and with a given
+     * initially reported size.  The spliterator implements {@code trySplit} to
+     * permit limited parallelism.
      *
-     * @param iterator the iterator for the source
-     * @param size the number of elements in the source, to be reported
-     * as initial {@code estimateSize}.
-     * @param characteristics properties of this spliterator's
-     * source or elements.
-     * @since 1.8
+     * @param iterator The iterator for the source
+     * @param size The number of elements in the source, to be reported as
+     *        initial {@code estimateSize}.
+     * @param characteristics Properties of this spliterator's source or
+     *        elements
+     * @return A new basic spliterator from an iterator
      */
     public static Spliterator.OfLong spliterator(PrimitiveIterator.OfLong iterator, long size, int characteristics) {
         return new LongIteratorSpliterator(iterator, size, characteristics);
     }
 
     /**
-     * Returns a basic Spliterator.OfLong using a given LongStream.LongIterator for element
-     * operations, with no initial size estimate. The spliterator
-     * implements {@code trySplit} to permit limited parallelism.
+     * Creates a new basic {@code Spliterator.OfLong} using a given
+     * {@code LongStream.LongIterator} for element operations, with no initial
+     * size estimate.  The spliterator implements {@code trySplit} to permit
+     * limited parallelism.
      *
-     * @param iterator the iterator for the source
-     * @param characteristics properties of this spliterator's
-     * source or elements.
-     * @since 1.8
+     * @param iterator The iterator for the source
+     * @param characteristics Properties of this spliterator's source or
+     *        elements
+     * @return A new basic spliterator from an iterator
      */
     public static Spliterator.OfLong spliteratorUnknownSize(PrimitiveIterator.OfLong iterator, int characteristics) {
         return new LongIteratorSpliterator(iterator, characteristics);
     }
 
     /**
-     * Returns a new basic Spliterator.OfDouble using a given DoubleStream.DoubleIterator for
-     * element operations, and with a given initially reported
-     * size. The spliterator implements {@code trySplit} to permit
-     * limited parallelism.
+     * Creates a new basic {@code Spliterator.OfDouble} using a given
+     * {@code DoubleStream.DoubleIterator} for element operations, and with a
+     * given initially reported size.  The spliterator implements
+     * {@code trySplit} to permit limited parallelism.
      *
-     * @param iterator the iterator for the source
-     * @param size the number of elements in the source, to be reported
-     * as initial {@code estimateSize}.
-     * @param characteristics properties of this spliterator's
-     * source or elements.
-     * @since 1.8
+     * @param iterator The iterator for the source
+     * @param size The number of elements in the source, to be reported as
+     *        initial {@code estimateSize}
+     * @param characteristics Properties of this spliterator's source or
+     *        elements
+     * @return A new basic spliterator from an iterator
      */
     public static Spliterator.OfDouble spliterator(PrimitiveIterator.OfDouble iterator, long size, int characteristics) {
         return new DoubleIteratorSpliterator(iterator, size, characteristics);
     }
 
     /**
-     * Returns a basic Spliterator.OfDouble using a given DoubleStream.DoubleIterator for element
-     * operations, with no initial size estimate. The spliterator
-     * implements {@code trySplit} to permit limited parallelism.
+     * Creates a new basic {@code Spliterator.OfDouble} using a given
+     * {@code DoubleStream.DoubleIterator} for element operations, with no
+     * initial size estimate.  The spliterator implements {@code trySplit} to
+     * permit limited parallelism.
      *
-     * @param iterator the iterator for the source
-     * @param characteristics properties of this spliterator's
-     * source or elements.
-     * @since 1.8
+     * @param iterator The iterator for the source
+     * @param characteristics Properties of this spliterator's source or
+     *        elements
+     * @return A new basic spliterator from an iterator
      */
     public static Spliterator.OfDouble spliteratorUnknownSize(PrimitiveIterator.OfDouble iterator, int characteristics) {
         return new DoubleIteratorSpliterator(iterator, characteristics);
@@ -333,6 +368,13 @@
 
     // Iterators from Spliterators
 
+    /**
+     * Creates an {@code Iterator} from a {@code Spliterator}.
+     *
+     * @param spliterator The spliterator
+     * @param <T> Type of elements
+     * @return An iterator
+     */
     public static<T> Iterator<T> iteratorFromSpliterator(Spliterator<? extends T> spliterator) {
         class Adapter implements Iterator<T>, Consumer<T> {
             boolean valueReady = false;
@@ -366,6 +408,12 @@
         return new Adapter();
     }
 
+    /**
+     * Creates an {@code Iterator.OfInt} from a {@code Spliterator.OfInt}.
+     *
+     * @param spliterator The spliterator
+     * @return An iterator
+     */
     public static PrimitiveIterator.OfInt iteratorFromSpliterator(Spliterator.OfInt spliterator) {
         class Adapter implements PrimitiveIterator.OfInt, IntConsumer {
             boolean valueReady = false;
@@ -398,6 +446,12 @@
         return new Adapter();
     }
 
+    /**
+     * Creates an {@code Iterator.OfLong} from a {@code Spliterator.OfLong}.
+     *
+     * @param spliterator The spliterator
+     * @return An iterator
+     */
     public static PrimitiveIterator.OfLong iteratorFromSpliterator(Spliterator.OfLong spliterator) {
         class Adapter implements PrimitiveIterator.OfLong, LongConsumer {
             boolean valueReady = false;
@@ -430,6 +484,12 @@
         return new Adapter();
     }
 
+    /**
+     * Creates an {@code Iterator.OfDouble} from a {@code Spliterator.OfDouble}.
+     *
+     * @param spliterator The spliterator
+     * @return An iterator
+     */
     public static PrimitiveIterator.OfDouble iteratorFromSpliterator(Spliterator.OfDouble spliterator) {
         class Adapter implements PrimitiveIterator.OfDouble, DoubleConsumer {
             boolean valueReady = false;
@@ -465,6 +525,7 @@
     // Implementations
 
     private static class EmptySpliterator<T> implements Spliterator<T> {
+        EmptySpliterator() { }
 
         @Override
         public Spliterator<T> trySplit() {
@@ -489,7 +550,9 @@
             return Spliterator.SIZED | Spliterator.SUBSIZED;
         }
 
-        private static class OfInt extends EmptySpliterator<Integer> implements Spliterator.OfInt {
+        private static final class OfInt extends EmptySpliterator<Integer> implements Spliterator.OfInt {
+            OfInt() { }
+
             @Override
             public Spliterator.OfInt trySplit() {
                 return null;
@@ -505,7 +568,9 @@
             }
         }
 
-        private static class OfLong extends EmptySpliterator<Long> implements Spliterator.OfLong {
+        private static final class OfLong extends EmptySpliterator<Long> implements Spliterator.OfLong {
+            OfLong() { }
+
             @Override
             public Spliterator.OfLong trySplit() {
                 return null;
@@ -521,7 +586,9 @@
             }
         }
 
-        private static class OfDouble extends EmptySpliterator<Double> implements Spliterator.OfDouble {
+        private static final class OfDouble extends EmptySpliterator<Double> implements Spliterator.OfDouble {
+            OfDouble() { }
+
             @Override
             public Spliterator.OfDouble trySplit() {
                 return null;