/*
 * 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.random;

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 {@link SplittableRNG} objects produced by recursive
 * splitting from a single original {@link 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 {@link 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 {@link 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 AbstractSplittableRNG}.
 * <p>
 * Objects that implement {@link 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.
 *
 * @since 14
 */
public interface SplittableRNG extends StreamableRNG {

    /**
     * Returns a new pseudorandom number generator, split off from
     * this one, that implements the {@link RandomNumberGenerator} and {@link 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 {@link RandomNumberGenerator} and
     *         {@link SplittableRNG} interfaces
     */
    SplittableRNG split();

    /**
     * Returns a new pseudorandom number generator, split off from
     * this one, that implements the {@link RandomNumberGenerator} and {@link SplittableRNG}
     * interfaces.
     *
     * @param source a {@link 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 {@link RandomNumberGenerator} and
     *         {@link SplittableRNG} interfaces
     */
    SplittableRNG split(SplittableRNG source);

    /**
     * Returns an effectively unlimited stream of new pseudorandom
     * number generators, each of which implements the {@link 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 {@link 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
     * {@link 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 {@link 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 {@link SplittableRNG}
     * interface.
     *
     * @param source a {@link 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 {@link SplittableRNG} objects
     *
     * @implNote It is permitted to implement this method in a manner
     *           equivalent to {@code splits(Long.MAX_VALUE, source)}.
     */
    Stream<SplittableRNG> splits(SplittableRNG source);

    /**
     * Returns a stream producing the given {@code streamSize} number of
     * new pseudorandom number generators, each of which implements the
     * {@link SplittableRNG} interface.
     *
     * @param streamSize the number of values to generate
     * @param source a {@link 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 {@link 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 {@link RandomNumberGenerator}
     * interface.  Ideally the generators in the stream will appear
     * to be statistically independent.
     *
     * @return a stream of objects that implement the {@link RandomNumberGenerator} interface
     *
     * @implNote The default implementation calls {@code splits()}.
     */
    default Stream<RandomNumberGenerator> rngs() {
        return this.splits().map(x -> (RandomNumberGenerator)x);
    }

    /**
     * Returns a stream producing the given {@code streamSize} number of
     * new pseudorandom number generators, each of which implements the
     * {@link RandomNumberGenerator} interface.  Ideally the generators in the stream will
     * appear to be statistically independent.
     *
     * @param streamSize the number of generators to generate
     *
     * @return a stream of objects that implement the {@link RandomNumberGenerator} interface
     *
     * @throws IllegalArgumentException if {@code streamSize} is
     *         less than zero
     *
     * @implNote The default implementation calls {@code splits(streamSize)}.
     */
    default Stream<RandomNumberGenerator> rngs(long streamSize) {
        return this.splits(streamSize).map(x -> (RandomNumberGenerator)x);
    }
}