changeset 7555:a65fb326969d

- doc updates. - fixed bug in zip. The zipped stream is infinite only if both streams are inifinite.
author psandoz
date Mon, 04 Mar 2013 15:35:55 +0100
parents c9c3e504e55b
children 9dc2126deb55
files src/share/classes/java/util/stream/Streams.java
diffstat 1 files changed, 144 insertions(+), 158 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/stream/Streams.java	Fri Mar 01 10:38:22 2013 -0800
+++ b/src/share/classes/java/util/stream/Streams.java	Mon Mar 04 15:35:55 2013 +0100
@@ -40,9 +40,14 @@
 import java.util.function.UnaryOperator;
 
 /**
- * This class contains various methods that operate on and/or return instances
- * of {@link Stream}, as well as the primitive specializations
- * {@link IntStream}, {@link LongStream}, and {@link DoubleStream}.
+ * This class contains various methods that operate on and/or create streams
+ * that are instances of {@link Stream}, as well as the primitive
+ * specializations {@link IntStream}, {@link LongStream}, and
+ * {@link DoubleStream}.
+ * <p>
+ * Unless otherwise stated methods that create streams will create sequential
+ * streams.  A sequential stream can be transformed into a parallel stream by
+ * calling the {@code parallel()} method on the created stream.
  *
  * @since 1.8
  */
