View Javadoc

    1   /*
    2    * Copyright 2005 The Apache Software Foundation.
    3    *
    4    * Licensed under the Apache License, Version 2.0 (the "License");
    5    * you may not use this file except in compliance with the License.
    6    * You may obtain a copy of the License at
    7    *
    8    *      http://www.apache.org/licenses/LICENSE-2.0
    9    *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16  package org.apache.commons.math.random;
    17
    18  /***
    19   * Interface extracted from <code>java.util.Random</code>.  This interface is
    20   * implemented by {@link AbstractRandomGenerator}.
    21   *
    22   * @since 1.1
    23   * @version $Revision:$ $Date$
    24   */
    25  public interface RandomGenerator {
    26
    27      /***
    28       * Sets the seed of the underyling random number generator using a
    29       * <code>long</code> seed.  Sequences of values generated starting with the
    30       * same seeds should be identical.
    31       *
    32       * @param seed the seed value
    33       */
    34      void setSeed(long seed);
    35
    36      /***
    37       * Generates random bytes and places them into a user-supplied
    38       * byte array.  The number of random bytes produced is equal to
    39       * the length of the byte array.
    40       *
    41       * @param bytes the non-null byte array in which to put the
    42       * random bytes
    43       */
    44      void nextBytes(byte[] bytes);
    45
    46      /***
    47       * Returns the next pseudorandom, uniformly distributed <code>int</code>
    48       * value from this random number generator's sequence.
    49       * All 2<font size="-1"><sup>32</sup></font> possible <tt>int</tt> values
    50       * should be produced with  (approximately) equal probability.
    51       *
    52       * @return the next pseudorandom, uniformly distributed <code>int</code>
    53       *  value from this random number generator's sequence
    54       */
    55      int nextInt();
    56
    57      /***
    58       * Returns a pseudorandom, uniformly distributed <tt>int</tt> value
    59       * between 0 (inclusive) and the specified value (exclusive), drawn from
    60       * this random number generator's sequence.
    61       *
    62       * @param n the bound on the random number to be returned.  Must be
    63       * positive.
    64       * @return  a pseudorandom, uniformly distributed <tt>int</tt>
    65       * value between 0 (inclusive) and n (exclusive).
    66       * @throws IllegalArgumentException  if n is not positive.
    67       */
    68      int nextInt(int n);
    69
    70      /***
    71       * Returns the next pseudorandom, uniformly distributed <code>long</code>
    72       * value from this random number generator's sequence.  All
    73       * 2<font size="-1"><sup>64</sup></font> possible <tt>long</tt> values
    74       * should be produced with (approximately) equal probability.
    75       *
    76       * @return  the next pseudorandom, uniformly distributed <code>long</code>
    77       *value from this random number generator's sequence
    78       */
    79      long nextLong();
    80
    81      /***
    82       * Returns the next pseudorandom, uniformly distributed
    83       * <code>boolean</code> value from this random number generator's
    84       * sequence.
    85       *
    86       * @return  the next pseudorandom, uniformly distributed
    87       * <code>boolean</code> value from this random number generator's
    88       * sequence
    89       */
    90      boolean nextBoolean();
    91
    92      /***
    93       * Returns the next pseudorandom, uniformly distributed <code>float</code>
    94       * value between <code>0.0</code> and <code>1.0</code> from this random
    95       * number generator's sequence.
    96       *
    97       * @return  the next pseudorandom, uniformly distributed <code>float</code>
    98       * value between <code>0.0</code> and <code>1.0</code> from this
    99       * random number generator's sequence
    100      */
    101     float nextFloat();
    102
    103     /***
    104      * Returns the next pseudorandom, uniformly distributed
    105      * <code>double</code> value between <code>0.0</code> and
    106      * <code>1.0</code> from this random number generator's sequence.
    107      *
    108      * @return  the next pseudorandom, uniformly distributed
    109      *  <code>double</code> value between <code>0.0</code> and
    110      *  <code>1.0</code> from this random number generator's sequence
    111      */
    112     double nextDouble();
    113
    114     /***
    115      * Returns the next pseudorandom, Gaussian ("normally") distributed
    116      * <code>double</code> value with mean <code>0.0</code> and standard
    117      * deviation <code>1.0</code> from this random number generator's sequence.
    118      *
    119      * @return  the next pseudorandom, Gaussian ("normally") distributed
    120      * <code>double</code> value with mean <code>0.0</code> and
    121      * standard deviation <code>1.0</code> from this random number
    122      *  generator's sequence
    123      */
    124     double nextGaussian();
    125 }