    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    }