001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.commons.math3.random;
018    
019    
020    /**
021     * Interface extracted from <code>java.util.Random</code>.  This interface is
022     * implemented by {@link AbstractRandomGenerator}.
023     *
024     * @since 1.1
025     * @version $Id: RandomGenerator.java 1416643 2012-12-03 19:37:14Z tn $
026     */
027    public interface RandomGenerator {
028    
029        /**
030         * Sets the seed of the underlying random number generator using an
031         * <code>int</code> seed.
032         * <p>Sequences of values generated starting with the same seeds
033         * should be identical.
034         * </p>
035         * @param seed the seed value
036         */
037        void setSeed(int seed);
038    
039        /**
040         * Sets the seed of the underlying random number generator using an
041         * <code>int</code> array seed.
042         * <p>Sequences of values generated starting with the same seeds
043         * should be identical.
044         * </p>
045         * @param seed the seed value
046         */
047        void setSeed(int[] seed);
048    
049        /**
050         * Sets the seed of the underlying random number generator using a
051         * <code>long</code> seed.
052         * <p>Sequences of values generated starting with the same seeds
053         * should be identical.
054         * </p>
055         * @param seed the seed value
056         */
057        void setSeed(long seed);
058    
059        /**
060         * Generates random bytes and places them into a user-supplied
061         * byte array.  The number of random bytes produced is equal to
062         * the length of the byte array.
063         *
064         * @param bytes the non-null byte array in which to put the
065         * random bytes
066         */
067        void nextBytes(byte[] bytes);
068    
069        /**
070         * Returns the next pseudorandom, uniformly distributed <code>int</code>
071         * value from this random number generator's sequence.
072         * All 2<font size="-1"><sup>32</sup></font> possible <tt>int</tt> values
073         * should be produced with  (approximately) equal probability.
074         *
075         * @return the next pseudorandom, uniformly distributed <code>int</code>
076         *  value from this random number generator's sequence
077         */
078        int nextInt();
079    
080        /**
081         * Returns a pseudorandom, uniformly distributed <tt>int</tt> value
082         * between 0 (inclusive) and the specified value (exclusive), drawn from
083         * this random number generator's sequence.
084         *
085         * @param n the bound on the random number to be returned.  Must be
086         * positive.
087         * @return  a pseudorandom, uniformly distributed <tt>int</tt>
088         * value between 0 (inclusive) and n (exclusive).
089         * @throws IllegalArgumentException  if n is not positive.
090         */
091        int nextInt(int n);
092    
093        /**
094         * Returns the next pseudorandom, uniformly distributed <code>long</code>
095         * value from this random number generator's sequence.  All
096         * 2<font size="-1"><sup>64</sup></font> possible <tt>long</tt> values
097         * should be produced with (approximately) equal probability.
098         *
099         * @return  the next pseudorandom, uniformly distributed <code>long</code>
100         *value from this random number generator's sequence
101         */
102        long nextLong();
103    
104        /**
105         * Returns the next pseudorandom, uniformly distributed
106         * <code>boolean</code> value from this random number generator's
107         * sequence.
108         *
109         * @return  the next pseudorandom, uniformly distributed
110         * <code>boolean</code> value from this random number generator's
111         * sequence
112         */
113        boolean nextBoolean();
114    
115        /**
116         * Returns the next pseudorandom, uniformly distributed <code>float</code>
117         * value between <code>0.0</code> and <code>1.0</code> from this random
118         * number generator's sequence.
119         *
120         * @return  the next pseudorandom, uniformly distributed <code>float</code>
121         * value between <code>0.0</code> and <code>1.0</code> from this
122         * random number generator's sequence
123         */
124        float nextFloat();
125    
126        /**
127         * Returns the next pseudorandom, uniformly distributed
128         * <code>double</code> value between <code>0.0</code> and
129         * <code>1.0</code> from this random number generator's sequence.
130         *
131         * @return  the next pseudorandom, uniformly distributed
132         *  <code>double</code> value between <code>0.0</code> and
133         *  <code>1.0</code> from this random number generator's sequence
134         */
135        double nextDouble();
136    
137        /**
138         * Returns the next pseudorandom, Gaussian ("normally") distributed
139         * <code>double</code> value with mean <code>0.0</code> and standard
140         * deviation <code>1.0</code> from this random number generator's sequence.
141         *
142         * @return  the next pseudorandom, Gaussian ("normally") distributed
143         * <code>double</code> value with mean <code>0.0</code> and
144         * standard deviation <code>1.0</code> from this random number
145         *  generator's sequence
146         */
147        double nextGaussian();
148    }