View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.math3.random;
18  
19  
20  /**
21   * Interface extracted from <code>java.util.Random</code>.  This interface is
22   * implemented by {@link AbstractRandomGenerator}.
23   *
24   * @since 1.1
25   * @version $Id: RandomGenerator.java 1416643 2012-12-03 19:37:14Z tn $
26   */
27  public interface RandomGenerator {
28  
29      /**
30       * Sets the seed of the underlying random number generator using an
31       * <code>int</code> seed.
32       * <p>Sequences of values generated starting with the same seeds
33       * should be identical.
34       * </p>
35       * @param seed the seed value
36       */
37      void setSeed(int seed);
38  
39      /**
40       * Sets the seed of the underlying random number generator using an
41       * <code>int</code> array seed.
42       * <p>Sequences of values generated starting with the same seeds
43       * should be identical.
44       * </p>
45       * @param seed the seed value
46       */
47      void setSeed(int[] seed);
48  
49      /**
50       * Sets the seed of the underlying random number generator using a
51       * <code>long</code> seed.
52       * <p>Sequences of values generated starting with the same seeds
53       * should be identical.
54       * </p>
55       * @param seed the seed value
56       */
57      void setSeed(long seed);
58  
59      /**
60       * Generates random bytes and places them into a user-supplied
61       * byte array.  The number of random bytes produced is equal to
62       * the length of the byte array.
63       *
64       * @param bytes the non-null byte array in which to put the
65       * random bytes
66       */
67      void nextBytes(byte[] bytes);
68  
69      /**
70       * Returns the next pseudorandom, uniformly distributed <code>int</code>
71       * value from this random number generator's sequence.
72       * All 2<font size="-1"><sup>32</sup></font> possible <tt>int</tt> values
73       * should be produced with  (approximately) equal probability.
74       *
75       * @return the next pseudorandom, uniformly distributed <code>int</code>
76       *  value from this random number generator's sequence
77       */
78      int nextInt();
79  
80      /**
81       * Returns a pseudorandom, uniformly distributed <tt>int</tt> value
82       * between 0 (inclusive) and the specified value (exclusive), drawn from
83       * this random number generator's sequence.
84       *
85       * @param n the bound on the random number to be returned.  Must be
86       * positive.
87       * @return  a pseudorandom, uniformly distributed <tt>int</tt>
88       * value between 0 (inclusive) and n (exclusive).
89       * @throws IllegalArgumentException  if n is not positive.
90       */
91      int nextInt(int n);
92  
93      /**
94       * Returns the next pseudorandom, uniformly distributed <code>long</code>
95       * value from this random number generator's sequence.  All
96       * 2<font size="-1"><sup>64</sup></font> possible <tt>long</tt> values
97       * should be produced with (approximately) equal probability.
98       *
99       * @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 }