changeset 8283:720ee175d43d

Rename Stream.singleton -> of, adjust specs for other facory methods
author briangoetz
date Sun, 21 Apr 2013 16:01:35 -0400
parents d907dff00ace
children d01bdf1b0f50
files src/share/classes/java/util/stream/DoubleStream.java src/share/classes/java/util/stream/IntStream.java src/share/classes/java/util/stream/LongStream.java src/share/classes/java/util/stream/Stream.java test-ng/tests/org/openjdk/tests/java/util/stream/StreamBuilderTest.java
diffstat 5 files changed, 137 insertions(+), 135 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/stream/DoubleStream.java	Sun Apr 21 10:30:42 2013 -0700
+++ b/src/share/classes/java/util/stream/DoubleStream.java	Sun Apr 21 16:01:35 2013 -0400
@@ -677,11 +677,21 @@
      * @param t The single element
      * @return A singleton sequential stream
      */
-    public static DoubleStream singleton(double t) {
+    public static DoubleStream of(double t) {
         return StreamSupport.doubleStream(new Streams.DoubleStreamBuilderImpl(t));
     }
 
     /**
+     * Returns a sequential stream whose elements are the specified values.
+     *
+     * @param values the elements of the new stream
+     * @return the new stream
+     */
+    public static DoubleStream of(double... values) {
+        return Arrays.stream(values);
+    }
+
+    /**
      * Returns an infinite sequential {@code DoubleStream} produced by iterative
      * application of a function {@code f} to an initial element {@code seed},
      * producing a {@code Stream} consisting of {@code seed}, {@code f(seed)},
@@ -720,12 +730,12 @@
     }
 
     /**
-     * Returns an infinite sequential {@code DoubleStream} where each element is
+     * Returns a sequential {@code DoubleStream} where each element is
      * generated by an {@code DoubleSupplier}.  This is suitable for generating
      * constant streams, streams of random elements, etc.
      *
      * @param s the {@code DoubleSupplier} for generated elements
-     * @return A new infinite sequential {@code DoubleStream}
+     * @return A new sequential {@code DoubleStream}
      */
     public static DoubleStream generate(DoubleSupplier s) {
         Objects.requireNonNull(s);
@@ -741,86 +751,76 @@
     }
 
     /**
-     * Returns a sequential stream whose elements are the specified values.
-     *
-     * @param values the elements of the new stream
-     * @return the new stream
-     */
-    public static DoubleStream of(double... values) {
-        return Arrays.stream(values);
-    }
-
-    /**
-     * Returns a sequential {@code DoubleStream} from {@code start} (inclusive)
-     * to {@code end} (exclusive) by an incremental or decremental step of 1.0.
+     * Returns a sequential {@code DoubleStream} from {@code startInclusive} (inclusive)
+     * to {@code endExclusive} (exclusive) by an incremental or decremental step of 1.0.
      *
      * @implSpec
      * The implementation behaves as if:
      * <pre>{@code
-     *     doubleRange(start, end, start <= end ? 1.0 : -1.0);
+     *     doubleRange(startInclusive, endExclusive, startInclusive <= endExclusive ? 1.0 : -1.0);
      * }</pre>
      *
-     * @param start the (inclusive) initial value
-     * @param end the exclusive upper bound
+     * @param startInclusive the (inclusive) initial value
+     * @param endExclusive the exclusive upper bound
      * @return A sequential {@code DoubleStream} for a range of {@code double}
      *         elements
      */
-    public static DoubleStream range(double start, double end) {
-        return range(start, end, start <= end ? 1.0 : -1.0);
+    public static DoubleStream range(double startInclusive, double endExclusive) {
+        return range(startInclusive, endExclusive, startInclusive <= endExclusive ? 1.0 : -1.0);
     }
 
     /**
-     * Returns a sequential {@code DoubleStream} from {@code start} (inclusive)
-     * to {@code end} (exclusive) by {@code step}.
+     * Returns a sequential {@code DoubleStream} from {@code startInclusive} (inclusive)
+     * to {@code endExclusive} (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 startInclusive} is less than {@code endExclusive} and {@code step} is greater
+     * than 0 then a stream of increasing values is returned. If {@code startInclusive}
+     * is greater than {@code endExclusive} and {@code step} is less than 0 then a stream
+     * of decreasing values is returned. If {@code startInclusive} is equal to
+     * {@code endExclusive} then an empty stream is returned.
      * <p>
      * An equivalent sequence of increasing values can be produced
      * sequentially using a {@code for} loop as follows:
      * <pre>{@code
-     *     long size = (long) Math.ceil((start - end) / step);
+     *     long size = (long) Math.ceil((startInclusive - endExclusive) / step);
      *     long i = 0
-     *     for (double v = start; i < size; i++, v = start + step * i) {
+     *     for (double v = startInclusive; i < size; i++, v = startInclusive + step * i) {
      *         ...
      *     }
      * }</pre>
      *
-     * @param start the (inclusive) initial value
-     * @param end the exclusive upper bound
+     * @param startInclusive the (inclusive) initial value
+     * @param endExclusive the exclusive upper bound
      * @param step the difference between consecutive values
      * @return A sequential {@code DoubleStream} for a range of {@code double}
      *         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
+     *         if {@code startInclusive} is greater than {@code endExclusive} and {@code step} is
+     *         greater than 0, or if {@code startInclusive} is less than {@code endExclusive} and
      *         {@code step} is less than 0, or {@code step} is equal to 0,
      *         or the size is greater than {@code Long.MAX_VALUE} or is
      *         {@code NaN}.
      */
-    public static DoubleStream range(double start, double end, double step) {
+    public static DoubleStream range(double startInclusive, double endExclusive, double step) {
         // @@@ Need to check for ranges that may not produce distinct values
         //     such as when the step is very small
         //     Also clarify the size of the range which may produce more or less
         //     than expected
         if (step > 0) {
             // Decreasing range with an increasing step value
-            if (start > end) throw new IllegalArgumentException(
-                    String.format("Illegal range: start(%f) > end(%f), step(%f) > 0", start, end, step));
+            if (startInclusive > endExclusive) throw new IllegalArgumentException(
+                    String.format("Illegal range: startInclusive(%f) > endExclusive(%f), step(%f) > 0", startInclusive, endExclusive, step));
         }
         else if (step < 0) {
             // Increasing range with a decreasing step value
-            if (start < end) throw new IllegalArgumentException(
-                    String.format("Illegal range: start(%f) < end(%f), step(%f) < 0", start, end, step));
+            if (startInclusive < endExclusive) throw new IllegalArgumentException(
+                    String.format("Illegal range: startInclusive(%f) < endExclusive(%f), step(%f) < 0", startInclusive, endExclusive, step));
         }
         else if (step == 0) {
             throw new IllegalArgumentException("Illegal range: step(0)");
         }
 
-        double size = Math.ceil((end - start) / step);
+        double size = Math.ceil((endExclusive - startInclusive) / step);
         if (Double.isNaN(size)) {
             throw new IllegalArgumentException(
                     String.format("Illegal range: %f size is NaN", size));
@@ -830,6 +830,6 @@
                     String.format("Illegal range: size %f > Long.MAX_VALUE", size));
         }
 
-        return StreamSupport.doubleStream(new Streams.RangeDoubleSpliterator(start, end, step, 0, (long) size));
+        return StreamSupport.doubleStream(new Streams.RangeDoubleSpliterator(startInclusive, endExclusive, step, 0, (long) size));
     }
 }
--- a/src/share/classes/java/util/stream/IntStream.java	Sun Apr 21 10:30:42 2013 -0700
+++ b/src/share/classes/java/util/stream/IntStream.java	Sun Apr 21 16:01:35 2013 -0400
@@ -682,11 +682,21 @@
      * @param t The single element
      * @return A singleton sequential stream
      */
-    public static IntStream singleton(int t) {
+    public static IntStream of(int t) {
         return StreamSupport.intStream(new Streams.IntStreamBuilderImpl(t));
     }
 
     /**
+     * Returns a sequential stream whose elements are the specified values.
+     *
+     * @param values the elements of the new stream
+     * @return the new stream
+     */
+    public static IntStream of(int... values) {
+        return Arrays.stream(values);
+    }
+
+    /**
      * Returns an infinite sequential {@code IntStream} produced by iterative
      * application of a function {@code f} to an initial element {@code seed},
      * producing a {@code Stream} consisting of {@code seed}, {@code f(seed)},
@@ -725,12 +735,12 @@
     }
 
     /**
-     * Returns an infinite sequential {@code IntStream} where each element is
+     * Returns a sequential {@code IntStream} where each element is
      * generated by an {@code IntSupplier}.  This is suitable for generating
      * constant streams, streams of random elements, etc.
      *
      * @param s the {@code IntSupplier} for generated elements
-     * @return A new infinite sequential {@code IntStream}
+     * @return A new sequential {@code IntStream}
      */
     public static IntStream generate(IntSupplier s) {
         Objects.requireNonNull(s);
@@ -746,74 +756,66 @@
     }
 
     /**
-     * Returns a sequential stream whose elements are the specified values.
-     *
-     * @param values the elements of the new stream
-     * @return the new stream
-     */
-    public static IntStream of(int... values) {
-        return Arrays.stream(values);
-    }
-
-    /**
-     * Returns a sequential {@code IntStream} from {@code start} (inclusive)
-     * to {@code end} (exclusive) by an incremental or decremental step of 1.
+     * Returns a sequential {@code IntStream} from {@code startInclusive} (inclusive)
+     * to {@code endExclusive} (exclusive) by an incremental or decremental step of 1.
      *
      * @implSpec
      * The implementation behaves as if:
      * <pre>{@code
-     *     intRange(start, end, start <= end ? 1 : -1);
+     *     intRange(startInclusive, endExclusive, startInclusive <= endExclusive ? 1 : -1);
      * }</pre>
      *
-     * @param start the (inclusive) initial value
-     * @param end the exclusive upper bound
+     * @param startInclusive the (inclusive) initial value
+     * @param endExclusive the exclusive upper bound
      * @return A sequential {@code IntStream} for a range of {@code int}
      *         elements
      */
-    public static IntStream range(int start, int end) {
-        return range(start, end, start <= end ? 1 : -1);
+    public static IntStream range(int startInclusive, int endExclusive) {
+        return range(startInclusive, endExclusive, startInclusive <= endExclusive ? 1 : -1);
     }
 
     /**
-     * Returns a sequential {@code IntStream} from {@code start} (inclusive)
-     * to {@code end} (exclusive) by {@code step}.
+     * Returns a sequential {@code IntStream} from {@code startInclusive} (inclusive)
+     * to {@code endExclusive} (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 startInclusive} is less than {@code endExclusive} and {@code step} is greater
+     * than 0 then a stream of increasing values is returned. If {@code startInclusive}
+     * is greater than {@code endExclusive} and {@code step} is less than 0 then a stream
+     * of decreasing values is returned. If {@code startInclusive} is equal to
+     * {@code endExclusive} then an empty stream is returned.
      * <p>
      * An equivalent sequence of increasing values can be produced
      * sequentially using a {@code for} loop as follows:
      * <pre>{@code
-     *     for (int i = start; i < end ; i += step) { ... }
+     *     for (int i = startInclusive; i < endExclusive ; i += step) { ... }
      * }</pre>
      *
-     * @param start the (inclusive) initial value
-     * @param end the exclusive upper bound
+     * @param startInclusive the (inclusive) initial value
+     * @param endExclusive the exclusive upper bound
      * @param step the difference between consecutive 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
+     *         if {@code startInclusive} is greater than {@code endExclusive} and {@code step} is
+     *         greater than 0, or if {@code startInclusive} is less than {@code endExclusive} and
      *         {@code step} is less than 0, or if {@code step} is equal to 0.
      */
-    public static IntStream range(int start, int end, int step) {
+    public static IntStream range(int startInclusive, int endExclusive, int step) {
         if (step > 0) {
             // Decreasing range with an increasing step value
-            if (start > end) throw new IllegalArgumentException(
-                    String.format("Illegal range: start(%d) > end(%d), step(%d) > 0", start, end, step));
+            if (startInclusive > endExclusive) throw new IllegalArgumentException(
+                    String.format("Illegal range: startInclusive(%d) > endExclusive(%d), step(%d) > 0",
+                                  startInclusive, endExclusive, step));
         }
         else if (step < 0) {
             // Increasing range with a decreasing step value
-            if (start < end) throw new IllegalArgumentException(
-                    String.format("Illegal range: start(%d) < end(%d), step(%d) < 0", start, end, step));
+            if (startInclusive < endExclusive) throw new IllegalArgumentException(
+                    String.format("Illegal range: startInclusive(%d) < endExclusive(%d), step(%d) < 0",
+                                  startInclusive, endExclusive, step));
         }
         else if (step == 0) {
             throw new IllegalArgumentException("Illegal range: step(0)");
         }
-        return StreamSupport.intStream(new Streams.RangeIntSpliterator(start, end, step));
+        return StreamSupport.intStream(new Streams.RangeIntSpliterator(startInclusive, endExclusive, step));
     }
 }
--- a/src/share/classes/java/util/stream/LongStream.java	Sun Apr 21 10:30:42 2013 -0700
+++ b/src/share/classes/java/util/stream/LongStream.java	Sun Apr 21 16:01:35 2013 -0400
@@ -672,11 +672,21 @@
      * @param t The single element
      * @return A singleton sequential stream
      */
-    public static LongStream singleton(long t) {
+    public static LongStream of(long t) {
         return StreamSupport.longStream(new Streams.LongStreamBuilderImpl(t));
     }
 
     /**
+     * Returns a sequential stream whose elements are the specified values.
+     *
+     * @param values the elements of the new stream
+     * @return the new stream
+     */
+    public static LongStream of(long... values) {
+        return Arrays.stream(values);
+    }
+
+    /**
      * Returns an infinite sequential {@code LongStream} produced by iterative
      * application of a function {@code f} to an initial element {@code seed},
      * producing a {@code Stream} consisting of {@code seed}, {@code f(seed)},
@@ -715,12 +725,12 @@
     }
 
     /**
-     * Returns an infinite sequential {@code LongStream} where each element is
+     * Returns a sequential {@code LongStream} where each element is
      * generated by an {@code LongSupplier}.  This is suitable for generating
      * constant streams, streams of random elements, etc.
      *
      * @param s the {@code LongSupplier} for generated elements
-     * @return A new infinite sequential {@code LongStream}
+     * @return A new sequential {@code LongStream}
      */
     public static LongStream generate(LongSupplier s) {
         Objects.requireNonNull(s);
@@ -736,74 +746,64 @@
     }
 
     /**
-     * Returns a sequential stream whose elements are the specified values.
-     *
-     * @param values the elements of the new stream
-     * @return the new stream
-     */
-    public static LongStream of(long... values) {
-        return Arrays.stream(values);
-    }
-
-    /**
-     * Returns a sequential {@code LongStream} from {@code start} (inclusive)
-     * to {@code end} (exclusive) by an incremental or decremental step of 1.
+     * Returns a sequential {@code LongStream} from {@code startInclusive} (inclusive)
+     * to {@code endExclusive} (exclusive) by an incremental or decremental step of 1.
      *
      * @implSpec
      * The implementation behaves as if:
      * <pre>{@code
-     *     longRange(start, end, start <= end ? 1 : -1);
+     *     longRange(startInclusive, endExclusive, startInclusive <= endExclusive ? 1 : -1);
      * }</pre>
      *
-     * @param start the (inclusive) initial value
-     * @param end the exclusive upper bound
+     * @param startInclusive the (inclusive) initial value
+     * @param endExclusive the exclusive upper bound
      * @return A sequential {@code LongStream} for a range of {@code long}
      *         elements
      */
-    public static LongStream range(long start, final long end) {
-        return range(start, end, start <= end ? 1 : -1);
+    public static LongStream range(long startInclusive, final long endExclusive) {
+        return range(startInclusive, endExclusive, startInclusive <= endExclusive ? 1 : -1);
     }
 
     /**
-     * Returns a sequential {@code LongStream} from {@code start} (inclusive)
-     * to {@code end} (exclusive) by {@code step}.
+     * Returns a sequential {@code LongStream} from {@code startInclusive} (inclusive)
+     * to {@code endExclusive} (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 startInclusive} is less than {@code endExclusive} and {@code step} is greater
+     * than 0 then a stream of increasing values is returned. If {@code startInclusive}
+     * is greater than {@code endExclusive} and {@code step} is less than 0 then a stream
+     * of decreasing values is returned. If {@code startInclusive} is equal to
+     * {@code endExclusive} then an empty stream is returned.
      * <p>
      * An equivalent sequence of increasing values can be produced
      * sequentially using a {@code for} loop as follows:
      * <pre>{@code
-     *     for (long i = start; i < end ; i += step) { ... }
+     *     for (long i = startInclusive; i < endExclusive ; i += step) { ... }
      * }</pre>
      *
-     * @param start the (inclusive) initial value
-     * @param end the exclusive upper bound
+     * @param startInclusive the (inclusive) initial value
+     * @param endExclusive the exclusive upper bound
      * @param step the difference between consecutive 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
+     *         if {@code startInclusive} is greater than {@code endExclusive} and {@code step} is
+     *         greater than 0, or if {@code startInclusive} is less than {@code endExclusive} and
      *         {@code step} is less than 0, or if {@code step} is equal to 0.
      */
-    public static LongStream range(long start, final long end, final long step) {
+    public static LongStream range(long startInclusive, final long endExclusive, final long step) {
         if (step > 0) {
             // Decreasing range with an increasing step value
-            if (start > end) throw new IllegalArgumentException(
-                    String.format("Illegal range: start(%d) > end(%d), step(%d) > 0", start, end, step));
+            if (startInclusive > endExclusive) throw new IllegalArgumentException(
+                    String.format("Illegal range: startInclusive(%d) > endExclusive(%d), step(%d) > 0", startInclusive, endExclusive, step));
         }
         else if (step < 0) {
             // Increasing range with a decreasing step value
-            if (start < end) throw new IllegalArgumentException(
-                    String.format("Illegal range: start(%d) < end(%d), step(%d) < 0", start, end, step));
+            if (startInclusive < endExclusive) throw new IllegalArgumentException(
+                    String.format("Illegal range: startInclusive(%d) < endExclusive(%d), step(%d) < 0", startInclusive, endExclusive, step));
         }
         else if (step == 0) {
             throw new IllegalArgumentException("Illegal range: step(0)");
         }
-        return StreamSupport.longStream(new Streams.RangeLongSpliterator(start, end, step));
+        return StreamSupport.longStream(new Streams.RangeLongSpliterator(startInclusive, endExclusive, step));
     }
 }
--- a/src/share/classes/java/util/stream/Stream.java	Sun Apr 21 10:30:42 2013 -0700
+++ b/src/share/classes/java/util/stream/Stream.java	Sun Apr 21 16:01:35 2013 -0400
@@ -814,11 +814,23 @@
      * @param <T> The type of stream elements
      * @return A singleton sequential stream
      */
-    public static<T> Stream<T> singleton(T t) {
+    public static<T> Stream<T> of(T t) {
         return StreamSupport.stream(new Streams.StreamBuilderImpl<>(t));
     }
 
     /**
+     * Returns a sequential stream whose elements are the specified values.
+     *
+     * @param values the elements of the new stream
+     * @param <T> The type of stream elements
+     * @return the new stream
+     */
+    @SafeVarargs
+    public static<T> Stream<T> of(T... values) {
+        return Arrays.stream(values);
+    }
+
+    /**
      * Returns an infinite sequential {@code Stream} produced by iterative
      * application of a function {@code f} to an initial element {@code seed},
      * producing a {@code Stream} consisting of {@code seed}, {@code f(seed)},
@@ -857,13 +869,13 @@
     }
 
     /**
-     * Returns an infinite sequential {@code Stream} where each element is
+     * Returns a sequential {@code Stream} where each element is
      * generated by a {@code Supplier}.  This is suitable for generating
      * constant streams, streams of random elements, etc.
      *
      * @param s the {@code Supplier} of generated elements
      * @param <T> The type of stream elements
-     * @return A new infinite sequential {@code Stream}
+     * @return A new sequential {@code Stream}
      */
     public static<T> Stream<T> generate(Supplier<T> s) {
         Objects.requireNonNull(s);
@@ -877,16 +889,4 @@
                 },
                 Spliterator.ORDERED | Spliterator.IMMUTABLE));
     }
-
-    /**
-     * Returns a sequential stream whose elements are the specified values.
-     *
-     * @param values the elements of the new stream
-     * @param <T> The type of stream elements
-     * @return the new stream
-     */
-    @SafeVarargs
-    public static<T> Stream<T> of(T... values) {
-        return Arrays.stream(values);
-    }
 }
--- a/test-ng/tests/org/openjdk/tests/java/util/stream/StreamBuilderTest.java	Sun Apr 21 10:30:42 2013 -0700
+++ b/test-ng/tests/org/openjdk/tests/java/util/stream/StreamBuilderTest.java	Sun Apr 21 16:01:35 2013 -0400
@@ -75,7 +75,7 @@
     @Test
     public void testSingleton() {
         TestData.OfRef<Integer> data = TestData.Factory.ofSupplier("[0, 1)",
-                                                                   () -> Stream.singleton(1));
+                                                                   () -> Stream.of(1));
 
         withData(data).
                 stream(s -> s).
@@ -137,7 +137,7 @@
     @Test
     public void testIntSingleton() {
         TestData.OfInt data = TestData.Factory.ofIntSupplier("[0, 1)",
-                                                             () -> IntStream.singleton(1));
+                                                             () -> IntStream.of(1));
 
         withData(data).
                 stream(s -> s).
@@ -199,7 +199,7 @@
     @Test
     public void testLongSingleton() {
         TestData.OfLong data = TestData.Factory.ofLongSupplier("[0, 1)",
-                                                               () -> LongStream.singleton(1));
+                                                               () -> LongStream.of(1));
 
         withData(data).
                 stream(s -> s).
@@ -260,7 +260,7 @@
 
     @Test
     public void testDoubleSingleton() {
-        TestData.OfDouble data = TestData.Factory.ofDoubleSupplier("[0, 1)", () -> DoubleStream.singleton(1));
+        TestData.OfDouble data = TestData.Factory.ofDoubleSupplier("[0, 1)", () -> DoubleStream.of(1));
 
         withData(data).
                 stream(s -> s).