/*

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

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

 *

 *

 *

 *

 *

 *

 *

 *

 *

 *

 *

 *

 *

 *

 *

 *

 *

 *

 *

 *

 */

// package java.util;

import java.util.stream.Stream;

import java.util.stream.StreamSupport;

import java.util.stream.IntStream;

import java.util.stream.LongStream;

import java.util.stream.DoubleStream;

/**

 * This interface is designed to provide a common protocol for objects

 * that generate sequences of pseudorandom numbers (or Boolean values)

 * and furthermore can be <it>split</it> into two objects (the original

 * one and a new one) each of which obey that same protocol (and therefore

 * can be recursively split indefinitely).

 *

 * <p>Ideally, all {@code SplittableRNG} objects produced by recursive

 * splitting from a single original {@code SplittableRNG} object are

 * statistically independent of one another and individually uniform.

 * Therefore we would expect the set of values collectively generated

 * by a set of such objects to have the same statistical properties as

 * if the same quantity of values were generated by a single thread

 * using a single {@code SplittableRNG} object.  In practice, one must

 * settle for some approximation to independence and uniformity.

 *

 * <p>Methods are provided to perform a single splitting operation and

 * also to produce a stream of generators split off from the original

 * (by either iterative or recursive splitting, or a combination).

 *

 * <p>An implementation of the {@code SplittableRng} interface must provide

 * concrete definitions for the methods {@code nextInt()}, {@code nextLong},

 * {@code period()}, {@code split()}, {@code split(SplittableRng)},

 * {@code splits()}, {@code splits(long)}, {@code splits(SplittableRng)},

 * and {@code splits(long, SplittableRng)}.  Perhaps the most convenient

 * way to implement this interface is to extend the abstract class

 * {@link java.util.AbstractSplittableRng}.

 *

 * <p>Objects that implement {@code java.util.SplittableRNG} are

 * typically not cryptographically secure.  Consider instead using

 * {@link java.security.SecureRandom} to get a cryptographically

 * secure pseudo-random number generator for use by

 * security-sensitive applications.

 *

 * @author  Guy Steele

 * @since   1.9

 */

interface SplittableRng extends StreamableRng {

    /**

     * Returns a new pseudorandom number generator, split off from

     * this one, that implements the {@code Rng} and {@code SplittableRng}

     * interfaces.

     *

     * This pseudorandom number generator may be used as a source of

     * pseudorandom bits used to initialize the state the new one.

     *

     * @return a new object that implements the {@code Rng} and

     *         {@code SplittableRng} interfaces

     */

    SplittableRng split();

    /**

     * Returns a new pseudorandom number generator, split off from

     * this one, that implements the {@code Rng} and {@code SplittableRng}

     * interfaces.

     *

     * @param source a {@code SplittableRng} instance to be used instead

     *               of this one as a source of pseudorandom bits used to

     *               initialize the state of the new ones.

     *

     * @return an object that implements the {@code Rng} and

     *         {@code SplittableRng} interfaces

     */

    SplittableRng split(SplittableRng source);

    /**

     * Returns an effectively unlimited stream of new pseudorandom

     * number generators, each of which implements the {@code SplittableRng}

     * interface.

     *

     * This pseudorandom number generator may be used as a source of

     * pseudorandom bits used to initialize the state the new ones.

     *

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

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

     *

     * @return a stream of {@code SplittableRng} objects

     */

    default Stream<SplittableRng> splits() {

	return this.splits(this);

    }

    /**

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

     * new pseudorandom number generators, each of which implements the

     * {@code SplittableRng} interface.

     *

     * This pseudorandom number generator may be used as a source of

     * pseudorandom bits used to initialize the state the new ones.

     *

     * @param streamSize the number of values to generate

     * @return a stream of {@code SplittableRng} objects

     * @throws IllegalArgumentException if {@code streamSize} is

     *         less than zero

     */

    Stream<SplittableRng> splits(long streamSize);

    /**

     * Returns an effectively unlimited stream of new pseudorandom

     * number generators, each of which implements the {@code SplittableRng}

     * interface.

     *

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

     * equivalent to {@code splits(Long.MAX_VALUE, source)}.

     *

     * @param source a {@code SplittableRng} instance to be used instead

     *               of this one as a source of pseudorandom bits used to

     *               initialize the state of the new ones.

     *

     * @return a stream of {@code SplittableRng} objects

     */

    Stream<SplittableRng> splits(SplittableRng source);

    /**

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

     * new pseudorandom number generators, each of which implements the

     * {@code SplittableRng} interface.

     *

     * @param streamSize the number of values to generate

     * @param source a {@code SplittableRng} instance to be used instead

     *               of this one as a source of pseudorandom bits used to

     *               initialize the state of the new ones.

     * @return a stream of {@code SplittableRng} objects

     * @throws IllegalArgumentException if {@code streamSize} is

     *         less than zero

     */

    Stream<SplittableRng> splits(long streamSize, SplittableRng source);

    /**

     * Returns an effectively unlimited stream of new pseudorandom

     * number generators, each of which implements the {@code Rng}

     * interface.  Ideally the generators in the stream will appear

     * to be statistically independent.

     *

     * @implNote The default implementation calls {@code splits()}.

     *

     * @return a stream of objects that implement the {@code Rng} interface

     */

    default Stream<Rng> rngs() {

	return this.splits().map(x -> (Rng)x);

    }

    /**

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

     * new pseudorandom number generators, each of which implements the

     * {@code Rng} interface.  Ideally the generators in the stream will

     * appear to be statistically independent.

     *

     * @implNote The default implementation calls {@code splits(streamSize)}.

     *

     * @param streamSize the number of generators to generate

     * @return a stream of objects that implement the {@code Rng} interface

     * @throws IllegalArgumentException if {@code streamSize} is

     *         less than zero

     */

    default Stream<Rng> rngs(long streamSize) {

	return this.splits(streamSize).map(x -> (Rng)x);

    }

}