changeset 7564:98bf3c8a550c

- Improve documentation for Stream.iterator. - Ensure iterator for reference values correctly supports a null seed value.
author psandoz
date Tue, 05 Mar 2013 18:10:52 +0100
parents e89a6e7532e0
children f971c0bb050e
files src/share/classes/java/util/stream/Streams.java
diffstat 1 files changed, 73 insertions(+), 34 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/stream/Streams.java	Tue Mar 05 16:35:05 2013 +0100
+++ b/src/share/classes/java/util/stream/Streams.java	Tue Mar 05 18:10:52 2013 +0100
@@ -58,6 +58,13 @@
     }
 
     /**
+     * An object instance representing no value. Can be used when processing
+     * streams that can contain {@code null} elements to distinguish between a
+     * {@code null} value and no value.
+     */
+    static final Object NONE = new Object();
+
+    /**
      * The maximum size of array to allocate.
      */
     static final long MAX_ARRAY_SIZE = Integer.MAX_VALUE - 8;
@@ -421,14 +428,20 @@
 
     /**
      * Creates a sequential {@code Stream} that is an infinite sequence of
-     * elements. The first element is {@code seed}, the second element is the
-     * result of applying {@code seed} to the function {@code f}, and the nth
-     * element is the result of applying the nth minus one element to the
-     * function {@code f}.
+     * elements produced by repeated application of a function {@code f} to
+     * {@code seed}.
      *
-     * @param seed The first element in sequence
-     * @param f The function to be applied to the nth minus one element to
-     *        produce the nth element, where n > 1
+     * <p>The first element at position {@code 0} in the {@code Stream} is
+     * {@code seed}. An element at position {@code n}, where {@code n > 0},
+     * is the result of applying the element at position {@code n - 1} to the
+     * function {@code f}.  For example, this method creates a {@code Stream}
+     * that has the following elements: {@code seed}, {@code f(seed)},
+     * {@code f(f(seed))} etc.
+     *
+     * @param seed The first element, at position {@code 0}, in the stream
+     * @param f The function to be applied to an element at position
+     *        {@code n - 1} in the {@code Stream} to produce the next element at
+     *        position {@code n}, where {@code n > 0}
      * @param <T> The type of elements
      * @return A new sequential {@code Stream} that is an infinite sequence of
      *         elements
@@ -436,11 +449,12 @@
     public static<T> Stream<T> iterate(final T seed, final UnaryOperator<T> f) {
         Objects.requireNonNull(f);
         final InfiniteIterator<T> iterator = new InfiniteIterator<T>() {
-            T t = null;
+            @SuppressWarnings("unchecked")
+            T t = (T) NONE;
 
             @Override
             public T next() {
-                return t = (t == null) ? seed : f.apply(t);
+                return t = (t == NONE) ? seed : f.apply(t);
             }
         };
         return stream(Spliterators.spliteratorUnknownSize(
@@ -468,6 +482,7 @@
      *         generated elements
      */
     public static<T> Stream<T> generate(Supplier<T> s) {
+        Objects.requireNonNull(s);
         InfiniteIterator<T> iterator = s::get;
         return stream(Spliterators.spliteratorUnknownSize(
                 iterator,
@@ -479,14 +494,21 @@
 
     /**
      * Creates a sequential {@code IntStream} that is an infinite sequence of
-     * {@code int} elements.  The first element is {@code seed}, the second
-     * element is the result of applying {@code seed} to the function {@code f},
-     * and the nth element is the result of applying the nth minus one element
-     * to the function {@code f}.
+     * {@code int} elements produced by repeated application of a function
+     * {@code f} to {@code seed}.
      *
-     * @param seed The first {@code int} element in sequence
-     * @param f The function to be applied to the nth minus one element to
-     *        produce the nth element, where n > 1
+     * <p>The first element at position {@code 0} in the {@code IntStream} is
+     * {@code seed}. An element at position {@code n}, where {@code n > 0},
+     * is the result of applying the element at position {@code n - 1} to the
+     * function {@code f}.  For example, this method creates a {@code IntStream}
+     * that has the following elements: {@code seed}, {@code f(seed)},
+     * {@code f(f(seed))} etc.
+     *
+     * @param seed The first {@code int} element, at position {@code 0}, in the
+     *        stream
+     * @param f The function to be applied to an element at position
+     *        {@code n - 1} in the {@code IntStream} to produce the next element
+     *        at position {@code n}, where {@code n > 0}
      * @return A sequential {@code IntStream} that is an infinite sequence of
      *         {@code int} elements
      */
@@ -527,6 +549,7 @@
      *         of generated {@code int} elements
      */
     public static IntStream generateInt(IntSupplier s) {
+        Objects.requireNonNull(s);
         InfiniteIterator.OfInt iterator = s::getAsInt;
         return intStream(Spliterators.spliteratorUnknownSize(
                 iterator,
@@ -601,14 +624,21 @@
 
     /**
      * Creates a sequential {@code LongStream} that is an infinite sequence of
-     * {@code long} elements.  The first element is {@code seed}, the second
-     * element is the result of applying {@code seed} to the function {@code f},
-     * and the nth element is the result of applying the nth minus one element
-     * to the function {@code f}.
+     * {@code long} elements produced by repeated application of a function
+     * {@code f} to {@code seed}.
      *
-     * @param seed The first {@code long} element in sequence
-     * @param f The function to be applied to the nth minus one element to
-     *        produce the nth element, where n > 1
+     * <p>The first element at position {@code 0} in the {@code LongStream} is
+     * {@code seed}. An element at position {@code n}, where {@code n > 0},
+     * is the result of applying the element at position {@code n - 1} to the
+     * function {@code f}.  For example, this method creates a
+     * {@code LongStream} that has the following elements: {@code seed},
+     * {@code f(seed)}, {@code f(f(seed))} etc.
+     *
+     * @param seed The first {@code long} element, at position {@code 0}, in the
+     *        stream
+     * @param f The function to be applied to an element at position
+     *        {@code n - 1} in the {@code LongStream} to produce the next
+     *        element at position {@code n}, where {@code n > 0}
      * @return A sequential {@code LongStream} that is an infinite sequence of
      *         {@code long} elements
      */
@@ -650,6 +680,7 @@
      *         of generated {@code long} elements
      */
     public static LongStream generateLong(LongSupplier s) {
+        Objects.requireNonNull(s);
         InfiniteIterator.OfLong iterator = s::getAsLong;
         return longStream(Spliterators.spliteratorUnknownSize(
                 iterator,
@@ -723,16 +754,23 @@
     // Infinite DoubleStream generators
 
     /**
-     * Creates a sequential {@code DoubleStream} that is an infinite sequence
-     * of {@code double} elements.  The first element is {@code seed}, the
-     * second element is the result of applying {@code seed} to the function
-     * {@code f}, and the nth element is the result of applying the nth minus
-     * one element to the function {@code f}.
+     * Creates a sequential {@code DoubleStream} that is an infinite sequence of
+     * {@code double} elements produced by repeated application of a function
+     * {@code f} to {@code seed}.
      *
-     * @param seed The first {@code double} element in sequence
-     * @param f The function to be applied to the nth minus one element to
-     *        produce the nth element, where n > 1
-     * @return A {@code DoubleStream} that is an infinite sequence of
+     * <p>The first element at position {@code 0} in the {@code DoubleStream} is
+     * {@code seed}. An element at position {@code n}, where {@code n > 0},
+     * is the result of applying the element at position {@code n - 1} to the
+     * function {@code f}.  For example, this method creates a
+     * {@code DoubleStream} that has the following elements: {@code seed},
+     * {@code f(seed)}, {@code f(f(seed))} etc.
+     *
+     * @param seed The first {@code double} element, at position {@code 0}, in
+     *        the stream
+     * @param f The function to be applied to an element at position
+     *        {@code n - 1} in the {@code DoubleStream} to produce the next
+     *        element at position {@code n}, where {@code n > 0}
+     * @return A sequential {@code DoubleStream} that is an infinite sequence of
      *         {@code double} elements
      */
     public static DoubleStream iterateDouble(final double seed, final DoubleUnaryOperator f) {
@@ -768,10 +806,11 @@
      * @param s the {@code DoubleSupplier} of generated elements; may have
      *        side-effects.  The {@code DoubleSupplier} will not be invoked
      *        concurrently so it need not protect access to mutable state.
-     * @return A new sequential {@code DoubleStream} that is an infinite sequence
-     *         of generated {@code double} elements
+     * @return A new sequential {@code DoubleStream} that is an infinite
+     *         sequence of generated {@code double} elements
      */
     public static DoubleStream generateDouble(DoubleSupplier s) {
+        Objects.requireNonNull(s);
         InfiniteIterator.OfDouble iterator = s::getAsDouble;
         return doubleStream(Spliterators.spliteratorUnknownSize(
                 iterator,