1 /*

     2  * Copyright (c) 2013, 2019, Oracle and/or its affiliates. All rights reserved.

     3  * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

     4  *

     5  *

     6  *

     7  *

     8  *

     9  *

    10  *

    11  *

    12  *

    13  *

    14  *

    15  *

    16  *

    17  *

    18  *

    19  *

    20  *

    21  *

    22  *

    23  *

    24  */

    25 

    26 // package java.util;

    27 

    28 import java.util.Spliterator;

    29 import java.util.function.Consumer;

    30 import java.util.function.IntConsumer;

    31 import java.util.function.LongConsumer;

    32 import java.util.function.DoubleConsumer;

    33 import java.util.stream.StreamSupport;

    34 import java.util.stream.IntStream;

    35 import java.util.stream.LongStream;

    36 import java.util.stream.DoubleStream;

    37 

    38 /**

    39  * This class overrides the stream-producing methods (such as {@code ints()})

    40  * in class {@code AbstractRng} to provide {@code Spliterator}-based

    41  * implmentations that support potentially parallel execution.

    42  *

    43  * To implement a pseudorandom number generator, the programmer needs

    44  * only to extend this class and provide implementations for the methods

    45  * {@code nextInt()}, {@code nextLong()}, {@code makeIntsSpliterator},

    46  * {@code makeLongsSpliterator}, and {@code makeDoublesSpliterator}.

    47  *

    48  * This class is not public; it provides shared code to the public

    49  * classes {@code AbstractSplittableRng}, {@code AbstractSharedRng},

    50  * and {@code AbstractArbitrarilyJumpableRng}.

    51  *

    52  * @author  Guy Steele

    53  * @author  Doug Lea

    54  * @since   1.9

    55  */

    56 

    57 abstract class AbstractSpliteratorRng implements Rng {

    58     /*

    59      * Implementation Overview.

    60      *

    61      * This class provides most of the "user API" methods needed to

    62      * satisfy the interface java.util.Rng.  An implementation of this

    63      * interface need only extend this class and provide implementations

    64      * of six methods: nextInt, nextLong, and nextDouble (the versions

    65      * that take no arguments) and makeIntsSpliterator,

    66      * makeLongsSpliterator, and makeDoublesSpliterator.

    67      *

    68      * File organization: First the non-public abstract methods needed

    69      * to create spliterators, then the main public methods.

    70      */

    71 

    72     abstract Spliterator.OfInt makeIntsSpliterator(long index, long fence, int origin, int bound);

    73     abstract Spliterator.OfLong makeLongsSpliterator(long index, long fence, long origin, long bound);

    74     abstract Spliterator.OfDouble makeDoublesSpliterator(long index, long fence, double origin, double bound);

    75 	

    76     /* ---------------- public methods ---------------- */

    77 

    78     // stream methods, coded in a way intended to better isolate for

    79     // maintenance purposes the small differences across forms.

    80 

    81     /**

    82      * Returns a stream producing the given {@code streamSize} number

    83      * of pseudorandom {@code int} values from this generator and/or

    84      * one split from it.

    85      *

    86      * @param streamSize the number of values to generate

    87      * @return a stream of pseudorandom {@code int} values

    88      * @throws IllegalArgumentException if {@code streamSize} is

    89      *         less than zero

    90      */

    91     public IntStream ints(long streamSize) {

    92 	RngSupport.checkStreamSize(streamSize);

    93         return StreamSupport.intStream

    94             (makeIntsSpliterator(0L, streamSize, Integer.MAX_VALUE, 0),

    95              false);

    96     }

    97 

    98     /**

    99      * Returns an effectively unlimited stream of pseudorandomly chosen

   100      * {@code int} values.

   101      *

   102      * @implNote The implementation of this method is effectively

   103      * equivalent to {@code ints(Long.MAX_VALUE)}.

   104      *

   105      * @return a stream of pseudorandomly chosen {@code int} values

   106      */

   107     

   108     public IntStream ints() {

   109         return StreamSupport.intStream

   110             (makeIntsSpliterator(0L, Long.MAX_VALUE, Integer.MAX_VALUE, 0),

   111              false);

   112     }

   113 

   114     /**

   115      * Returns a stream producing the given {@code streamSize} number

   116      * of pseudorandom {@code int} values from this generator and/or one split

   117      * from it; each value conforms to the given origin (inclusive) and bound

   118      * (exclusive).

   119      *

   120      * @param streamSize the number of values to generate

   121      * @param randomNumberOrigin the origin (inclusive) of each random value

   122      * @param randomNumberBound the bound (exclusive) of each random value

   123      * @return a stream of pseudorandom {@code int} values,

   124      *         each with the given origin (inclusive) and bound (exclusive)

   125      * @throws IllegalArgumentException if {@code streamSize} is

   126      *         less than zero, or {@code randomNumberOrigin}

   127      *         is greater than or equal to {@code randomNumberBound}

   128      */

   129     public IntStream ints(long streamSize, int randomNumberOrigin,

   130 			   int randomNumberBound) {

   131 	RngSupport.checkStreamSize(streamSize);

   132 	RngSupport.checkRange(randomNumberOrigin, randomNumberBound);

   133         return StreamSupport.intStream

   134             (makeIntsSpliterator(0L, streamSize, randomNumberOrigin, randomNumberBound),

   135              false);

   136     }

   137 

   138     /**

   139      * Returns an effectively unlimited stream of pseudorandom {@code

   140      * int} values from this generator and/or one split from it; each value

   141      * conforms to the given origin (inclusive) and bound (exclusive).

   142      *

   143      * @implNote This method is implemented to be equivalent to {@code

   144      * ints(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.

   145      *

   146      * @param randomNumberOrigin the origin (inclusive) of each random value

   147      * @param randomNumberBound the bound (exclusive) of each random value

   148      * @return a stream of pseudorandom {@code int} values,

   149      *         each with the given origin (inclusive) and bound (exclusive)

   150      * @throws IllegalArgumentException if {@code randomNumberOrigin}

   151      *         is greater than or equal to {@code randomNumberBound}

   152      */

   153     public IntStream ints(int randomNumberOrigin, int randomNumberBound) {

   154 	RngSupport.checkRange(randomNumberOrigin, randomNumberBound);

   155         return StreamSupport.intStream

   156             (makeIntsSpliterator(0L, Long.MAX_VALUE, randomNumberOrigin, randomNumberBound),

   157              false);

   158     }

   159 

   160     /**

   161      * Returns a stream producing the given {@code streamSize} number

   162      * of pseudorandom {@code long} values from this generator and/or

   163      * one split from it.

   164      *

   165      * @param streamSize the number of values to generate

   166      * @return a stream of pseudorandom {@code long} values

   167      * @throws IllegalArgumentException if {@code streamSize} is

   168      *         less than zero

   169      */

   170     public LongStream longs(long streamSize) {

   171 	RngSupport.checkStreamSize(streamSize);

   172         return StreamSupport.longStream

   173             (makeLongsSpliterator(0L, streamSize, Long.MAX_VALUE, 0L),

   174              false);

   175     }

   176 

   177     /**

   178      * Returns an effectively unlimited stream of pseudorandom {@code

   179      * long} values from this generator and/or one split from it.

   180      *

   181      * @implNote This method is implemented to be equivalent to {@code

   182      * longs(Long.MAX_VALUE)}.

   183      *

   184      * @return a stream of pseudorandom {@code long} values

   185      */

   186     public LongStream longs() {

   187         return StreamSupport.longStream

   188             (makeLongsSpliterator(0L, Long.MAX_VALUE, Long.MAX_VALUE, 0L),

   189              false);

   190     }

   191 

   192     /**

   193      * Returns a stream producing the given {@code streamSize} number of

   194      * pseudorandom {@code long} values from this generator and/or one split

   195      * from it; each value conforms to the given origin (inclusive) and bound

   196      * (exclusive).

   197      *

   198      * @param streamSize the number of values to generate

   199      * @param randomNumberOrigin the origin (inclusive) of each random value

   200      * @param randomNumberBound the bound (exclusive) of each random value

   201      * @return a stream of pseudorandom {@code long} values,

   202      *         each with the given origin (inclusive) and bound (exclusive)

   203      * @throws IllegalArgumentException if {@code streamSize} is

   204      *         less than zero, or {@code randomNumberOrigin}

   205      *         is greater than or equal to {@code randomNumberBound}

   206      */

   207     public LongStream longs(long streamSize, long randomNumberOrigin,

   208 			     long randomNumberBound) {

   209 	RngSupport.checkStreamSize(streamSize);

   210 	RngSupport.checkRange(randomNumberOrigin, randomNumberBound);

   211         return StreamSupport.longStream

   212             (makeLongsSpliterator(0L, streamSize, randomNumberOrigin, randomNumberBound),

   213              false);

   214     }

   215 

   216     /**

   217      * Returns an effectively unlimited stream of pseudorandom {@code

   218      * long} values from this generator and/or one split from it; each value

   219      * conforms to the given origin (inclusive) and bound (exclusive).

   220      *

   221      * @implNote This method is implemented to be equivalent to {@code

   222      * longs(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.

   223      *

   224      * @param randomNumberOrigin the origin (inclusive) of each random value

   225      * @param randomNumberBound the bound (exclusive) of each random value

   226      * @return a stream of pseudorandom {@code long} values,

   227      *         each with the given origin (inclusive) and bound (exclusive)

   228      * @throws IllegalArgumentException if {@code randomNumberOrigin}

   229      *         is greater than or equal to {@code randomNumberBound}

   230      */

   231     public LongStream longs(long randomNumberOrigin, long randomNumberBound) {

   232 	RngSupport.checkRange(randomNumberOrigin, randomNumberBound);

   233         return StreamSupport.longStream

   234             (makeLongsSpliterator(0L, Long.MAX_VALUE, randomNumberOrigin, randomNumberBound),

   235              false);

   236     }

   237 

   238     /**

   239      * Returns a stream producing the given {@code streamSize} number of

   240      * pseudorandom {@code double} values from this generator and/or one split

   241      * from it; each value is between zero (inclusive) and one (exclusive).

   242      *

   243      * @param streamSize the number of values to generate

   244      * @return a stream of {@code double} values

   245      * @throws IllegalArgumentException if {@code streamSize} is

   246      *         less than zero

   247      */

   248     public DoubleStream doubles(long streamSize) {

   249 	RngSupport.checkStreamSize(streamSize);

   250         return StreamSupport.doubleStream

   251             (makeDoublesSpliterator(0L, streamSize, Double.MAX_VALUE, 0.0),

   252              false);

   253     }

   254 

   255     /**

   256      * Returns an effectively unlimited stream of pseudorandom {@code

   257      * double} values from this generator and/or one split from it; each value

   258      * is between zero (inclusive) and one (exclusive).

   259      *

   260      * @implNote This method is implemented to be equivalent to {@code

   261      * doubles(Long.MAX_VALUE)}.

   262      *

   263      * @return a stream of pseudorandom {@code double} values

   264      */

   265     public DoubleStream doubles() {

   266         return StreamSupport.doubleStream

   267             (makeDoublesSpliterator(0L, Long.MAX_VALUE, Double.MAX_VALUE, 0.0),

   268              false);

   269     }

   270 

   271     /**

   272      * Returns a stream producing the given {@code streamSize} number of

   273      * pseudorandom {@code double} values from this generator and/or one split

   274      * from it; each value conforms to the given origin (inclusive) and bound

   275      * (exclusive).

   276      *

   277      * @param streamSize the number of values to generate

   278      * @param randomNumberOrigin the origin (inclusive) of each random value

   279      * @param randomNumberBound the bound (exclusive) of each random value

   280      * @return a stream of pseudorandom {@code double} values,

   281      *         each with the given origin (inclusive) and bound (exclusive)

   282      * @throws IllegalArgumentException if {@code streamSize} is

   283      *         less than zero

   284      * @throws IllegalArgumentException if {@code randomNumberOrigin}

   285      *         is greater than or equal to {@code randomNumberBound}

   286      */

   287     public DoubleStream doubles(long streamSize, double randomNumberOrigin,

   288 				 double randomNumberBound) {

   289 	RngSupport.checkStreamSize(streamSize);

   290 	RngSupport.checkRange(randomNumberOrigin, randomNumberBound);

   291         return StreamSupport.doubleStream

   292             (makeDoublesSpliterator(0L, streamSize, randomNumberOrigin, randomNumberBound),

   293              false);

   294     }

   295 

   296     /**

   297      * Returns an effectively unlimited stream of pseudorandom {@code

   298      * double} values from this generator and/or one split from it; each value

   299      * conforms to the given origin (inclusive) and bound (exclusive).

   300      *

   301      * @implNote This method is implemented to be equivalent to {@code

   302      * doubles(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.

   303      *

   304      * @param randomNumberOrigin the origin (inclusive) of each random value

   305      * @param randomNumberBound the bound (exclusive) of each random value

   306      * @return a stream of pseudorandom {@code double} values,

   307      *         each with the given origin (inclusive) and bound (exclusive)

   308      * @throws IllegalArgumentException if {@code randomNumberOrigin}

   309      *         is greater than or equal to {@code randomNumberBound}

   310      */

   311     public DoubleStream doubles(double randomNumberOrigin, double randomNumberBound) {

   312 	RngSupport.checkRange(randomNumberOrigin, randomNumberBound);

   313         return StreamSupport.doubleStream

   314             (makeDoublesSpliterator(0L, Long.MAX_VALUE, randomNumberOrigin, randomNumberBound),

   315              false);

   316     }

   317 

   318 }