@@ -60,18 +65,18 @@
     // Stream construction
 
     /**
-     * Creates an empty stream.
+     * Creates an empty sequential {@code Stream}.
      *
      * @param <T> Type of elements
-     * @return An empty stream
+     * @return An empty sequential {@code Stream}
      */
     public static<T> Stream<T> emptyStream() {
         return stream(Spliterators.<T>emptySpliterator());
     }
 
     /**
-     * Creates a new sequential stream whose source is a {@code Supplier} of a
-     * non-lazy {@code Spliterator}.
+     * Creates a new sequential {@code Stream} whose source is a
+     * {@code Supplier} of a non-lazy {@code Spliterator}.
      * <p>
      * The non-lazy {@code Spliterator} is obtained from the {@code Supplier}
      * when the terminal operation of the stream pipeline commences.  See
@@ -83,7 +88,7 @@
      *        {@code Spliterator}.  The characteristics must be equal to
      *        {@code source.get().getCharacteristics()}
      * @param <T> Type of elements
-     * @return A new stream
+     * @return A new sequential {@code Stream}
      */
     public static<T> Stream<T> stream(Supplier<? extends Spliterator<T>> source, int characteristics) {
         Objects.requireNonNull(source);
@@ -92,8 +97,8 @@
     }
 
     /**
-     * Creates a new parallel stream whose source is a {@code Supplier} of a
-     * non-lazy {@code Spliterator}.
+     * Creates a new parallel {@code Stream} whose source is a {@code Supplier}
+     * of a non-lazy {@code Spliterator}.
      * <p>
      * The non-lazy {@code Spliterator} is obtained from the {@code Supplier}
      * when the terminal operation of the stream pipeline commences.
@@ -105,7 +110,7 @@
      *        {@code Spliterator}. The characteristics must be equal to
      *        {@code source.get().getCharacteristics()}
      * @param <T> Type of elements
-     * @return A new stream
+     * @return A new parallel {@code Stream}
      */
     public static<T> Stream<T> parallelStream(Supplier<? extends Spliterator<T>> source, int characteristics) {
         Objects.requireNonNull(source);
@@ -114,12 +119,12 @@
     }
 
     /**
-     * Creates a new sequential stream whose source is a lazy
+     * Creates a new sequential {@code Stream} whose source is a lazy
      * {@code Spliterator}.
      * <p>
      * The {@code Spliterator} must be <b>lazy</b> and not commit to the
      * sequence of elements it covers until it is invoked with a method that
-     * requires the sequence of elements be known, for example when the size
+     * requires the sequence of elements be known.  For example, when the size
      * estimate is required or when traversal occurs, but not when the
      * characteristics are required.  See
      * <a href="package-summary.html#StreamSources">Stream sources</a> for more
@@ -127,18 +132,19 @@
      *
      * @param source A {@code Spliterator}
      * @param <T> Type of elements
-     * @return A new stream
+     * @return A new sequential {@code Stream}
      */
     public static<T> Stream<T> stream(Spliterator<T> source) {
         return stream(() -> source, source.characteristics());
     }
 
     /**
-     * Creates a new parallel stream whose source is a lazy {@code Spliterator}.
+     * Creates a new parallel {@code Stream} whose source is a lazy
+     * {@code Spliterator}.
      * <p>
      * The {@code Spliterator} must be <b>lazy</b> and not commit to the
      * sequence of elements it covers until it is invoked with a method that
-     * requires the sequence of elements be known, for example when the size
+     * requires the sequence of elements be known.  For example, when the size
      * estimate is required or when traversal occurs, but not when the
      * characteristics are required.  See
      * <a href="package-summary.html#StreamSources">Stream sources</a> for more
@@ -146,7 +152,7 @@
      *
      * @param source A {@code Spliterator}
      * @param <T> Type of elements
-     * @return A new stream
+     * @return A new parallel {@code Stream}
      */
     public static<T> Stream<T> parallelStream(Spliterator<T> source) {
         return parallelStream(() -> source, source.characteristics());
@@ -155,16 +161,16 @@
     // IntStream construction
 
     /**
-     * Creates an empty {@code int} stream.
+     * Creates an empty sequential {@code IntStream}.
      *
-     * @return An empty {@code int} stream
+     * @return An empty sequential {@code IntStream}
      */
     public static IntStream emptyIntStream() {
         return intStream(Spliterators.emptyIntSpliterator());
     }
 
     /**
-     * Creates a new sequential {@code int} stream whose source is a
+     * Creates a new sequential {@code IntStream} whose source is a
      * {@code Supplier} of a non-lazy {@code Spliterator.OfInt}.
      * <p>
      * The non-lazy {@code Spliterator.OfInt} is obtained from the
@@ -177,7 +183,7 @@
      * @param characteristics Characteristics of the supplied
      *        {@code Spliterator.OfInt}. The characteristics must be equal to
      *        {@code source.get().getCharacteristics()}
-     * @return A new {@code int} stream
+     * @return A new sequential {@code IntStream}
      */
     public static IntStream intStream(Supplier<? extends Spliterator.OfInt> source, int characteristics) {
         return new IntPipeline<>(source,
@@ -185,7 +191,7 @@
     }
 
     /**
-     * Creates a new parallel {@code int} stream whose source is a
+     * Creates a new parallel {@code IntStream} whose source is a
      * {@code Supplier} of a non-lazy {@code Spliterator.OfInt}.
      * <p>
      * The non-lazy {@code Spliterator.OfInt} is obtained from the
@@ -198,7 +204,7 @@
      * @param characteristics Characteristics of the supplied
      *        {@code Spliterator.OfInt}. The characteristics must be equal to
      *        {@code source.get().getCharacteristics()}
-     * @return A new {@code int} stream
+     * @return A new parallel {@code IntStream}
      */
     public static IntStream intParallelStream(Supplier<? extends Spliterator.OfInt> source, int characteristics) {
         return new IntPipeline<>(source,
@@ -206,38 +212,38 @@
     }
 
     /**
-     * Creates a new sequential {@code int} stream whose source is a lazy
+     * Creates a new sequential {@code IntStream} whose source is a lazy
      * {@code Spliterator.OfInt}.
      * <p>
      * The {@code Spliterator.OfInt} must be <b>lazy</b> and not commit to the
      * sequence of elements it covers until it is invoked with a method that
-     * requires the sequence of elements be known, for example when the size
+     * requires the sequence of elements be known.  For example, when the size
      * estimate is required or when traversal occurs, but not when the
      * characteristics are required.  See
      * <a href="package-summary.html#StreamSources">Stream sources</a> for more
      * details.
      *
      * @param source A {@code Spliterator.OfInt}
-     * @return A new {@code int} stream
+     * @return A new sequential {@code IntStream}
      */
     public static IntStream intStream(Spliterator.OfInt source) {
         return intStream(() -> source, source.characteristics());
     }
 
     /**
-     * Creates a new parallel {@code int} stream whose source is a lazy
+     * Creates a new parallel {@code IntStream} whose source is a lazy
      * {@code Spliterator.OfInt}.
      * <p>
      * The {@code Spliterator.OfInt} must be <b>lazy</b> and not commit to the
      * sequence of elements it covers until it is invoked with a method that
-     * requires the sequence of elements be known, for example when the size
+     * requires the sequence of elements be known.  For example, when the size
      * estimate is required or when traversal occurs, but not when the
      * characteristics are required.  See
      * <a href="package-summary.html#StreamSources">Stream sources</a> for more
      * details.
      *
      * @param source A {@code Spliterator.OfInt}
-     * @return A new {@code int} stream
+     * @return A new parallel {@code IntStream}
      */
     public static IntStream intParallelStream(Spliterator.OfInt source) {
         return intParallelStream(() -> source, source.characteristics());
@@ -246,16 +252,16 @@
     // LongStream construction
 
     /**
-     * Creates an empty {@code long} stream.
+     * Creates an empty sequential {@code LongStream}.
      *
-     * @return An empty {@code long} stream
+     * @return An empty sequential {@code LongStream}
      */
     public static LongStream emptyLongStream() {
         return longStream(Spliterators.emptyLongSpliterator());
     }
 
     /**
-     * Creates a new sequential {@code long} stream whose source is a
+     * Creates a new sequential {@code LongStream} whose source is a
      * {@code Supplier} of a non-lazy {@code Spliterator.OfLong}.
      * <p>
      * The non-lazy {@code Spliterator.OfLong} is obtained from the
@@ -268,7 +274,7 @@
      * @param characteristics Characteristics of the supplied
      *        {@code Spliterator.OfLong}. The characteristics must be equal to
      *        {@code source.get().getCharacteristics()}
-     * @return A new {@code long} stream
+     * @return A new sequential {@code LongStream}
      */
     public static LongStream longStream(Supplier<? extends Spliterator.OfLong> source, int characteristics) {
         return new LongPipeline<>(source,
@@ -276,7 +282,7 @@
     }
 
     /**
-     * Creates a new parallel {@code long} stream whose source is a
+     * Creates a new parallel {@code LongStream} whose source is a
      * {@code Supplier} of a non-lazy {@code Spliterator.OfLong}.
      * <p>
      * The non-lazy {@code Spliterator.OfLong} is obtained from the
@@ -289,7 +295,7 @@
      * @param characteristics Characteristics of the supplied
      *        {@code Spliterator.OfLong}. The characteristics must be equal to
      *        {@code source.get().getCharacteristics()}
-     * @return A new {@code long} stream
+     * @return A new parallel {@code LongStream}
      */
     public static LongStream longParallelStream(Supplier<? extends Spliterator.OfLong> source, int characteristics) {
         return new LongPipeline<>(source,
@@ -297,38 +303,38 @@
     }
 
     /**
-     * Creates a new sequential {@code long} stream whose source is a lazy
+     * Creates a new sequential {@code LongStream} whose source is a lazy
      * {@code Spliterator.OfLong}.
      * <p>
      * The {@code Spliterator.OfLong} must be <b>lazy</b> and not commit to the
      * sequence of elements it covers until it is invoked with a method that
-     * requires the sequence of elements be known, for example when the size
+     * requires the sequence of elements be known.  For example, when the size
      * estimate is required or when traversal occurs, but not when the
      * characteristics are required.  See
      * <a href="package-summary.html#StreamSources">Stream sources</a> for more
      * details.
      *
      * @param source A {@code Spliterator.OfLong}
-     * @return A new {@code long} stream
+     * @return A new sequential {@code LongStream}
      */
     public static LongStream longStream(Spliterator.OfLong source) {
         return longStream(() -> source, source.characteristics());
     }
 
     /**
-     * Creates a new parallel {@code long} stream whose source is a lazy
+     * Creates a new parallel {@code LongStream} whose source is a lazy
      * {@code Spliterator.OfLong}.
      * <p>
      * The {@code Spliterator.OfLong} must be <b>lazy</b> and not commit to the
      * sequence of elements it covers until it is invoked with a method that
-     * requires the sequence of elements be known, for example when the size
+     * requires the sequence of elements be known.  For example, when the size
      * estimate is required or when traversal occurs, but not when the
      * characteristics are required.  See
      * <a href="package-summary.html#StreamSources">Stream sources</a> for more
      * details.
      *
      * @param source A {@code Spliterator.OfLong}
-     * @return A new {@code long} stream
+     * @return A new parallel {@code LongStream}
      */
     public static LongStream longParallelStream(Spliterator.OfLong source) {
         return longParallelStream(() -> source, source.characteristics());
@@ -337,16 +343,16 @@
     // DoubleStream construction
 
     /**
-     * Creates an empty {@code double} stream.
+     * Creates an empty sequential {@code DoubleStream}.
      *
-     * @return An empty {@code double} stream
+     * @return An empty sequential {@code DoubleStream}
      */
     public static DoubleStream emptyDoubleStream() {
         return doubleStream(Spliterators.emptyDoubleSpliterator());
     }
 
     /**
-     * Creates a new sequential {@code double} stream whose source is a
+     * Creates a new sequential {@code DoubleStream} whose source is a
      * {@code Supplier} of a non-lazy {@code Spliterator.OfDouble}.
      * <p>
      * The non-lazy {@code Spliterator.OfDouble} is obtained from the
@@ -359,7 +365,7 @@
      * @param characteristics Characteristics of the supplied
      *        {@code Spliterator.OfDouble}. The characteristics must be equal to
      *        {@code source.get().getCharacteristics()}
-     * @return A new {@code double} stream
+     * @return A new sequential {@code DoubleStream}
      */
     public static DoubleStream doubleStream(Supplier<? extends Spliterator.OfDouble> source,
                                             int characteristics) {
@@ -368,7 +374,7 @@
     }
 
     /**
-     * Creates a new parallel {@code double} stream whose source is a
+     * Creates a new parallel {@code DoubleStream} whose source is a
      * {@code Supplier} of a non-lazy {@code Spliterator.OfDouble}.
      * <p>
      * The non-lazy {@code Spliterator.OfDouble} is obtained from the
@@ -381,7 +387,7 @@
      * @param characteristics Characteristics of the supplied
      *        {@code Spliterator.OfDouble}. The characteristics must be equal to
      *        {@code source.get().getCharacteristics()}
-     * @return A new {@code double} stream
+     * @return A new parallel {@code DoubleStream}
      */
     public static DoubleStream doubleParallelStream(Supplier<? extends Spliterator.OfDouble> source,
                                                     int characteristics) {
@@ -390,38 +396,38 @@
     }
 
     /**
-     * Creates a new sequential {@code double} stream whose source is a lazy
+     * Creates a new sequential {@code DoubleStream} whose source is a lazy
      * {@code Spliterator.OfDouble}.
      * <p>
      * The {@code Spliterator.OfDouble} must be <b>lazy</b> and not commit to
      * the sequence of elements it covers until it is invoked with a method that
-     * requires the sequence of elements be known, for example when the size
+     * requires the sequence of elements be known.  For example, when the size
      * estimate is required or when traversal occurs, but not when the
      * characteristics are required.  See
      * <a href="package-summary.html#StreamSources">Stream sources</a> for more
      * details.
      *
      * @param source A {@code Spliterator.OfDouble}
-     * @return A new {@code double} stream
+     * @return A new sequential {@code DoubleStream}
      */
     public static DoubleStream doubleStream(Spliterator.OfDouble source) {
         return doubleStream(() -> source, source.characteristics());
     }
 
     /**
-     * Creates a new parallel {@code double} stream whose source is a lazy
+     * Creates a new parallel {@code DoubleStream} whose source is a lazy
      * {@code Spliterator.OfDouble}.
      * <p>
      * The {@code Spliterator.OfDouble} must be <b>lazy</b> and not commit to
      * the sequence of elements it covers until it is invoked with a method that
-     * requires the sequence of elements be known, for example when the size
+     * requires the sequence of elements be known.  For example, when the size
      * estimate is required or when traversal occurs, but not when the
      * characteristics are required.  See
      * <a href="package-summary.html#StreamSources">Stream sources</a> for more
      * details.
      *
      * @param source A {@code Spliterator.OfDouble}
-     * @return A new {@code double} stream
+     * @return A new parallel {@code DoubleStream}
      */
     public static DoubleStream doubleParallelStream(Spliterator.OfDouble source) {
         return doubleParallelStream(() -> source, source.characteristics());
@@ -430,20 +436,18 @@
     // Infinite Stream generators
 
     /**
-     * Creates a sequential 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}.
-     * <p>
-     * To transform into a parallel stream call the {@code parallel()} method on
-     * the created stream.
+     * 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}.
      *
      * @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
      * @param <T> The type of elements
-     * @return A stream that is an infinite sequence of elements
+     * @return A new sequential {@code Stream} that is an infinite sequence of
+     *         elements
      */
     public static<T> Stream<T> iterate(final T seed, final UnaryOperator<T> f) {
         Objects.requireNonNull(f);
@@ -459,21 +463,19 @@
     }
 
     /**
-     * Creates a sequential stream that is an infinite sequence of supplied
-     * elements.  Each element is supplied in sequence order.
+     * Creates a sequential {@code Stream} that is an infinite sequence of
+     * supplied elements.  Each element is supplied in sequence order.
      * <p>
      * A {@code Supplier} can supply constant values, such as
      * {@code () -> "CONSTANT"}, or can supply non-constant values in which case
      * the {@code Supplier} may have side-effects.
-     * <p>
-     * To transform into a parallel stream call the {@code parallel()} method on
-     * the created stream.
      *
      * @param s the {@code Supplier} of elements; may have side-effects.  The
      *        {@code Supplier} will not be invoked concurrently so it need not
      *        protect access to mutable state.
      * @param <T> The type of elements
-     * @return A stream that is an infinite sequence of elements
+     * @return A new sequential {@code Stream} that is an infinite sequence of
+     *         elements
      */
     public static<T> Stream<T> generate(Supplier<T> s) {
         InfiniteIterator<T> iterator = s::get;
@@ -483,20 +485,17 @@
     // Infinite IntStream generators and ranges
 
     /**
-     * Creates a sequential {@code int} stream that is an infinite sequence of
+     * 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}.
-     * <p>
-     * To transform into a parallel stream call the {@code parallel()} method on
-     * the created stream.
      *
      * @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
-     * @return An {@code int} stream that is an infinite sequence of {@code int}
-     *         elements
+     * @return A sequential {@code IntStream} that is an infinite sequence of
+     *         {@code int} elements
      */
     public static IntStream iterateInt(final int seed, final IntUnaryOperator f) {
         Objects.requireNonNull(f);
@@ -514,22 +513,19 @@
     }
 
     /**
-     * Creates a sequential {@code int} stream that is an infinite sequence of
+     * Creates a sequential {@code IntStream} that is an infinite sequence of
      * supplied {@code int} elements.  Each element is supplied in sequence
      * order.
      * <p>
      * A {@code IntSupplier} can supply constant values, such as
      * {@code () -> 123}, or can supply non-constant values in which case the
      * {@code IntSupplier} may have side-effects.
-     * <p>
-     * To transform into a parallel stream call the {@code parallel()} method on
-     * the created stream.
      *
      * @param s the {@code IntSupplier} of elements; may have side-effects.  The
      *        {@code IntSupplier} will not be invoked concurrently so it need
      *        not protect access to mutable state.
-     * @return An {@code int} stream that is an infinite sequence of {@code int}
-     *         elements
+     * @return A sequential {@code IntStream} that is an infinite sequence of
+     *         {@code int} elements
      */
     public static IntStream generateInt(IntSupplier s) {
         InfiniteIterator.OfInt iterator = s::getAsInt;
@@ -537,9 +533,9 @@
     }
 
     /**
-     * Returns an {@link IntStream} of {@code int} values from {@code start}
-     * (inclusive) to {@code end} (exclusive) by an incremental or decremental
-     * step of 1.
+     * Creates a sequential {@code IntStream} of {@code int} elements from
+     * {@code start} (inclusive) to {@code end} (exclusive) by an incremental or
+     * decremental step of 1.
      * <p>
      * @implSpec
      * The implementation behaves as if:
@@ -549,15 +545,16 @@
      *
      * @param start the (inclusive) initial value
      * @param end the exclusive upper bound
-     * @return An {@code IntStream} for a range of {@code int} values
+     * @return A sequential {@code IntStream} for a range of {@code int}
+     *         elements
      */
     public static IntStream intRange(int start, int end) {
         return intRange(start, end, start <= end ? 1 : -1);
     }
 
     /**
-     * Returns an {@link IntStream} of {@code int} values from {@code start}
-     * (inclusive) to {@code end} (exclusive) by {@code step}.
+     * Creates a sequential {@code IntStream} of {@code int} elements from
+     * {@code start} (inclusive) to {@code end} (exclusive) by {@code step}.
      * <p>
      * If {@code start} is less than {@code end} and  {@code step} is greater
      * than 0 then a stream of increasing values is returned. If {@code start}
@@ -574,11 +571,12 @@
      * @param start the (inclusive) initial value
      * @param end the exclusive upper bound
      * @param step the difference between consecutive values
-     * @return An {@code IntStream} for a range of {@code int} values
+     * @return A sequential {@code IntStream} for a range of {@code int}
+     *         elements
      * @throws IllegalArgumentException
      *         if {@code start} is greater than {@code end} and {@code step} is
      *         greater than 0, or if {@code start} is less than {@code end} and
-     *         the {@code step} is less than 0, or {@code step} is equal to 0.
+     *         {@code step} is less than 0, or {@code step} is equal to 0.
      */
     public static IntStream intRange(int start, int end, int step) {
         if (step > 0) {
@@ -600,19 +598,16 @@
     // Infinite LongStream generators and ranges
 
     /**
-     * Creates a sequential {@code long} stream that is an infinite sequence of
+     * 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}.
-     * <p>
-     * To transform into a parallel stream call the {@code parallel()} method on
-     * the created stream.
      *
      * @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
-     * @return A {@code long} stream that is an infinite sequence of
+     * @return A sequential {@code LongStream} that is an infinite sequence of
      *         {@code long} elements
      */
     public static LongStream iterateLong(final long seed, final LongUnaryOperator f) {
@@ -631,21 +626,18 @@
     }
 
     /**
-     * Creates a sequential {@code long} stream that is an infinite sequence of
+     * Creates a sequential {@code LongStream} that is an infinite sequence of
      * supplied {@code long} elements.  Each element is supplied in sequence
      * order.
      * <p>
      * A {@code LongSupplier} can supply constant values, such as
      * {@code () -> 123L}, or can supply non-constant values in which case the
      * {@code LongSupplier} may have side-effects.
-     * <p>
-     * To transform into a parallel stream call the {@code parallel()} method on
-     * the created stream.
      *
      * @param s the {@code LongSupplier} of elements; may have side-effects.
      *        The {@code LongSupplier} will not be invoked concurrently so it
      *        need not protect access to mutable state.
-     * @return A {@code long} stream that is an infinite sequence of
+     * @return A sequential {@code LongStream} that is an infinite sequence of
      *         {@code long} elements
      */
     public static LongStream generateLong(LongSupplier s) {
@@ -654,9 +646,9 @@
     }
 
     /**
-     * Returns an {@link LongStream} of {@code long} values from {@code start}
-     * (inclusive) to {@code end} (exclusive) by an incremental or decremental
-     * step of 1.
+     * Creates a sequential {@link LongStream} of {@code long} elements from
+     * {@code start} (inclusive) to {@code end} (exclusive) by an incremental or
+     * decremental step of 1.
      * <p>
      * @implSpec
      * The implementation behaves as if:
@@ -666,15 +658,16 @@
      *
      * @param start the (inclusive) initial value
      * @param end the exclusive upper bound
-     * @return A {@code LongStream} for a range of {@code long} values
+     * @return A sequential {@code LongStream} for a range of {@code long}
+     *         elements
      */
     public static LongStream longRange(long start, final long end) {
         return longRange(start, end, start <= end ? 1 : -1);
     }
 
     /**
-     * Returns an {@link LongStream} of {@code long} values from {@code start}
-     * (inclusive) to {@code end} (exclusive) by {@code step}.
+     * Creates a sequential {@link LongStream} of {@code long} elements from
+     * {@code start} (inclusive) to {@code end} (exclusive) by {@code step}.
      * <p>
      * If {@code start} is less than {@code end} and  {@code step} is greater
      * than 0 then a stream of increasing values is returned. If {@code start}
@@ -691,11 +684,12 @@
      * @param start the (inclusive) initial value
      * @param end the exclusive upper bound
      * @param step the difference between consecutive values
-     * @return A {@code LongStream} for a range of {@code long} values
+     * @return A sequential {@code LongStream} for a range of {@code long}
+     *         elements
      * @throws IllegalArgumentException
      *         if {@code start} is greater than {@code end} and {@code step} is
      *         greater than 0, or if {@code start} is less than {@code end} and
-     *         the {@code step} is less than 0, or {@code step} is equal to 0.
+     *         {@code step} is less than 0, or {@code step} is equal to 0.
      */
     public static LongStream longRange(long start, final long end, final long step) {
         if (step > 0) {
@@ -717,19 +711,16 @@
     // Infinite DoubleStream generators
 
     /**
-     * Creates a sequential {@code double} stream that is an infinite sequence
+     * 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}.
-     * <p>
-     * To transform into a parallel stream call the {@code parallel()} method on
-     * the created stream.
      *
      * @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 double} stream that is an infinite sequence of
+     * @return A {@code DoubleStream} that is an infinite sequence of
      *         {@code double} elements
      */
     public static DoubleStream iterateDouble(final double seed, final DoubleUnaryOperator f) {
@@ -748,21 +739,18 @@
     }
 
     /**
-     * Creates a sequential {@code double} stream that is an infinite sequence
+     * Creates a sequential {@code DoubleStream} that is an infinite sequence
      * of supplied {@code double} elements.  Each element is supplied in
      * sequence order.
      * <p>
      * A {@code DoubleSupplier} can supply constant values, such as
      * {@code () -> 123.0}, or can supply non-constant values in which case the
      * {@code DoubleSupplier} may have side-effects.
-     * <p>
-     * To transform into a parallel stream call the {@code parallel()} method on
-     * the created stream.
      *
      * @param s the {@code DoubleSupplier} of elements; may have side-effects.
      *        The {@code DoubleSupplier} will not be invoked concurrently so it
      *        need not protect access to mutable state.
-     * @return A {@code double} stream that is an infinite sequence of
+     * @return A {@code DoubleStream} that is an infinite sequence of
      *         {@code double} elements
      */
     public static DoubleStream generateDouble(DoubleSupplier s) {
@@ -773,20 +761,24 @@
     // Stream combining functions
 
     /**
-     * Creates a concatenated stream whose elements are all the elements, in
-     * encounter order if any, of a first stream proceeded by all the elements
-     * of a second stream, in encounter order if any.
+     * Creates a lazy concatenated {@code Stream} whose elements are all the
+     * elements of a first {@code Stream} succeeded by all the elements of the
+     * second {@code Stream}.
      * <p>
-     * The concatenated stream is lazy and elements are not consumed until the
-     * terminal operation is executed.
+     * The encounter order, if any, of both {@code Stream}s are preserved in the
+     * concatenated {@code Stream}.  The combined {@code Stream} will have an
+     * encounter order if both {@code Stream}s have an encounter order.
      * <p>
-     * To transform into a parallel stream call the {@code parallel()} method on
-     * the created stream.
+     * The combined {@code Stream} is a parallel {@code Stream} if either
+     * {@code Stream} is a parallel {@code Stream}, otherwise the combined
+     * {@code Stream} is a sequential {@code Stream}.
      *
-     * @param a The first stream
-     * @param b The second stream to concatenate on to end of the first stream
+     * @param a The first {@code Stream}
+     * @param b The second {@code Stream} to concatenate on to end of the first
+     *        stream
      * @param <T> Type of elements
-     * @return A concatenated stream
+     * @return A {@code Stream} that is the concatenation of the two
+     *         {@code Stream}s
      */
     public static<T> Stream<T> concat(Stream<? extends T> a, Stream<? extends T> b) {
         @SuppressWarnings("unchecked")
@@ -846,7 +838,7 @@
             @Override
             public int characteristics() {
                 if (beforeSplit) {
-                    // Concatenation looses DISTINCT and SORTED characteristics
+                    // Concatenation loses DISTINCT and SORTED characteristics
                     int both = aSpliterator.characteristics() & bSpliterator.characteristics() &
                            ~(Spliterator.DISTINCT | Spliterator.SORTED);
 
@@ -868,31 +860,27 @@
     }
 
     /**
+     * Creates a lazy and sequential combined {@code Stream} whose elements are
+     * the result of combining the elements of two {@code Stream}s.
+     * <p>
+     * The encounter order, if any, of both {@code Stream}s are preserved in
+     * the combined stream.  The combined stream will have an encounter order
+     * if both {@code Stream}s have an encounter order.
+     * <p>
+     * The number of elements of the combined {@code Stream} will be the smaller
+     * of the number of elements of the first or second {@code Stream}.  Any
+     * elements remaining in the larger of the two {@code Stream}s will not be
+     * consumed.
      *
-     * Creates a zipped stream whose elements are the result of combining the
-     * elements of two streams, in encounter order if any.
-     * <p>
-     * The number of elements of the zipped stream will be the smaller of the
-     * number of elements of the first or second stream.
-     * <p>
-     * The zipped stream is lazy and elements are not consumed until the
-     * terminal operation is executed. If one stream is larger than the other
-     * then only some of the elements of the larger stream will be consumed, at
-     * most the number of elements consumed will be the same as the total number
-     * of elements of the smaller stream.
-     * <p>
-     * To transform into a parallel stream call the {@code parallel()} method on
-     * the created stream.
-     *
-     * @param a The first stream to combine
-     * @param b The second stream to combine
-     * @param zipper The function applied to an element from the first stream
-     *        and an element from the second stream to produce an element for
-     *        the zipped stream
-     * @param <A> The type of elements of the first stream
-     * @param <B> The type of elements of the second stream
-     * @param <C> The type of elements of the zipped stream
-     * @return A zipped stream
+     * @param a The first {@code Stream} to combine
+     * @param b The second {@code Stream} to combine
+     * @param zipper The function applied to an element from the first
+     *        {@code Stream} and an element from the second {@code Stream} to
+     *        produce an element for the combined {@code Stream}
+     * @param <A> The type of elements of the first {@code Stream}
+     * @param <B> The type of elements of the second {@code Stream}
+     * @param <C> The type of elements of the zipped {@code Stream}
+     * @return A combined {@code Stream}
      */
     public static<A, B, C> Stream<C> zip(Stream<? extends A> a,
                                          Stream<? extends B> b,
@@ -903,13 +891,11 @@
         @SuppressWarnings("unchecked")
         Spliterator<B> bSpliterator = (Spliterator<B>) Objects.requireNonNull(b).spliterator();
 
-        // Zipping looses DISTINCT and SORTED characteristics
-        int both = aSpliterator.characteristics() & bSpliterator.characteristics() &
-                   ~(Spliterator.DISTINCT | Spliterator.SORTED);
-        // Zipping is INFINITE if either stream is INFINITE
-        int either = (aSpliterator.characteristics() | aSpliterator.characteristics()) &
-                     Spliterator.INFINITE;
-        int characteristics = both | either;
+        // Combining loses DISTINCT and SORTED characteristics and for other
+        // characteristics the combined stream has a characteristic if both
+        // streams to combine has the characteristic
+        int characteristics = aSpliterator.characteristics() & bSpliterator.characteristics() &
+                              ~(Spliterator.DISTINCT | Spliterator.SORTED);
 
         long zipSize = ((characteristics & Spliterator.SIZED) != 0)
                      ? Math.min(aSpliterator.getExactSizeIfKnown(), bSpliterator.getExactSizeIfKnown())