Mercurial > hg > openjdk > lambda > jdk
changeset 7546:871862c719a5
Format JavaDoc to 80 character width limit
author | psandoz |
---|---|
date | Thu, 28 Feb 2013 17:35:49 +0100 |
parents | af323ffe1aa7 |
children | 9ccdccc3c754 |
files | src/share/classes/java/util/stream/Streams.java |
diffstat | 1 files changed, 292 insertions(+), 180 deletions(-) [+] |
line wrap: on
line diff
--- a/src/share/classes/java/util/stream/Streams.java Wed Feb 27 20:06:16 2013 -0800 +++ b/src/share/classes/java/util/stream/Streams.java Thu Feb 28 17:35:49 2013 +0100 @@ -40,8 +40,9 @@ 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 return instances + * of {@link Stream}, as well as the primitive specializations + * {@link IntStream}, {@link LongStream}, and {@link DoubleStream}. * * @since 1.8 */ @@ -69,14 +70,18 @@ } /** - * Creates a new sequential stream whose source is a {@code Supplier} of a non-lazy {@code Spliterator}. + * Creates a new sequential 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 <a href="package-summary.html#StreamSources">Stream sources</a> for more details. + * The non-lazy {@code Spliterator} is obtained from the {@code Supplier} + * when the terminal operation of the stream pipeline commences. See + * <a href="package-summary.html#StreamSources">Stream sources</a> for more + * details. * * @param source A {@code Supplier} of a {@code Spliterator} - * @param characteristics Characteristics of the supplied {@code Spliterator}. The characteristics - * must be equal to {@code source.get().getCharacteristics()} + * @param characteristics Characteristics of the supplied + * {@code Spliterator}. The characteristics must be equal to + * {@code source.get().getCharacteristics()} * @param <T> Type of elements * @return A new stream */ @@ -87,14 +92,18 @@ } /** - * Creates a new parallel stream whose source is a {@code Supplier} of a non-lazy {@code Spliterator}. + * Creates a new parallel 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 <a href="package-summary.html#StreamSources">Stream sources</a> for more details. + * The non-lazy {@code Spliterator} is obtained from the {@code Supplier} + * when the terminal operation of the stream pipeline commences. + * See <a href="package-summary.html#StreamSources">Stream sources</a> for + * more details. * * @param source A {@code Supplier} of a {@code Spliterator} - * @param characteristics Characteristics of the supplied {@code Spliterator}. The characteristics - * must be equal to {@code source.get().getCharacteristics()} + * @param characteristics Characteristics of the supplied + * {@code Spliterator}. The characteristics must be equal to + * {@code source.get().getCharacteristics()} * @param <T> Type of elements * @return A new stream */ @@ -105,12 +114,16 @@ } /** - * Creates a new sequential stream whose source is a lazy {@code Spliterator}. + * Creates a new sequential 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 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. + * 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 + * 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} * @param <T> Type of elements @@ -123,10 +136,13 @@ /** * Creates a new parallel 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 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. + * 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 + * 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} * @param <T> Type of elements @@ -148,15 +164,19 @@ } /** - * Creates a new sequential {@code int} stream whose source is a {@code Supplier} of a non-lazy - * {@code Spliterator.OfInt}. + * Creates a new sequential {@code int} stream whose source is a + * {@code Supplier} of a non-lazy {@code Spliterator.OfInt}. * <p> - * The non-lazy {@code Spliterator.OfInt} is obtained from the {@code Supplier} when the terminal operation of the - * stream pipeline commences. See <a href="package-summary.html#StreamSources">Stream sources</a> for more details. + * The non-lazy {@code Spliterator.OfInt} is obtained from the + * {@code Supplier} when the terminal operation of the stream pipeline + * commences. + * See <a href="package-summary.html#StreamSources">Stream sources</a> for + * more details. * * @param source A {@code Supplier} of a {@code Spliterator.OfInt} - * @param characteristics Characteristics of the supplied {@code Spliterator.OfInt}. The characteristics - * must be equal to {@code source.get().getCharacteristics()} + * @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 */ public static IntStream intStream(Supplier<? extends Spliterator.OfInt> source, int characteristics) { @@ -165,15 +185,19 @@ } /** - * Creates a new parallel {@code int} stream whose source is a {@code Supplier} of a non-lazy - * {@code Spliterator.OfInt}. + * Creates a new parallel {@code int} stream whose source is a + * {@code Supplier} of a non-lazy {@code Spliterator.OfInt}. * <p> - * The non-lazy {@code Spliterator.OfInt} is obtained from the {@code Supplier} when the terminal operation of the - * stream pipeline commences. See <a href="package-summary.html#StreamSources">Stream sources</a> for more details. + * The non-lazy {@code Spliterator.OfInt} is obtained from the + * {@code Supplier} when the terminal operation of the stream pipeline + * commences. + * See <a href="package-summary.html#StreamSources">Stream sources</a> for + * more details. * * @param source A {@code Supplier} of a {@code Spliterator.OfInt} - * @param characteristics Characteristics of the supplied {@code Spliterator.OfInt}. The characteristics - * must be equal to {@code source.get().getCharacteristics()} + * @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 */ public static IntStream intParallelStream(Supplier<? extends Spliterator.OfInt> source, int characteristics) { @@ -182,12 +206,16 @@ } /** - * Creates a new sequential {@code int} stream whose source is a lazy {@code Spliterator.OfInt}. + * Creates a new sequential {@code int} stream 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 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. + * 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 + * 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 @@ -197,12 +225,16 @@ } /** - * Creates a new parallel {@code int} stream whose source is a lazy {@code Spliterator.OfInt}. + * Creates a new parallel {@code int} stream 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 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. + * 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 + * 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 @@ -223,15 +255,19 @@ } /** - * Creates a new sequential {@code long} stream whose source is a {@code Supplier} of a non-lazy - * {@code Spliterator.OfLong}. + * Creates a new sequential {@code long} stream whose source is a + * {@code Supplier} of a non-lazy {@code Spliterator.OfLong}. * <p> - * The non-lazy {@code Spliterator.OfLong} is obtained from the {@code Supplier} when the terminal operation of the - * stream pipeline commences. See <a href="package-summary.html#StreamSources">Stream sources</a> for more details. + * The non-lazy {@code Spliterator.OfLong} is obtained from the + * {@code Supplier} when the terminal operation of the stream pipeline + * commences. See + * <a href="package-summary.html#StreamSources">Stream sources</a> for more + * details. * * @param source A {@code Supplier} of a {@code Spliterator.OfLong} - * @param characteristics Characteristics of the supplied {@code Spliterator.OfLong}. The characteristics - * must be equal to {@code source.get().getCharacteristics()} + * @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 */ public static LongStream longStream(Supplier<? extends Spliterator.OfLong> source, int characteristics) { @@ -240,15 +276,19 @@ } /** - * Creates a new parallel {@code long} stream whose source is a {@code Supplier} of a non-lazy - * {@code Spliterator.OfLong}. + * Creates a new parallel {@code long} stream whose source is a + * {@code Supplier} of a non-lazy {@code Spliterator.OfLong}. * <p> - * The non-lazy {@code Spliterator.OfLong} is obtained from the {@code Supplier} when the terminal operation of the - * stream pipeline commences. See <a href="package-summary.html#StreamSources">Stream sources</a> for more details. + * The non-lazy {@code Spliterator.OfLong} is obtained from the + * {@code Supplier} when the terminal operation of the stream pipeline + * commences. See + * <a href="package-summary.html#StreamSources">Stream sources</a> for more + * details. * * @param source A {@code Supplier} of a {@code Spliterator.OfLong} - * @param characteristics Characteristics of the supplied {@code Spliterator.OfLong}. The characteristics - * must be equal to {@code source.get().getCharacteristics()} + * @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 */ public static LongStream longParallelStream(Supplier<? extends Spliterator.OfLong> source, int characteristics) { @@ -257,12 +297,16 @@ } /** - * Creates a new sequential {@code long} stream whose source is a lazy {@code Spliterator.OfLong}. + * Creates a new sequential {@code long} stream 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 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. + * 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 + * 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 @@ -272,12 +316,16 @@ } /** - * Creates a new parallel {@code long} stream whose source is a lazy {@code Spliterator.OfLong}. + * Creates a new parallel {@code long} stream 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 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. + * 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 + * 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 @@ -298,16 +346,19 @@ } /** - * Creates a new sequential {@code double} stream whose source is a {@code Supplier} of a non-lazy - * {@code Spliterator.OfDouble}. + * Creates a new sequential {@code double} stream whose source is a + * {@code Supplier} of a non-lazy {@code Spliterator.OfDouble}. * <p> - * The non-lazy {@code Spliterator.OfDouble} is obtained from the {@code Supplier} when the terminal operation of - * the stream pipeline commences. See <a href="package-summary.html#StreamSources">Stream sources</a> for more + * The non-lazy {@code Spliterator.OfDouble} is obtained from the + * {@code Supplier} when the terminal operation of the stream pipeline + * commences. See + * <a href="package-summary.html#StreamSources">Stream sources</a> for more * details. * * @param source A {@code Supplier} of a {@code Spliterator.OfDouble} - * @param characteristics Characteristics of the supplied {@code Spliterator.OfDouble}. The characteristics - * must be equal to {@code source.get().getCharacteristics()} + * @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 */ public static DoubleStream doubleStream(Supplier<? extends Spliterator.OfDouble> source, @@ -317,16 +368,19 @@ } /** - * Creates a new parallel {@code double} stream whose source is a {@code Supplier} of a non-lazy - * {@code Spliterator.OfDouble}. + * Creates a new parallel {@code double} stream whose source is a + * {@code Supplier} of a non-lazy {@code Spliterator.OfDouble}. * <p> - * The non-lazy {@code Spliterator.OfDouble} is obtained from the {@code Supplier} when the terminal operation of - * the stream pipeline commences. See <a href="package-summary.html#StreamSources">Stream sources</a> for more + * The non-lazy {@code Spliterator.OfDouble} is obtained from the + * {@code Supplier} when the terminal operation of the stream pipeline + * commences. See + * <a href="package-summary.html#StreamSources">Stream sources</a> for more * details. * * @param source A {@code Supplier} of a {@code Spliterator.OfDouble} - * @param characteristics Characteristics of the supplied {@code Spliterator.OfDouble}. The characteristics - * must be equal to {@code source.get().getCharacteristics()} + * @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 */ public static DoubleStream doubleParallelStream(Supplier<? extends Spliterator.OfDouble> source, @@ -336,12 +390,16 @@ } /** - * Creates a new sequential {@code double} stream whose source is a lazy {@code Spliterator.OfDouble}. + * Creates a new sequential {@code double} stream 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 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. + * 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 + * 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 @@ -351,12 +409,16 @@ } /** - * Creates a new parallel {@code double} stream whose source is a lazy {@code Spliterator.OfDouble}. + * Creates a new parallel {@code double} stream 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 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. + * 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 + * 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 @@ -368,14 +430,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}. + * 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. + * To transform into a parallel stream call the {@code parallel()} method on + * the created stream. * * @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 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 */ @@ -393,16 +459,19 @@ } /** - * Creates a sequential stream that is an infinite sequence of supplied elements. Each element is supplied in - * sequence order. + * Creates a sequential 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> - * 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. + * 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 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 */ @@ -414,15 +483,20 @@ // Infinite IntStream generators and ranges /** - * Creates a sequential {@code int} stream 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}. + * Creates a sequential {@code int} stream 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. + * 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 + * @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 */ public static IntStream iterateInt(final int seed, final IntUnaryOperator f) { Objects.requireNonNull(f); @@ -440,17 +514,22 @@ } /** - * Creates a sequential {@code int} stream that is an infinite sequence of supplied {@code int} elements. Each - * element is supplied in sequence order. + * Creates a sequential {@code int} stream 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. + * 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. + * 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 + * @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 */ public static IntStream generateInt(IntSupplier s) { InfiniteIterator.OfInt iterator = s::getAsInt; @@ -458,8 +537,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. + * Returns an {@link IntStream} of {@code int} values from {@code start} + * (inclusive) to {@code end} (exclusive) by an incremental or decremental + * step of 1. * <p> * @implSpec * The implementation behaves as if: @@ -476,15 +556,17 @@ } /** - * Returns an {@link IntStream} of {@code int} values from {@code start} (inclusive) to {@code end} (exclusive) - * by {@code step}. + * Returns an {@link IntStream} of {@code int} values 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} is greater than {@code end} and {@code step} is less than - * 0 then a stream of decreasing values is returned. If {@code start} is equal to {@code end} then - * an empty stream is returned. + * 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} + * is greater than {@code end} and {@code step} is less than 0 then a stream + * of decreasing values is returned. If {@code start} is equal to + * {@code end} then an empty stream is returned. * <p> - * An equivalent sequence of increasing values can be produced, sequentially, using a {@code for} loop as follows: + * An equivalent sequence of increasing values can be produced, + * sequentially, using a {@code for} loop as follows: * <pre> * for (int i = start; i < end ; i += step) { ... } * </pre> @@ -494,9 +576,9 @@ * @param step the difference between consecutive values * @return An {@code IntStream} for a range of {@code int} values * @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. + * 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. */ public static IntStream intRange(int start, int end, int step) { if (step > 0) { @@ -518,15 +600,20 @@ // Infinite LongStream generators and ranges /** - * Creates a sequential {@code long} stream 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}. + * Creates a sequential {@code long} stream 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. + * 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 {@code long} elements + * @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 + * {@code long} elements */ public static LongStream iterateLong(final long seed, final LongUnaryOperator f) { Objects.requireNonNull(f); @@ -544,17 +631,22 @@ } /** - * Creates a sequential {@code long} stream that is an infinite sequence of supplied {@code long} elements. Each - * element is supplied in sequence order. + * Creates a sequential {@code long} stream 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. + * 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. + * 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 {@code long} elements + * @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 + * {@code long} elements */ public static LongStream generateLong(LongSupplier s) { InfiniteIterator.OfLong iterator = s::getAsLong; @@ -562,8 +654,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. + * Returns an {@link LongStream} of {@code long} values from {@code start} + * (inclusive) to {@code end} (exclusive) by an incremental or decremental + * step of 1. * <p> * @implSpec * The implementation behaves as if: @@ -580,15 +673,17 @@ } /** - * Returns an {@link LongStream} of {@code long} values from {@code start} (inclusive) to {@code end} (exclusive) - * by {@code step}. + * Returns an {@link LongStream} of {@code long} values 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} is greater than {@code end} and {@code step} is less than - * 0 then a stream of decreasing values is returned. If {@code start} is equal to {@code end} then - * an empty stream is returned. + * 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} + * is greater than {@code end} and {@code step} is less than 0 then a stream + * of decreasing values is returned. If {@code start} is equal to + * {@code end} then an empty stream is returned. * <p> - * An equivalent sequence of increasing values can be produced, sequentially, using a {@code for} loop as follows: + * An equivalent sequence of increasing values can be produced, + * sequentially, using a {@code for} loop as follows: * <pre> * for (long i = start; i < end ; i += step) { ... } * </pre> @@ -598,9 +693,9 @@ * @param step the difference between consecutive values * @return A {@code LongStream} for a range of {@code long} values * @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. + * 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. */ public static LongStream longRange(long start, final long end, final long step) { if (step > 0) { @@ -622,15 +717,20 @@ // Infinite DoubleStream generators /** - * Creates a sequential {@code double} stream 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 double} stream 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. + * 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 {@code double} elements + * @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 + * {@code double} elements */ public static DoubleStream iterateDouble(final double seed, final DoubleUnaryOperator f) { Objects.requireNonNull(f); @@ -648,17 +748,22 @@ } /** - * Creates a sequential {@code double} stream that is an infinite sequence of supplied {@code double} elements. - * Each element is supplied in sequence order. + * Creates a sequential {@code double} stream 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. + * 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. + * 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 {@code double} elements + * @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 + * {@code double} elements */ public static DoubleStream generateDouble(DoubleSupplier s) { InfiniteIterator.OfDouble iterator = s::getAsDouble; @@ -668,12 +773,15 @@ // 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 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. * <p> - * The concatenated stream is lazy and elements are not consumed until the terminal operation is executed. + * The concatenated stream is lazy and elements are not consumed until the + * terminal operation is executed. * <p> - * To transform into a parallel stream call the {@code parallel()} method on the created stream. + * To transform into a parallel stream call the {@code parallel()} method on + * the created stream. * * @param a The first stream * @param b The second stream to concatenate on to end of the first stream @@ -761,22 +869,26 @@ /** * - * Creates a zipped stream whose elements are the result of combining the elements of two streams, in encounter - * order if any. + * 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. + * 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. + * 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. + * 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 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