1 /*

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

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package java.util.random;

    27 

    28 import java.math.BigInteger;

    29 import java.util.stream.DoubleStream;

    30 import java.util.stream.IntStream;

    31 import java.util.stream.LongStream;

    32 

    33 /**

    34  * The {@link RandomNumberGenerator} interface is designed to provide a common protocol for objects

    35  * that generate random or (more typically) pseudorandom sequences of numbers (or Boolean values).

    36  * Such a sequence may be obtained by either repeatedly invoking a method that returns a single

    37  * (pseudo)randomly chosen value, or by invoking a method that returns a stream of (pseudo)randomly

    38  * chosen values.

    39  * <p>

    40  * Ideally, given an implicitly or explicitly specified range of values, each value would be chosen

    41  * independently and uniformly from that range. In practice, one may have to settle for some

    42  * approximation to independence and uniformity.

    43  * <p>

    44  * In the case of {@code int}, {@code long}, and {@link Boolean} values, if there is no explicit

    45  * specification of range, then the range includes all possible values of the type.  In the case of

    46  * {@code float} and {@code double} values, a value is always chosen from the set of

    47  * 2<sup><i>w</i></sup> values between 0.0 (inclusive) and 1.0 (exclusive), where <i>w</i> is 23 for

    48  * {@code float} values and 52 for {@code double} values, such that adjacent values differ by

    49  * 2<sup>&minus;<i>w</i></sup>; if an explicit range is specified, then the chosen number is

    50  * computationally scaled and translated so as to appear to have been chosen from that range.

    51  * <p>

    52  * Each method that returns a stream produces a stream of values each of which is chosen in the same

    53  * manner as for a method that returns a single (pseudo)randomly chosen value.  For example, if

    54  * {@code r} implements {@link RandomNumberGenerator}, then the method call {@code r.ints(100)}

    55  * returns a stream of 100 {@code int} values.  These are not necessarily the exact same values that

    56  * would have been returned if instead {@code r.nextInt()} had been called 100 times; all that is

    57  * guaranteed is that each value in the stream is chosen in a similar (pseudo)random manner from the

    58  * same range.

    59  * <p>

    60  * Every object that implements the {@link RandomNumberGenerator} interface is assumed to contain a

    61  * finite amount of state.  Using such an object to generate a pseudorandomly chosen value alters

    62  * its state.  The number of distinct possible states of such an object is called its

    63  * <i>period</i>.  (Some implementations of the {@link RandomNumberGenerator} interface

    64  * may be truly random rather than pseudorandom, for example relying on the statistical behavior of

    65  * a physical object to derive chosen values.  Such implementations do not have a fixed period.)

    66  * <p>

    67  * As a rule, objects that implement the {@link RandomNumberGenerator} interface need not be

    68  * thread-safe.  It is recommended that multithreaded applications use either {@link

    69  * ThreadLocalRandom} or (preferably) pseudorandom number generators that implement the {@link

    70  * SplittableRNG} or {@link JumpableRNG} interface.

    71  * <p>

    72  * To implement this interface, a class only needs to provide concrete definitions for the methods

    73  * {@code nextLong()} and {@code period()}. Default implementations are provided for all other

    74  * methods (but it may be desirable to override some of them, especially {@code nextInt()} if the

    75  * underlying algorithm is {@code int}-based). Moerover, it may be preferable instead to implement

    76  * another interface such as {@link JumpableRNG} or {@link LeapableRNG}, or to extend an abstract

    77  * class such as {@link AbstractSplittableRNG} or {@link AbstractArbitrarilyJumpableRNG}.

    78  * <p>

    79  * Objects that implement {@link RandomNumberGenerator} are typically not cryptographically secure.

    80  * Consider instead using {@link java.security.SecureRandom} to get a cryptographically secure

    81  * pseudorandom number generator for use by security-sensitive applications.  Note, however, that

    82  * {@code java.security.SecureRandom} does implement the {@link RandomNumberGenerator} interface, so

    83  * that instances of {@code java.security.SecureRandom} may be used interchangeably with other types

    84  * of pseudorandom generators in applications that do not require a secure generator.

    85  *

    86  * @since 14

    87  */

    88 public interface RandomNumberGenerator {

    89 

    90     /**

    91      * Returns an effectively unlimited stream of pseudorandomly chosen

    92      * {@code double} values.

    93      *

    94      * @return a stream of pseudorandomly chosen {@code double} values

    95      *

    96      * @implNote It is permitted to implement this method in a manner

    97      * equivalent to {@code doubles(Long.MAX_VALUE)}.

    98      *

    99      * @implNote The default implementation produces a sequential stream

   100      * that repeatedly calls {@code nextDouble()}.

   101      */

   102     default DoubleStream doubles() {

   103         return DoubleStream.generate(this::nextDouble).sequential();

   104     }

   105 

   106     /**

   107      * Returns an effectively unlimited stream of pseudorandomly chosen

   108      * {@code double} values, where each value is between the specified

   109      * origin (inclusive) and the specified bound (exclusive).

   110      *

   111      * @param randomNumberOrigin the least value that can be produced

   112      * @param randomNumberBound the upper bound (exclusive) for each value produced

   113      *

   114      * @return a stream of pseudorandomly chosen {@code double} values, each between

   115      *         the specified origin (inclusive) and the specified bound (exclusive)

   116      *

   117      * @throws IllegalArgumentException if {@code randomNumberOrigin}

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

   119      *

   120      * @implNote It is permitted to implement this method in a manner

   121      *           equivalent to

   122      *           {@code doubles(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.

   123      * @implNote The default implementation produces a sequential stream that repeatedly

   124      *           calls {@code nextDouble(randomNumberOrigin, randomNumberBound)}.

   125      */

   126     default DoubleStream doubles(double randomNumberOrigin, double randomNumberBound) {

   127         RNGSupport.checkRange(randomNumberOrigin, randomNumberBound);

   128         return DoubleStream.generate(() -> nextDouble(randomNumberOrigin, randomNumberBound)).sequential();

   129     }

   130 

   131     /**

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

   133      * pseudorandomly chosen {@code double} values.

   134      *

   135      * @param streamSize the number of values to generate

   136      *

   137      * @return a stream of pseudorandomly chosen {@code double} values

   138      *

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

   140      *         less than zero

   141      *

   142      * @implNote The default implementation produces a sequential stream

   143      * that repeatedly calls {@code nextDouble()}.

   144      */

   145     default DoubleStream doubles(long streamSize) {

   146         RNGSupport.checkStreamSize(streamSize);

   147         return doubles().limit(streamSize);

   148     }

   149 

   150     /**

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

   152      * pseudorandomly chosen {@code double} values, where each value is between

   153      * the specified origin (inclusive) and the specified bound (exclusive).

   154      *

   155      * @param streamSize the number of values to generate

   156      * @param randomNumberOrigin the least value that can be produced

   157      * @param randomNumberBound the upper bound (exclusive) for each value produced

   158      *

   159      * @return a stream of pseudorandomly chosen {@code double} values, each between

   160      *         the specified origin (inclusive) and the specified bound (exclusive)

   161      *

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

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

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

   165      *

   166      * @implNote The default implementation produces a sequential stream

   167      * that repeatedly calls {@code nextDouble(randomNumberOrigin, randomNumberBound)}.

   168      */

   169     default DoubleStream doubles(long streamSize, double randomNumberOrigin,

   170                           double randomNumberBound) {

   171         RNGSupport.checkStreamSize(streamSize);

   172         RNGSupport.checkRange(randomNumberOrigin, randomNumberBound);

   173         return doubles(randomNumberOrigin, randomNumberBound).limit(streamSize);

   174     }

   175 

   176     /**

   177      * Returns an effectively unlimited stream of pseudorandomly chosen

   178      * {@code int} values.

   179      *

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

   181      *

   182      * @implNote It is permitted to implement this method in a manner

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

   184      * @implNote The default implementation produces a sequential stream

   185      * that repeatedly calls {@code nextInt()}.

   186      */

   187     default IntStream ints() {

   188         return IntStream.generate(this::nextInt).sequential();

   189     }

   190 

   191     /**

   192      * Returns an effectively unlimited stream of pseudorandomly chosen

   193      * {@code int} values, where each value is between the specified

   194      * origin (inclusive) and the specified bound (exclusive).

   195      *

   196      * @param randomNumberOrigin the least value that can be produced

   197      * @param randomNumberBound the upper bound (exclusive) for each value produced

   198      *

   199      * @return a stream of pseudorandomly chosen {@code int} values, each between

   200      *         the specified origin (inclusive) and the specified bound (exclusive)

   201      *

   202      * @throws IllegalArgumentException if {@code randomNumberOrigin}

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

   204      *

   205      * @implNote It is permitted to implement this method in a manner equivalent to

   206      *           {@code ints(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.

   207      * @implNote The default implementation produces a sequential stream that repeatedly

   208      *           calls {@code nextInt(randomNumberOrigin, randomNumberBound)}.

   209      */

   210     default IntStream ints(int randomNumberOrigin, int randomNumberBound) {

   211         RNGSupport.checkRange(randomNumberOrigin, randomNumberBound);

   212         return IntStream.generate(() -> nextInt(randomNumberOrigin, randomNumberBound)).sequential();

   213     }

   214 

   215     /**

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

   217      * pseudorandomly chosen {@code int} values.

   218      *

   219      * @param streamSize the number of values to generate

   220      *

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

   222      *

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

   224      *         less than zero

   225      *

   226      * @implNote The default implementation produces a sequential stream

   227      *           that repeatedly calls {@code nextInt()}.

   228      */

   229     default IntStream ints(long streamSize) {

   230         RNGSupport.checkStreamSize(streamSize);

   231         return ints().limit(streamSize);

   232     }

   233 

   234     /**

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

   236      * pseudorandomly chosen {@code int} values, where each value is between

   237      * the specified origin (inclusive) and the specified bound (exclusive).

   238      *

   239      * @param streamSize the number of values to generate

   240      * @param randomNumberOrigin the least value that can be produced

   241      * @param randomNumberBound the upper bound (exclusive) for each value produced

   242      *

   243      * @return a stream of pseudorandomly chosen {@code int} values, each between

   244      *         the specified origin (inclusive) and the specified bound (exclusive)

   245      *

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

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

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

   249      *

   250      * @implNote The default implementation produces a sequential stream that repeatedly

   251      *           calls {@code nextInt(randomNumberOrigin, randomNumberBound)}.

   252      */

   253     default IntStream ints(long streamSize, int randomNumberOrigin,

   254                           int randomNumberBound) {

   255         RNGSupport.checkStreamSize(streamSize);

   256         RNGSupport.checkRange(randomNumberOrigin, randomNumberBound);

   257         return ints(randomNumberOrigin, randomNumberBound).limit(streamSize);

   258     }

   259 

   260     /**

   261      * Returns an effectively unlimited stream of pseudorandomly chosen

   262      * {@code long} values.

   263      *

   264      * @return a stream of pseudorandomly chosen {@code long} values

   265      *

   266      * @implNote It is permitted to implement this method in a manner

   267      *           equivalent to {@code longs(Long.MAX_VALUE)}.

   268      * @implNote The default implementation produces a sequential stream

   269      *           that repeatedly calls {@code nextLong()}.

   270      */

   271     default LongStream longs() {

   272         return LongStream.generate(this::nextLong).sequential();

   273     }

   274 

   275     /**

   276      * Returns an effectively unlimited stream of pseudorandomly chosen

   277      * {@code long} values, where each value is between the specified

   278      * origin (inclusive) and the specified bound (exclusive).

   279      *

   280      * @param randomNumberOrigin the least value that can be produced

   281      * @param randomNumberBound the upper bound (exclusive) for each value produced

   282      *

   283      * @return a stream of pseudorandomly chosen {@code long} values, each between

   284      *         the specified origin (inclusive) and the specified bound (exclusive)

   285      *

   286      * @throws IllegalArgumentException if {@code randomNumberOrigin}

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

   288      *

   289      * @implNote It is permitted to implement this method in a manner

   290      *           equivalent to {@code longs(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.

   291      * @implNote The default implementation produces a sequential stream that repeatedly

   292      *           calls {@code nextLong(randomNumberOrigin, randomNumberBound)}.

   293      */

   294     default LongStream longs(long randomNumberOrigin, long randomNumberBound) {

   295         RNGSupport.checkRange(randomNumberOrigin, randomNumberBound);

   296         return LongStream.generate(() -> nextLong(randomNumberOrigin, randomNumberBound)).sequential();

   297     }

   298 

   299     /**

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

   301      * pseudorandomly chosen {@code long} values.

   302      *

   303      * @param streamSize the number of values to generate

   304      *

   305      * @return a stream of pseudorandomly chosen {@code long} values

   306      *

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

   308      *         less than zero

   309      *

   310      * @implNote The default implementation produces a sequential stream

   311      * that repeatedly calls {@code nextLong()}.

   312      */

   313     default LongStream longs(long streamSize) {

   314         RNGSupport.checkStreamSize(streamSize);

   315         return longs().limit(streamSize);

   316     }

   317 

   318     /**

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

   320      * pseudorandomly chosen {@code long} values, where each value is between

   321      * the specified origin (inclusive) and the specified bound (exclusive).

   322      *

   323      * @param streamSize the number of values to generate

   324      * @param randomNumberOrigin the least value that can be produced

   325      * @param randomNumberBound the upper bound (exclusive) for each value produced

   326      *

   327      * @return a stream of pseudorandomly chosen {@code long} values, each between

   328      *         the specified origin (inclusive) and the specified bound (exclusive)

   329      *

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

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

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

   333      *

   334      * @implNote The default implementation produces a sequential stream that repeatedly

   335      *            calls {@code nextLong(randomNumberOrigin, randomNumberBound)}.

   336      */

   337     default LongStream longs(long streamSize, long randomNumberOrigin,

   338                           long randomNumberBound) {

   339         RNGSupport.checkStreamSize(streamSize);

   340         RNGSupport.checkRange(randomNumberOrigin, randomNumberBound);

   341         return longs(randomNumberOrigin, randomNumberBound).limit(streamSize);

   342     }

   343 

   344     /**

   345      * Returns a pseudorandomly chosen {@code boolean} value.

   346      * <p>

   347      * The default implementation tests the high-order bit (sign bit) of a value produced by {@code

   348      * nextInt()}, on the grounds that some algorithms for pseudorandom number generation produce

   349      * values whose high-order bits have better statistical quality than the low-order bits.

   350      *

   351      * @return a pseudorandomly chosen {@code boolean} value

   352      */

   353     default boolean nextBoolean() {

   354         return nextInt() < 0;

   355     }

   356 

   357     /**

   358      * Returns a pseudorandom {@code float} value between zero (inclusive) and one (exclusive).

   359      * <p>

   360      * The default implementation uses the 24 high-order bits from a call to {@code nextInt()}.

   361      *

   362      * @return a pseudorandom {@code float} value between zero (inclusive) and one (exclusive)

   363      */

   364     default float nextFloat() {

   365         return (nextInt() >>> 8) * 0x1.0p-24f;

   366     }

   367 

   368     /**

   369      * Returns a pseudorandomly chosen {@code float} value between zero

   370      * (inclusive) and the specified bound (exclusive).

   371      *

   372      * @param bound the upper bound (exclusive) for the returned value.

   373      *        Must be positive and finite

   374      *

   375      * @return a pseudorandomly chosen {@code float} value between

   376      *         zero (inclusive) and the bound (exclusive)

   377      *

   378      * @throws IllegalArgumentException if {@code bound} is not

   379      *         positive and finite

   380      *

   381      * @implNote The default implementation simply calls

   382      *     {@code RNGSupport.checkBound(bound)} and then

   383      *     {@code RNGSupport.boundedNextFloat(this, bound)}.

   384      */

   385     default float nextFloat(float bound) {

   386         RNGSupport.checkBound(bound);

   387         return RNGSupport.boundedNextFloat(this, bound);

   388     }

   389 

   390     /**

   391      * Returns a pseudorandomly chosen {@code float} value between the

   392      * specified origin (inclusive) and the specified bound (exclusive).

   393      *

   394      * @param origin the least value that can be returned

   395      * @param bound the upper bound (exclusive)

   396      *

   397      * @return a pseudorandomly chosen {@code float} value between the

   398      *         origin (inclusive) and the bound (exclusive)

   399      *

   400      * @throws IllegalArgumentException unless {@code origin} is finite,

   401      *         {@code bound} is finite, and {@code origin} is less than

   402      *         {@code bound}

   403      *

   404      * @implNote The default implementation simply calls

   405      *           {@code RNGSupport.checkRange(origin, bound)} and then

   406      *          {@code RNGSupport.boundedNextFloat(this, origin, bound)}.

   407      */

   408     default float nextFloat(float origin, float bound) {

   409         RNGSupport.checkRange(origin, bound);

   410         return RNGSupport.boundedNextFloat(this, origin, bound);

   411     }

   412 

   413     /**

   414      * Returns a pseudorandom {@code double} value between zero (inclusive) and one (exclusive).

   415      * <p>

   416      * The default implementation uses the 53 high-order bits from a call to {@code nextLong()}.

   417      *

   418      * @return a pseudorandom {@code double} value between zero (inclusive) and one (exclusive)

   419      */

   420     default double nextDouble() {

   421         return (nextLong() >>> 11) * 0x1.0p-53;

   422     }

   423 

   424     /**

   425      * Returns a pseudorandomly chosen {@code double} value between zero

   426      * (inclusive) and the specified bound (exclusive).

   427      *

   428      * @param bound the upper bound (exclusive) for the returned value.

   429      *        Must be positive and finite

   430      *

   431      * @return a pseudorandomly chosen {@code double} value between

   432      *         zero (inclusive) and the bound (exclusive)

   433      *

   434      * @throws IllegalArgumentException if {@code bound} is not

   435      *         positive and finite

   436      *

   437      * @implNote The default implementation simply calls

   438      *           {@code RNGSupport.checkBound(bound)} and then

   439      *           {@code RNGSupport.boundedNextDouble(this, bound)}.

   440      */

   441     default double nextDouble(double bound) {

   442         RNGSupport.checkBound(bound);

   443         return RNGSupport.boundedNextDouble(this, bound);

   444     }

   445 

   446     /**

   447      * Returns a pseudorandomly chosen {@code double} value between the

   448      * specified origin (inclusive) and the specified bound (exclusive).

   449      *

   450      * @param origin the least value that can be returned

   451      * @param bound the upper bound (exclusive) for the returned value

   452      *

   453      * @return a pseudorandomly chosen {@code double} value between the

   454      *         origin (inclusive) and the bound (exclusive)

   455      *

   456      * @throws IllegalArgumentException unless {@code origin} is finite,

   457      *         {@code bound} is finite, and {@code origin} is less than

   458      *         {@code bound}

   459      *

   460      * @implNote The default implementation simply calls

   461      *           {@code RNGSupport.checkRange(origin, bound)} and then

   462      *           {@code RNGSupport.boundedNextDouble(this, origin, bound)}.

   463      */

   464     default double nextDouble(double origin, double bound) {

   465         RNGSupport.checkRange(origin, bound);

   466         return RNGSupport.boundedNextDouble(this, origin, bound);

   467     }

   468 

   469     /**

   470      * Returns a pseudorandomly chosen {@code int} value.

   471      * <p>

   472      * The default implementation uses the 32 high-order bits from a call to {@code nextLong()}.

   473      *

   474      * @return a pseudorandomly chosen {@code int} value

   475      */

   476     default public int nextInt() {

   477         return (int)(nextLong() >>> 32);

   478     }

   479 

   480     /**

   481      * Returns a pseudorandomly chosen {@code int} value between

   482      * zero (inclusive) and the specified bound (exclusive).

   483      *

   484      * @param bound the upper bound (exclusive) for the returned value. Must be positive.

   485      *

   486      * @return a pseudorandomly chosen {@code int} value between

   487      *         zero (inclusive) and the bound (exclusive)

   488      *

   489      * @throws IllegalArgumentException if {@code bound} is not positive

   490      *

   491      * @implNote The default implementation simply calls

   492      *           {@code RNGSupport.checkBound(bound)} and then

   493      *           {@code RNGSupport.boundedNextInt(this, bound)}.

   494      */

   495     default int nextInt(int bound) {

   496         RNGSupport.checkBound(bound);

   497         return RNGSupport.boundedNextInt(this, bound);

   498     }

   499 

   500     /**

   501      * Returns a pseudorandomly chosen {@code int} value between the

   502      * specified origin (inclusive) and the specified bound (exclusive).

   503      *

   504      * @param origin the least value that can be returned

   505      * @param bound the upper bound (exclusive) for the returned value

   506      *

   507      * @return a pseudorandomly chosen {@code int} value between the

   508      *         origin (inclusive) and the bound (exclusive)

   509      *

   510      * @throws IllegalArgumentException if {@code origin} is greater than

   511      *         or equal to {@code bound}

   512      *

   513      * @implNote The default implementation simply calls

   514      *           {@code RNGSupport.checkRange(origin, bound)} and then

   515      *           {@code RNGSupport.boundedNextInt(this, origin, bound)}.

   516      */

   517     default int nextInt(int origin, int bound) {

   518         RNGSupport.checkRange(origin, bound);

   519         return RNGSupport.boundedNextInt(this, origin, bound);

   520     }

   521 

   522     /**

   523      * Returns a pseudorandomly chosen {@code long} value.

   524      *

   525      * @return a pseudorandomly chosen {@code long} value

   526      */

   527     long nextLong();

   528 

   529     /**

   530      * Returns a pseudorandomly chosen {@code long} value between

   531      * zero (inclusive) and the specified bound (exclusive).

   532      *

   533      * @param bound the upper bound (exclusive) for the returned value.  Must be positive.

   534      *

   535      * @return a pseudorandomly chosen {@code long} value between

   536      *         zero (inclusive) and the bound (exclusive)

   537      *

   538      * @throws IllegalArgumentException if {@code bound} is not positive

   539      *

   540      * @implNote The default implementation simply calls

   541      *           {@code RNGSupport.checkBound(bound)} and then

   542      *           {@code RNGSupport.boundedNextLong(this, bound)}.

   543      */

   544     default long nextLong(long bound) {

   545         RNGSupport.checkBound(bound);

   546         return RNGSupport.boundedNextLong(this, bound);

   547     }

   548 

   549     /**

   550      * Returns a pseudorandomly chosen {@code long} value between the

   551      * specified origin (inclusive) and the specified bound (exclusive).

   552      *

   553      * @param origin the least value that can be returned

   554      * @param bound the upper bound (exclusive) for the returned value

   555      *

   556      * @return a pseudorandomly chosen {@code long} value between the

   557      *         origin (inclusive) and the bound (exclusive)

   558      *

   559      * @throws IllegalArgumentException if {@code origin} is greater than

   560      *         or equal to {@code bound}

   561      *

   562      * @implNote The default implementation simply calls

   563      *           {@code RNGSupport.checkRange(origin, bound)} and then

   564      *           {@code RNGSupport.boundedNextInt(this, origin, bound)}.

   565      *

   566      */

   567     default long nextLong(long origin, long bound) {

   568         RNGSupport.checkRange(origin, bound);

   569         return RNGSupport.boundedNextLong(this, origin, bound);

   570     }

   571 

   572     /**

   573      * Returns a {@code double} value pseudorandomly chosen from

   574      * a Gaussian (normal) distribution whose mean is 0 and whose

   575      * standard deviation is 1.

   576      *

   577      * @return a {@code double} value pseudorandomly chosen from a

   578      *         Gaussian distribution

   579      */

   580     default double nextGaussian() {

   581         return RNGSupport.computeNextGaussian(this);

   582     }

   583 

   584     /**

   585      * Returns a {@code double} value pseudorandomly chosen from

   586      * a Gaussian (normal) distribution with a mean and

   587      * standard deviation specified by the arguments.

   588      *

   589      * @param mean the mean of the Gaussian distribution to be drawn from

   590      * @param stddev the standard deviation (square root of the variance)

   591      *        of the Gaussian distribution to be drawn from

   592      *

   593      * @return a {@code double} value pseudorandomly chosen from the

   594      *         specified Gaussian distribution

   595      *

   596      * @throws IllegalArgumentException if {@code stddev} is negative

   597      */

   598     default double nextGaussian(double mean, double stddev) {

   599         if (stddev < 0.0) throw new IllegalArgumentException("standard deviation must be non-negative");

   600         return mean + stddev * RNGSupport.computeNextGaussian(this);

   601     }

   602 

   603     /**

   604      * Returns a nonnegative {@code double} value pseudorandomly chosen

   605      * from an exponential distribution whose mean is 1.

   606      *

   607      * @return a nonnegative {@code double} value pseudorandomly chosen from an

   608      *         exponential distribution

   609      */

   610     default double nextExponential() {

   611         return RNGSupport.computeNextExponential(this);

   612     }

   613 

   614     /**

   615      * Returns the period of this {@link RandomNumberGenerator} object.

   616      *

   617      * @return a {@link BigInteger} whose value is the number of distinct possible states of this

   618      *         {@link RandomNumberGenerator} object, or 0 if unknown, or negative if extremely

   619      *         large.

   620      */

   621     BigInteger period();

   622 

   623     /**

   624      * The value (0) returned by the {@code period()} method if the period is unknown.

   625      */

   626     static final BigInteger UNKNOWN_PERIOD = BigInteger.ZERO;

   627 

   628     /**

   629      * The (negative) value returned by the {@code period()} method if this generator

   630      * has no period because it is truly random rather than just pseudorandom.

   631      */

   632     static final BigInteger TRULY_RANDOM = BigInteger.valueOf(-1);

   633 

   634     /**

   635      * The (negative) value that may be returned by the {@code period()} method

   636      * if this generator has a huge period (larger than 2**(2**16)).

   637      */

   638     static final BigInteger HUGE_PERIOD = BigInteger.valueOf(-2);

   639 }