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

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

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

 * published by the Free Software Foundation.  Oracle designates this

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

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

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

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

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

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

 * accompanied this code).

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

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

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

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

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

 * questions.

package java.util.random;

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

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

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

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

 * chosen values.

 * <p>

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

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

 * approximation to independence and uniformity.

 * <p>

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

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

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

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

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

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

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

 * <p>

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

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

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

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

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

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

 * same range.

 * <p>

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

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

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

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

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

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

 * <p>

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

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

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

 * SplittableRNG} or {@link JumpableRNG} interface.

 * <p>

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

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

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

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

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

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

 * <p>

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

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

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

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

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

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

 * @since 14

public interface RandomNumberGenerator {

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

     *

     *

     *

     *

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

     *           equivalent to

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

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

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

        RNGSupport.checkRange(randomNumberOrigin, randomNumberBound);

     * @param streamSize the number of values to generate

     *

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

     *

     * @throws IllegalArgumentException if {@code streamSize} is

     *         less than zero

     *

        RNGSupport.checkStreamSize(streamSize);

        return doubles().limit(streamSize);

     *

     *

     *

     * @implNote The default implementation produces a sequential stream

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

                          double randomNumberBound) {

        RNGSupport.checkStreamSize(streamSize);

        RNGSupport.checkRange(randomNumberOrigin, randomNumberBound);

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

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

     *

     *

     *

     *

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

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

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

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

        RNGSupport.checkRange(randomNumberOrigin, randomNumberBound);

     * @param streamSize the number of values to generate

     *

     *

     * @implNote The default implementation produces a sequential stream

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

        RNGSupport.checkStreamSize(streamSize);

        return ints().limit(streamSize);

     *

     *

     *

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

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

                          int randomNumberBound) {

        RNGSupport.checkStreamSize(streamSize);

        RNGSupport.checkRange(randomNumberOrigin, randomNumberBound);

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

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

     *

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

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

     *

     *

     *

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

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

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

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

        RNGSupport.checkRange(randomNumberOrigin, randomNumberBound);

     * @param streamSize the number of values to generate

     *

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

     *

     * @throws IllegalArgumentException if {@code streamSize} is

     *         less than zero

     *

        RNGSupport.checkStreamSize(streamSize);

        return longs().limit(streamSize);

     *

     *

     *

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

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

                          long randomNumberBound) {

        RNGSupport.checkStreamSize(streamSize);

        RNGSupport.checkRange(randomNumberOrigin, randomNumberBound);

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

     * <p>

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

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

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

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

     * <p>

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

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

     *

     *

     *

     * @implNote The default implementation simply calls

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

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

        RNGSupport.checkBound(bound);

        return RNGSupport.boundedNextFloat(this, bound);

     *

     *

     *

     * @implNote The default implementation simply calls

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

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

        RNGSupport.checkRange(origin, bound);

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

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

     * <p>

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

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

     *

     *

     *

     * @implNote The default implementation simply calls

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

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

        RNGSupport.checkBound(bound);

        return RNGSupport.boundedNextDouble(this, bound);

     *

     *

     *

     * @implNote The default implementation simply calls

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

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

        RNGSupport.checkRange(origin, bound);

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

     * <p>

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

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

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

     *

     *

     * @implNote The default implementation simply calls

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

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

        RNGSupport.checkBound(bound);

        return RNGSupport.boundedNextInt(this, bound);