/*

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

 * 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;

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 <i>split</i> 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

 */

public 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);

    }

}