001package squidpony.squidmath;
002
003import java.io.Serializable;
004
005/**
006 * This interface defines the interactions required of a random number
007 * generator. It is a replacement for Java's built-in Random because for
008 * improved performance.
009 *
010 * @author Eben Howard - http://squidpony.com - howard@squidpony.com
011 */
012public interface RandomnessSource extends Serializable {
013
014    /**
015     * Using this method, any algorithm that might use the built-in Java Random
016     * can interface with this randomness source.
017     *
018     * @param bits the number of bits to be returned
019     * @return the integer containing the appropriate number of bits
020     */
021    int next(int bits);
022
023    /**
024     *
025     * Using this method, any algorithm that needs to efficiently generate more
026     * than 32 bits of random data can interface with this randomness source.
027     *
028     * Get a random long between Long.MIN_VALUE and Long.MAX_VALUE (both inclusive).
029     * @return a random long between Long.MIN_VALUE and Long.MAX_VALUE (both inclusive)
030     */
031    long nextLong();
032
033    /**
034     * Produces a copy of this RandomnessSource that, if next() and/or nextLong() are called on this object and the
035     * copy, both will generate the same sequence of random numbers from the point copy() was called. This just needs to
036     * copy the state so it isn't shared, usually, and produce a new value with the same exact state.
037     * @return a copy of this RandomnessSource
038     */
039    RandomnessSource copy();
040}