/*
 * 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);
    }
}