OpenJDK / lambda / lambda / jdk
changeset 7732:79eb358c9c02
Docs and cleanups.
| author | psandoz |
|---|---|
| date | Sun, 24 Mar 2013 18:45:12 +0100 |
| parents | e3a614a98f69 |
| children | 08f05353a6d4 |
| files | src/share/classes/java/util/Collection.java src/share/classes/java/util/List.java src/share/classes/java/util/Set.java src/share/classes/java/util/SortedSet.java src/share/classes/java/util/Spliterators.java |
| diffstat | 5 files changed, 388 insertions(+), 293 deletions(-) [+] |
line wrap: on
line diff
--- a/src/share/classes/java/util/Collection.java Sat Mar 23 16:49:23 2013 -0400 +++ b/src/share/classes/java/util/Collection.java Sun Mar 24 18:45:12 2013 +0100 @@ -490,10 +490,11 @@ int hashCode(); /** - * Creates a {@link Spliterator}, over the elements in this collection, that - * reports the spliterator characteristic {@code SIZED}. Overriding - * implementations should document if the {@code Spliterator} reports any - * additional characteristic values. + * Creates a {@link Spliterator} over the elements in this collection. + * + * <p>The {@code Spliterator} reports {@link Spliterator#SIZED}. + * Implementations should document the reporting of additional + * characteristic values. * * <p>The default implementation should be overridden by implementing * Collections that can return a more efficient spliterator. In order to @@ -513,8 +514,14 @@ * collection as of the beginning of the terminal stream operation. * * @implSpec - * The default implementation creates a <em>late-binding</em> spliterator - * from the collections's {@code Iterator}. + * The default implementation creates a + * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator + * from the collections's {@code Iterator}. The spliterator inherits the + * <em>fail-fast</em> properties of the collection's iterator. + * + * @implNote + * The created {@code Spliterator} additionally reports + * {@link Spliterator#SUBSIZED}. * * @return a {@code Spliterator} over the elements in this collection * @since 1.8
--- a/src/share/classes/java/util/List.java Sat Mar 23 16:49:23 2013 -0400 +++ b/src/share/classes/java/util/List.java Sun Mar 24 18:45:12 2013 +0100 @@ -653,14 +653,21 @@ List<E> subList(int fromIndex, int toIndex); /** - * Creates a {@code Spliterator}, over the elements in this list, that - * reports {@code SIZED} and {@code ORDERED}. Overriding implementations - * are expected to document if the {@code Spliterator} reports any - * additional and relevant characteristic values. + * Creates a {@link Spliterator} over the elements in this list. + * + * <p>The {@code Spliterator} reports {@link Spliterator#SIZED} and + * {@link Spliterator#ORDERED}. Implementations should document the + * reporting of additional characteristic values. * * @implSpec - * The default implementation creates a <em>late-binding</em> spliterator - * from the list's {@code Iterator}. + * The default implementation creates a + * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator + * from the list's {@code Iterator}. The spliterator inherits the + * <em>fail-fast</em> properties of the collection's iterator. + * + * @implNote + * The created {@code Spliterator} additionally reports + * {@link Spliterator#SUBSIZED}. * * @return a {@code Spliterator} over the elements in this list * @since 1.8
--- a/src/share/classes/java/util/Set.java Sat Mar 23 16:49:23 2013 -0400 +++ b/src/share/classes/java/util/Set.java Sun Mar 24 18:45:12 2013 +0100 @@ -384,14 +384,21 @@ int hashCode(); /** - * Creates a {@code Spliterator}, over the elements in this set, that - * reports {@code SIZED} and {@code DISTINCT}. Overriding implementations - * are expected to document if the {@code Spliterator} reports any - * additional and relevant characteristic values. + * Creates a {@code Spliterator} over the elements in this set. + * + * <p>The {@code Spliterator} reports {@link Spliterator#SIZED} and + * {@link Spliterator#DISTINCT}. Implementations should document the + * reporting of additional characteristic values. * * @implSpec - * The default implementation creates a <em>late-binding</em> spliterator - * from the set's {@code Iterator}. + * The default implementation creates a + * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator + * from the set's {@code Iterator}. The spliterator inherits the + * <em>fail-fast</em> properties of the collection's iterator. + * + * @implNote + * The created {@code Spliterator} additionally reports + * {@link Spliterator#SUBSIZED}. * * @return a {@code Spliterator} over the elements in this set * @since 1.8
--- a/src/share/classes/java/util/SortedSet.java Sat Mar 23 16:49:23 2013 -0400 +++ b/src/share/classes/java/util/SortedSet.java Sun Mar 24 18:45:12 2013 +0100 @@ -221,11 +221,12 @@ E last(); /** - * Creates a {@code Spliterator}, over the elements in this sorted set, that - * reports {@code SIZED}, {@code DISTINCT}, {@code SORTED} and - * {@code ORDERED}. Overriding implementations are expected to document if - * the {@code Spliterator} reports any additional and relevant - * characteristic values. + * Creates a {@code Spliterator} over the elements in this sorted set. + * + * <p>The {@code Spliterator} reports {@link Spliterator#SIZED}, + * {@link Spliterator#DISTINCT}, {@link Spliterator#SORTED} and + * {@link Spliterator#ORDERED}. Implementations should document the + * reporting of additional characteristic values. * * <p>The spliterator's comparator (see * {@link java.util.Spliterator#getComparator()}) must be {@code null} if @@ -234,9 +235,15 @@ * same total ordering as the sorted set's comparator. * * @implSpec - * This implementation creates a <em>late-binding</em> spliterator from the - * sorted set's {@code Iterator}. The spliterator's comparator is the same - * as the sorted set's comparator. + * The default implementation creates a + * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator + * from the sorted set's {@code Iterator}. The spliterator inherits the + * <em>fail-fast</em> properties of the collection's iterator. The + * spliterator's comparator is the same as the sorted set's comparator. + * + * @implNote + * The created {@code Spliterator} additionally reports + * {@link Spliterator#SUBSIZED}. * * @return a {@code Spliterator} over the elements in this sorted set * @since 1.8
--- a/src/share/classes/java/util/Spliterators.java Sat Mar 23 16:49:23 2013 -0400 +++ b/src/share/classes/java/util/Spliterators.java Sun Mar 24 18:45:12 2013 +0100 @@ -52,7 +52,7 @@ * @return An empty {@code Spliterator} */ public static <T> Spliterator<T> emptySpliterator() { - return new EmptySpliterator<>(); + return new AbstractEmptySpliterator.OfRef<>(); } /** @@ -61,7 +61,7 @@ * @return An empty {@code Spliterator.OfInt} */ public static Spliterator.OfInt emptyIntSpliterator() { - return new EmptySpliterator.OfInt(); + return new AbstractEmptySpliterator.OfInt(); } /** @@ -70,7 +70,7 @@ * @return An empty {@code Spliterator.OfLong} */ public static Spliterator.OfLong emptyLongSpliterator() { - return new EmptySpliterator.OfLong(); + return new AbstractEmptySpliterator.OfLong(); } /** @@ -79,132 +79,160 @@ * @return An empty {@code Spliterator.OfDouble} */ public static Spliterator.OfDouble emptyDoubleSpliterator() { - return new EmptySpliterator.OfDouble(); + return new AbstractEmptySpliterator.OfDouble(); } // Array-based spliterators /** - * Creates a new {@code Spliterator} covering all of the given array. + * Creates a {@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.) + * @param additionalCharacteristics 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 + * @throws NullPointerException if the given array is {@code null} + * @return A spliterator from an array */ - public static <T> Spliterator<T> spliterator(Object[] array, int characteristics) { - return new ArraySpliterator<>(array, characteristics); + public static <T> Spliterator<T> spliterator(Object[] array, + int additionalCharacteristics) { + return new ArraySpliterator<>(Objects.requireNonNull(array), additionalCharacteristics); } /** - * Creates a new {@code Spliterator} covering the given range of the given + * Creates a {@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.) + * @param additionalCharacteristics 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 + * @throws NullPointerException if the given array is {@code null} + * @throws ArrayIndexOutOfBoundsException if {@code origin} is negative, + * {@code fence} is less than {@code origin}, or {@code fence} is + * greater than the array size + * @return A spliterator from an array */ - public static <T> Spliterator<T> spliterator(Object[] array, int origin, int fence, int characteristics) { - checkFromToBounds(array.length, origin, fence); - return new ArraySpliterator<>(array, origin, fence, characteristics); + public static <T> Spliterator<T> spliterator(Object[] array, int origin, int fence, + int additionalCharacteristics) { + checkFromToBounds(Objects.requireNonNull(array).length, origin, fence); + return new ArraySpliterator<>(array, origin, fence, additionalCharacteristics); } /** - * Creates a new {@code Spliterator.OfInt} covering all of the given array. + * Creates a {@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.) - * @return A new spliterator from an array + * @param additionalCharacteristics Properties of this spliterator's source + * or elements ({@code SIZED} and {@code SUBSIZED} are always + * reported, so need not be supplied.) + * @throws NullPointerException if the given array is {@code null} + * @return A spliterator from an array */ - public static Spliterator.OfInt spliterator(int[] array, int characteristics) { - return new IntArraySpliterator(array, characteristics); + public static Spliterator.OfInt spliterator(int[] array, + int additionalCharacteristics) { + return new IntArraySpliterator(Objects.requireNonNull(array), additionalCharacteristics); } /** - * Creates a new {@code Spliterator.OfInt} covering the given range of the + * Creates a {@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.) - * @return A new spliterator from an array + * @param additionalCharacteristics Properties of this spliterator's source + * or elements ({@code SIZED} and {@code SUBSIZED} are always + * reported, so need not be supplied.) + * @throws NullPointerException if the given array is {@code null} + * @throws ArrayIndexOutOfBoundsException if {@code origin} is negative, + * {@code fence} is less than {@code origin}, or {@code fence} is + * greater than the array size + * @return A spliterator from an array */ - public static Spliterator.OfInt spliterator(int[] array, int origin, int fence, int characteristics) { - checkFromToBounds(array.length, origin, fence); - return new IntArraySpliterator(array, origin, fence, characteristics); + public static Spliterator.OfInt spliterator(int[] array, int origin, int fence, + int additionalCharacteristics) { + checkFromToBounds(Objects.requireNonNull(array).length, origin, fence); + return new IntArraySpliterator(array, origin, fence, additionalCharacteristics); } /** - * Creates a new {@code Spliterator.OfLong} covering all of the given array. + * Creates a {@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.) - * @return A new spliterator from an array + * @param additionalCharacteristics Properties of this spliterator's source + * or elements ({@code SIZED} and {@code SUBSIZED} are always + * reported, so need not be supplied.) + * @throws NullPointerException if the given array is {@code null} + * @return A spliterator from an array */ - public static Spliterator.OfLong spliterator(long[] array, int characteristics) { - return new LongArraySpliterator(array, characteristics); + public static Spliterator.OfLong spliterator(long[] array, + int additionalCharacteristics) { + return new LongArraySpliterator(Objects.requireNonNull(array), additionalCharacteristics); } /** - * Creates a new {@code Spliterator.OfLong} covering the given range of the + * Creates a {@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.) - * @return A new spliterator from an array + * @param additionalCharacteristics Properties of this spliterator's source + * or elements ({@code SIZED} and {@code SUBSIZED} are always + * reported, so need not be supplied.) + * @throws NullPointerException if the given array is {@code null} + * @throws ArrayIndexOutOfBoundsException if {@code origin} is negative, + * {@code fence} is less than {@code origin}, or {@code fence} is + * greater than the array size + * @return A spliterator from an array */ - public static Spliterator.OfLong spliterator(long[] array, int origin, int fence, int characteristics) { - checkFromToBounds(array.length, origin, fence); - return new LongArraySpliterator(array, origin, fence, characteristics); + public static Spliterator.OfLong spliterator(long[] array, int origin, int fence, + int additionalCharacteristics) { + checkFromToBounds(Objects.requireNonNull(array).length, origin, fence); + return new LongArraySpliterator(array, origin, fence, additionalCharacteristics); } /** - * Creates a new {@code Spliterator.OfDouble} covering all of the given + * Creates a {@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.) - * @return A new spliterator from an array + * @param additionalCharacteristics Properties of this spliterator's source + * or elements ({@code SIZED} and {@code SUBSIZED} are always + * reported, so need not be supplied.) + * @throws NullPointerException if the given array is {@code null} + * @return A spliterator from an array */ - public static Spliterator.OfDouble spliterator(double[] array, int characteristics) { - return new DoubleArraySpliterator(array, characteristics); + public static Spliterator.OfDouble spliterator(double[] array, + int additionalCharacteristics) { + return new DoubleArraySpliterator(Objects.requireNonNull(array), additionalCharacteristics); } /** - * Creates a new {@code Spliterator.OfDouble} covering the given range of + * Creates a {@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.) - * @return A new spliterator from an array + * @param additionalCharacteristics Properties of this spliterator's source + * or elements ({@code SIZED} and {@code SUBSIZED} are always + * reported, so need not be supplied.) + * @throws NullPointerException if the given array is {@code null} + * @throws ArrayIndexOutOfBoundsException if {@code origin} is negative, + * {@code fence} is less than {@code origin}, or {@code fence} is + * greater than the array size + * @return A spliterator from an array */ - public static Spliterator.OfDouble spliterator(double[] array, int origin, int fence, int characteristics) { - checkFromToBounds(array.length, origin, fence); - return new DoubleArraySpliterator(array, origin, fence, characteristics); + public static Spliterator.OfDouble spliterator(double[] array, int origin, int fence, + int additionalCharacteristics) { + checkFromToBounds(Objects.requireNonNull(array).length, origin, fence); + return new DoubleArraySpliterator(array, origin, fence, additionalCharacteristics); } private static void checkFromToBounds(int arrayLength, int origin, int fence) { @@ -223,148 +251,205 @@ // Iterator-based spliterators /** - * Creates a new basic {@code Spliterator} using the given collection's + * Creates a 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 - * is <em>last-binding</em> and implements {@code trySplit} to permit - * limited parallelism. + * {@link java.util.Collection#size()} as its initial size. + * + * <p>Traversal of the iterator must be accomplished through the returned + * spliterator. + * + * <p>The spliterator is + * <em><a href="Spliterator.html#binding">late-binding</a></em>, inherits + * the <em>fail-fast</em> properties of the collection's iterator, and + * implements {@code trySplit} to permit limited parallelism. * * @param c The collection - * @param characteristics Properties of this spliterator's source or - * elements. + * @param additionalCharacteristics 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 basic spliterator from an iterator + * @throws NullPointerException if the given collection is {@code null} + * @return A basic spliterator from an iterator */ - public static <T> Spliterator<T> spliterator(Collection<T> c, int characteristics) { - return new IteratorSpliterator<>(c, characteristics); + public static <T> Spliterator<T> spliterator(Collection<T> c, + int additionalCharacteristics) { + return new IteratorSpliterator<>(Objects.requireNonNull(c), additionalCharacteristics); } /** - * Creates a new basic {@code Spliterator} using a given {@code Iterator} + * Creates a 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. * + * <p>Traversal of the iterator must be accomplished through the returned + * spliterator. + * * @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 additionalCharacteristics 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 basic spliterator from an iterator + * @throws NullPointerException if the given iterator is {@code null} + * @return A basic spliterator from an iterator */ - public static <T> Spliterator<T> spliterator(Iterator<T> iterator, long size, int characteristics) { - return new IteratorSpliterator<>(iterator, size, characteristics); + public static <T> Spliterator<T> spliterator(Iterator<T> iterator, long size, + int additionalCharacteristics) { + return new IteratorSpliterator<>(Objects.requireNonNull(iterator), size, additionalCharacteristics); } /** - * Creates a new basic {@code Spliterator} using a given {@code Iterator} + * Creates a 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. * + * <p>Traversal of the iterator must be accomplished through the returned + * spliterator. + * * @param iterator The iterator for the source - * @param characteristics Properties of this spliterator's source or - * elements + * @param additionalCharacteristics 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 basic spliterator from an iterator + * @throws NullPointerException if the given iterator is {@code null} + * @return A basic spliterator from an iterator */ - public static <T> Spliterator<T> spliteratorUnknownSize(Iterator<T> iterator, int characteristics) { - return new IteratorSpliterator<>(iterator, characteristics); + public static <T> Spliterator<T> spliteratorUnknownSize(Iterator<T> iterator, + int additionalCharacteristics) { + return new IteratorSpliterator<>(Objects.requireNonNull(iterator), additionalCharacteristics); } /** - * Creates a new basic {@code Spliterator.OfInt} using a given + * Creates a 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. * + * <p>Traversal of the iterator must be accomplished through the returned + * spliterator. + * * @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 + * @param additionalCharacteristics Properties of this spliterator's source + * or elements ({@code SIZED} and {@code SUBSIZED} are always + * reported, so need not be supplied.) + * @throws NullPointerException if the given iterator is {@code null} + * @return A basic spliterator from an iterator */ - public static Spliterator.OfInt spliterator(PrimitiveIterator.OfInt iterator, long size, int characteristics) { - return new IntIteratorSpliterator(iterator, size, characteristics); + public static Spliterator.OfInt spliterator(PrimitiveIterator.OfInt iterator, long size, + int additionalCharacteristics) { + return new IntIteratorSpliterator(Objects.requireNonNull(iterator), size, additionalCharacteristics); } /** - * Creates a new basic {@code Spliterator.OfInt} using a given + * Creates a 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. * + * <p>Traversal of the iterator must be accomplished through the returned + * spliterator. + * * @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 + * @param additionalCharacteristics Properties of this spliterator's source + * or elements ({@code SIZED} and {@code SUBSIZED} are always + * reported, so need not be supplied.) + * @throws NullPointerException if the given iterator is {@code null} + * @return A basic spliterator from an iterator */ - public static Spliterator.OfInt spliteratorUnknownSize(PrimitiveIterator.OfInt iterator, int characteristics) { - return new IntIteratorSpliterator(iterator, characteristics); + public static Spliterator.OfInt spliteratorUnknownSize(PrimitiveIterator.OfInt iterator, + int additionalCharacteristics) { + return new IntIteratorSpliterator(Objects.requireNonNull(iterator), additionalCharacteristics); } /** - * Creates a new basic {@code Spliterator.OfLong} using a given + * Creates a 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. * + * <p>Traversal of the iterator must be accomplished through the returned + * spliterator. + * * @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 + * @param additionalCharacteristics Properties of this spliterator's source + * or elements ({@code SIZED} and {@code SUBSIZED} are always + * reported, so need not be supplied.) + * @throws NullPointerException if the given iterator is {@code null} + * @return A basic spliterator from an iterator */ - public static Spliterator.OfLong spliterator(PrimitiveIterator.OfLong iterator, long size, int characteristics) { - return new LongIteratorSpliterator(iterator, size, characteristics); + public static Spliterator.OfLong spliterator(PrimitiveIterator.OfLong iterator, long size, + int additionalCharacteristics) { + return new LongIteratorSpliterator(Objects.requireNonNull(iterator), size, additionalCharacteristics); } /** - * Creates a new basic {@code Spliterator.OfLong} using a given + * Creates a 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. * + * <p>Traversal of the iterator must be accomplished through the returned + * spliterator. + * * @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 + * @param additionalCharacteristics Properties of this spliterator's source + * or elements ({@code SIZED} and {@code SUBSIZED} are always + * reported, so need not be supplied.) + * @throws NullPointerException if the given iterator is {@code null} + * @return A basic spliterator from an iterator */ - public static Spliterator.OfLong spliteratorUnknownSize(PrimitiveIterator.OfLong iterator, int characteristics) { - return new LongIteratorSpliterator(iterator, characteristics); + public static Spliterator.OfLong spliteratorUnknownSize(PrimitiveIterator.OfLong iterator, + int additionalCharacteristics) { + return new LongIteratorSpliterator(Objects.requireNonNull(iterator), additionalCharacteristics); } /** - * Creates a new basic {@code Spliterator.OfDouble} using a given + * Creates a 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. * + * <p>Traversal of the iterator must be accomplished through the returned + * spliterator. + * * @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 + * @param additionalCharacteristics Properties of this spliterator's source + * or elements ({@code SIZED} and {@code SUBSIZED} are always + * reported, so need not be supplied.) + * @throws NullPointerException if the given iterator is {@code null} + * @return A basic spliterator from an iterator */ - public static Spliterator.OfDouble spliterator(PrimitiveIterator.OfDouble iterator, long size, int characteristics) { - return new DoubleIteratorSpliterator(iterator, size, characteristics); + public static Spliterator.OfDouble spliterator(PrimitiveIterator.OfDouble iterator, long size, + int additionalCharacteristics) { + return new DoubleIteratorSpliterator(Objects.requireNonNull(iterator), size, additionalCharacteristics); } /** - * Creates a new basic {@code Spliterator.OfDouble} using a given + * Creates a 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. * + * <p>Traversal of the iterator must be accomplished through the returned + * spliterator. + * * @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 + * @param additionalCharacteristics Properties of this spliterator's source + * or elements ({@code SIZED} and {@code SUBSIZED} are always + * reported, so need not be supplied.) + * @throws NullPointerException if the given iterator is {@code null} + * @return A basic spliterator from an iterator */ - public static Spliterator.OfDouble spliteratorUnknownSize(PrimitiveIterator.OfDouble iterator, int characteristics) { - return new DoubleIteratorSpliterator(iterator, characteristics); + public static Spliterator.OfDouble spliteratorUnknownSize(PrimitiveIterator.OfDouble iterator, + int additionalCharacteristics) { + return new DoubleIteratorSpliterator(Objects.requireNonNull(iterator), additionalCharacteristics); } // Iterators from Spliterators @@ -372,11 +457,16 @@ /** * Creates an {@code Iterator} from a {@code Spliterator}. * + * <p>Traversal of the spliterator must be accomplished through the returned + * iterator. During traversal the spliterator must not be operated on. + * * @param spliterator The spliterator * @param <T> Type of elements + * @throws NullPointerException if the given spliterator is {@code null} * @return An iterator */ public static<T> Iterator<T> iteratorFromSpliterator(Spliterator<? extends T> spliterator) { + Objects.requireNonNull(spliterator); class Adapter implements Iterator<T>, Consumer<T> { boolean valueReady = false; T nextElement; @@ -389,9 +479,8 @@ @Override public boolean hasNext() { - Consumer<T> b = this; if (!valueReady) - spliterator.tryAdvance(b); + spliterator.tryAdvance(this); return valueReady; } @@ -410,12 +499,18 @@ } /** - * Creates an {@code Iterator.OfInt} from a {@code Spliterator.OfInt}. + * Creates an {@code PrimitiveIterator.OfInt} from a + * {@code Spliterator.OfInt}. + * + * <p>Traversal of the spliterator must be accomplished through the returned + * iterator. During traversal the spliterator must not be operated on. * * @param spliterator The spliterator + * @throws NullPointerException if the given spliterator is {@code null} * @return An iterator */ public static PrimitiveIterator.OfInt iteratorFromSpliterator(Spliterator.OfInt spliterator) { + Objects.requireNonNull(spliterator); class Adapter implements PrimitiveIterator.OfInt, IntConsumer { boolean valueReady = false; int nextElement; @@ -448,12 +543,18 @@ } /** - * Creates an {@code Iterator.OfLong} from a {@code Spliterator.OfLong}. + * Creates an {@code PrimitiveIterator.OfLong} from a + * {@code Spliterator.OfLong}. + * + * <p>Traversal of the spliterator must be accomplished through the returned + * iterator. During traversal the spliterator must not be operated on. * * @param spliterator The spliterator + * @throws NullPointerException if the given spliterator is {@code null} * @return An iterator */ public static PrimitiveIterator.OfLong iteratorFromSpliterator(Spliterator.OfLong spliterator) { + Objects.requireNonNull(spliterator); class Adapter implements PrimitiveIterator.OfLong, LongConsumer { boolean valueReady = false; long nextElement; @@ -486,12 +587,18 @@ } /** - * Creates an {@code Iterator.OfDouble} from a {@code Spliterator.OfDouble}. + * Creates an {@code PrimitiveIterator.OfDouble} from a + * {@code Spliterator.OfDouble}. + * + * <p>Traversal of the spliterator must be accomplished through the returned + * iterator. During traversal the spliterator must not be operated on. * * @param spliterator The spliterator + * @throws NullPointerException if the given spliterator is {@code null} * @return An iterator */ public static PrimitiveIterator.OfDouble iteratorFromSpliterator(Spliterator.OfDouble spliterator) { + Objects.requireNonNull(spliterator); class Adapter implements PrimitiveIterator.OfDouble, DoubleConsumer { boolean valueReady = false; double nextElement; @@ -525,93 +632,53 @@ // Implementations - private static class EmptySpliterator<T> implements Spliterator<T> { - EmptySpliterator() { } + private static abstract class AbstractEmptySpliterator<T, S extends Spliterator<T>, C> { - @Override - public Spliterator<T> trySplit() { + AbstractEmptySpliterator() { } + + public S trySplit() { return null; } - @Override - public boolean tryAdvance(Consumer<? super T> consumer) { + public boolean tryAdvance(C consumer) { Objects.requireNonNull(consumer); return false; } - @Override - public void forEach(Consumer<? super T> consumer) { + public void forEach(C consumer) { Objects.requireNonNull(consumer); } - @Override public long estimateSize() { return 0; } - @Override public int characteristics() { return Spliterator.SIZED | Spliterator.SUBSIZED; } - private static final class OfInt extends EmptySpliterator<Integer> implements Spliterator.OfInt { - OfInt() { } - - @Override - public Spliterator.OfInt trySplit() { - return null; - } - - @Override - public boolean tryAdvance(IntConsumer consumer) { - Objects.requireNonNull(consumer); - return false; - } - - @Override - public void forEach(IntConsumer consumer) { - Objects.requireNonNull(consumer); - } + private static final class OfRef<T> + extends AbstractEmptySpliterator<T, Spliterator<T>, Consumer<? super T>> + implements Spliterator<T> { + OfRef() { } } - private static final class OfLong extends EmptySpliterator<Long> implements Spliterator.OfLong { - OfLong() { } - - @Override - public Spliterator.OfLong trySplit() { - return null; - } - - @Override - public boolean tryAdvance(LongConsumer consumer) { - Objects.requireNonNull(consumer); - return false; - } - - @Override - public void forEach(LongConsumer consumer) { - Objects.requireNonNull(consumer); - } + private static final class OfInt + extends AbstractEmptySpliterator<Integer, Spliterator.OfInt, IntConsumer> + implements Spliterator.OfInt { + OfInt() { } } - private static final class OfDouble extends EmptySpliterator<Double> implements Spliterator.OfDouble { + private static final class OfLong + extends AbstractEmptySpliterator<Long, Spliterator.OfLong, LongConsumer> + implements Spliterator.OfLong { + OfLong() { } + } + + private static final class OfDouble + extends AbstractEmptySpliterator<Double, Spliterator.OfDouble, DoubleConsumer> + implements Spliterator.OfDouble { OfDouble() { } - - @Override - public Spliterator.OfDouble trySplit() { - return null; - } - - @Override - public boolean tryAdvance(DoubleConsumer consumer) { - Objects.requireNonNull(consumer); - return false; - } - - @Override - public void forEach(DoubleConsumer consumer) { - Objects.requireNonNull(consumer); - } } } @@ -635,30 +702,30 @@ private final int characteristics; /** - * Creates a new spliterator covering all of the given array. + * Creates a spliterator covering all of the given array. * @param array the array, assumed to be unmodified during use - * @param characteristics properties of this spliterator's + * @param additionalCharacteristics properties of this spliterator's * source or elements ({@code SIZED} and {@code SUBSIZED} * are always reported, so need not be supplied.) */ - public ArraySpliterator(Object[] array, int characteristics) { - this(array, 0, array.length, characteristics); + public ArraySpliterator(Object[] array, int additionalCharacteristics) { + this(array, 0, array.length, additionalCharacteristics); } /** - * Creates a new spliterator covering the given array and range + * Creates a spliterator covering the given array and range * @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 + * @param additionalCharacteristics properties of this spliterator's * source or elements ({@code SIZED} and {@code SUBSIZED} * are always reported, so need not be supplied.) */ - public ArraySpliterator(Object[] array, int origin, int fence, int characteristics) { + public ArraySpliterator(Object[] array, int origin, int fence, int additionalCharacteristics) { this.array = array; this.index = origin; this.fence = fence; - this.characteristics = characteristics; + this.characteristics = additionalCharacteristics | Spliterator.SIZED | Spliterator.SUBSIZED; } public Spliterator<T> trySplit() { @@ -693,7 +760,7 @@ public long estimateSize() { return (long)(fence - index); } public int characteristics() { - return characteristics | Spliterator.SIZED | Spliterator.SUBSIZED; + return characteristics; } } @@ -708,30 +775,30 @@ private final int characteristics; /** - * Creates a new spliterator covering all of the given array. + * Creates a spliterator covering all of the given array. * @param array the array, assumed to be unmodified during use - * @param characteristics properties of this spliterator's + * @param additionalCharacteristics properties of this spliterator's * source or elements ({@code SIZED} and {@code SUBSIZED} * are always reported, so need not be supplied.) */ - public IntArraySpliterator(int[] array, int characteristics) { - this(array, 0, array.length, characteristics); + public IntArraySpliterator(int[] array, int additionalCharacteristics) { + this(array, 0, array.length, additionalCharacteristics); } /** - * Creates a new spliterator covering the given array and range + * Creates a spliterator covering the given array and range * @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 + * @param additionalCharacteristics properties of this spliterator's * source or elements ({@code SIZED} and {@code SUBSIZED} * are always reported, so need not be supplied.) */ - public IntArraySpliterator(int[] array, int origin, int fence, int characteristics) { + public IntArraySpliterator(int[] array, int origin, int fence, int additionalCharacteristics) { this.array = array; this.index = origin; this.fence = fence; - this.characteristics = characteristics; + this.characteristics = additionalCharacteristics | Spliterator.SIZED | Spliterator.SUBSIZED; } public OfInt trySplit() { @@ -764,7 +831,7 @@ public long estimateSize() { return (long)(fence - index); } public int characteristics() { - return characteristics | Spliterator.SIZED | Spliterator.SUBSIZED; + return characteristics; } } @@ -779,30 +846,30 @@ private final int characteristics; /** - * Creates a new spliterator covering all of the given array. + * Creates a spliterator covering all of the given array. * @param array the array, assumed to be unmodified during use - * @param characteristics properties of this spliterator's + * @param additionalCharacteristics properties of this spliterator's * source or elements ({@code SIZED} and {@code SUBSIZED} * are always reported, so need not be supplied.) */ - public LongArraySpliterator(long[] array, int characteristics) { - this(array, 0, array.length, characteristics); + public LongArraySpliterator(long[] array, int additionalCharacteristics) { + this(array, 0, array.length, additionalCharacteristics); } /** - * Creates a new spliterator covering the given array and range + * Creates a spliterator covering the given array and range * @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 + * @param additionalCharacteristics properties of this spliterator's * source or elements ({@code SIZED} and {@code SUBSIZED} * are always reported, so need not be supplied.) */ - public LongArraySpliterator(long[] array, int origin, int fence, int characteristics) { + public LongArraySpliterator(long[] array, int origin, int fence, int additionalCharacteristics) { this.array = array; this.index = origin; this.fence = fence; - this.characteristics = characteristics; + this.characteristics = additionalCharacteristics | Spliterator.SIZED | Spliterator.SUBSIZED; } public OfLong trySplit() { @@ -835,7 +902,7 @@ public long estimateSize() { return (long)(fence - index); } public int characteristics() { - return characteristics | Spliterator.SIZED | Spliterator.SUBSIZED; + return characteristics; } } @@ -850,30 +917,30 @@ private final int characteristics; /** - * Creates a new spliterator covering all of the given array. + * Creates a spliterator covering all of the given array. * @param array the array, assumed to be unmodified during use - * @param characteristics properties of this spliterator's + * @param additionalCharacteristics properties of this spliterator's * source or elements ({@code SIZED} and {@code SUBSIZED} * are always reported, so need not be supplied.) */ - public DoubleArraySpliterator(double[] array, int characteristics) { - this(array, 0, array.length, characteristics); + public DoubleArraySpliterator(double[] array, int additionalCharacteristics) { + this(array, 0, array.length, additionalCharacteristics); } /** - * Creates a new spliterator covering the given array and range + * Creates a spliterator covering the given array and range * @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 + * @param additionalCharacteristics properties of this spliterator's * source or elements ({@code SIZED} and {@code SUBSIZED} * are always reported, so need not be supplied.) */ - public DoubleArraySpliterator(double[] array, int origin, int fence, int characteristics) { + public DoubleArraySpliterator(double[] array, int origin, int fence, int additionalCharacteristics) { this.array = array; this.index = origin; this.fence = fence; - this.characteristics = characteristics; + this.characteristics = additionalCharacteristics | Spliterator.SIZED | Spliterator.SUBSIZED; } public OfDouble trySplit() { @@ -906,7 +973,7 @@ public long estimateSize() { return (long)(fence - index); } public int characteristics() { - return characteristics | Spliterator.SIZED | Spliterator.SUBSIZED; + return characteristics; } } @@ -944,20 +1011,20 @@ private int batch; // batch size for splits /** - * Creates a new spliterator reporting the given estimated size and - * characteristics. + * Creates a spliterator reporting the given estimated size and + * additionalCharacteristics. * * @param est the estimated size of this spliterator if known, otherwise * {@code Long.MAX_VALUE}. - * @param characteristics properties of this spliterator's source or - * elements. If {@code SIZED} is reported then this spliterator - * will additionally report {@code SUBSIZED}. + * @param additionalCharacteristics properties of this spliterator's + * source or elements. If {@code SIZED} is reported then this + * spliterator will additionally report {@code SUBSIZED}. */ - protected AbstractSpliterator(long est, int characteristics) { + protected AbstractSpliterator(long est, int additionalCharacteristics) { this.est = est; - this.characteristics = ((characteristics & Spliterator.SIZED) != 0) - ? characteristics | Spliterator.SUBSIZED - : characteristics; + this.characteristics = ((additionalCharacteristics & Spliterator.SIZED) != 0) + ? additionalCharacteristics | Spliterator.SUBSIZED + : additionalCharacteristics; } static final class HoldingConsumer<T> implements Consumer<T> { @@ -1071,20 +1138,20 @@ private int batch; // batch size for splits /** - * Creates a new spliterator reporting the given estimated size and + * Creates a spliterator reporting the given estimated size and * characteristics. * * @param est the estimated size of this spliterator if known, otherwise * {@code Long.MAX_VALUE}. - * @param characteristics properties of this spliterator's source or - * elements. If {@code SIZED} is reported then this spliterator - * will additionally report {@code SUBSIZED}. + * @param additionalCharacteristics properties of this spliterator's + * source or elements. If {@code SIZED} is reported then this + * spliterator will additionally report {@code SUBSIZED}. */ - protected AbstractIntSpliterator(long est, int characteristics) { + protected AbstractIntSpliterator(long est, int additionalCharacteristics) { this.est = est; - this.characteristics = ((characteristics & Spliterator.SIZED) != 0) - ? characteristics | Spliterator.SUBSIZED - : characteristics; + this.characteristics = ((additionalCharacteristics & Spliterator.SIZED) != 0) + ? additionalCharacteristics | Spliterator.SUBSIZED + : additionalCharacteristics; } static final class HoldingIntConsumer implements IntConsumer { @@ -1185,20 +1252,20 @@ private int batch; // batch size for splits /** - * Creates a new spliterator reporting the given estimated size and + * Creates a spliterator reporting the given estimated size and * characteristics. * * @param est the estimated size of this spliterator if known, otherwise * {@code Long.MAX_VALUE}. - * @param characteristics properties of this spliterator's source or - * elements. If {@code SIZED} is reported then this spliterator - * will additionally report {@code SUBSIZED}. + * @param additionalCharacteristics properties of this spliterator's + * source or elements. If {@code SIZED} is reported then this + * spliterator will additionally report {@code SUBSIZED}. */ - protected AbstractLongSpliterator(long est, int characteristics) { + protected AbstractLongSpliterator(long est, int additionalCharacteristics) { this.est = est; - this.characteristics = ((characteristics & Spliterator.SIZED) != 0) - ? characteristics | Spliterator.SUBSIZED - : characteristics; + this.characteristics = ((additionalCharacteristics & Spliterator.SIZED) != 0) + ? additionalCharacteristics | Spliterator.SUBSIZED + : additionalCharacteristics; } static final class HoldingLongConsumer implements LongConsumer { @@ -1299,20 +1366,20 @@ private int batch; // batch size for splits /** - * Creates a new spliterator reporting the given estimated size and + * Creates a spliterator reporting the given estimated size and * characteristics. * * @param est the estimated size of this spliterator if known, otherwise * {@code Long.MAX_VALUE}. - * @param characteristics properties of this spliterator's source or - * elements. If {@code SIZED} is reported then this spliterator - * will additionally report {@code SUBSIZED}. + * @param additionalCharacteristics properties of this spliterator's + * source or elements. If {@code SIZED} is reported then this + * spliterator will additionally report {@code SUBSIZED}. */ - protected AbstractDoubleSpliterator(long est, int characteristics) { + protected AbstractDoubleSpliterator(long est, int additionalCharacteristics) { this.est = est; - this.characteristics = ((characteristics & Spliterator.SIZED) != 0) - ? characteristics | Spliterator.SUBSIZED - : characteristics; + this.characteristics = ((additionalCharacteristics & Spliterator.SIZED) != 0) + ? additionalCharacteristics | Spliterator.SUBSIZED + : additionalCharacteristics; } static final class HoldingDoubleConsumer implements DoubleConsumer { @@ -1398,7 +1465,7 @@ private int batch; // batch size for splits /** - * Creates a new spliterator using the given given + * Creates a spliterator using the given given * collection's {@link java.util.Collection#iterator()) for traversal, and * reporting its {@link java.util.Collection#size()) as its initial size. * @@ -1413,7 +1480,7 @@ } /** - * Creates a new spliterator using the given iterator + * Creates a spliterator using the given iterator * for traversal, and reporting the given initial size * and characteristics. * @@ -1430,7 +1497,7 @@ } /** - * Creates a new spliterator using the given iterator + * Creates a spliterator using the given iterator * for traversal, and reporting the given initial size * and characteristics. * @@ -1537,7 +1604,7 @@ private int batch; // batch size for splits /** - * Creates a new spliterator using the given iterator + * Creates a spliterator using the given iterator * for traversal, and reporting the given initial size * and characteristics. * @@ -1553,7 +1620,7 @@ } /** - * Creates a new spliterator using the given iterator for a + * Creates a spliterator using the given iterator for a * source of unknown size, reporting the given * characteristics. * @@ -1622,7 +1689,7 @@ private int batch; // batch size for splits /** - * Creates a new spliterator using the given iterator + * Creates a spliterator using the given iterator * for traversal, and reporting the given initial size * and characteristics. * @@ -1638,7 +1705,7 @@ } /** - * Creates a new spliterator using the given iterator for a + * Creates a spliterator using the given iterator for a * source of unknown size, reporting the given * characteristics. * @@ -1707,7 +1774,7 @@ private int batch; // batch size for splits /** - * Creates a new spliterator using the given iterator + * Creates a spliterator using the given iterator * for traversal, and reporting the given initial size * and characteristics. * @@ -1723,7 +1790,7 @@ } /** - * Creates a new spliterator using the given iterator for a + * Creates a spliterator using the given iterator for a * source of unknown size, reporting the given * characteristics. *