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   */
26  public interface RandomGenerator {
27  
28      /**
29       * Sets the seed of the underlying random number generator using an
30       * <code>int</code> seed.
31       * <p>Sequences of values generated starting with the same seeds
32       * should be identical.
33       * </p>
34       * @param seed the seed value
35       */
36      void setSeed(int seed);
37  
38      /**
39       * Sets the seed of the underlying random number generator using an
40       * <code>int</code> array seed.
41       * <p>Sequences of values generated starting with the same seeds
42       * should be identical.
43       * </p>
44       * @param seed the seed value
45       */
46      void setSeed(int[] seed);
47  
48      /**
49       * Sets the seed of the underlying random number generator using a
50       * <code>long</code> seed.
51       * <p>Sequences of values generated starting with the same seeds
52       * should be identical.
53       * </p>
54       * @param seed the seed value
55       */
56      void setSeed(long seed);
57  
58      /**
59       * Generates random bytes and places them into a user-supplied
60       * byte array.  The number of random bytes produced is equal to
61       * the length of the byte array.
62       *
63       * @param bytes the non-null byte array in which to put the
64       * random bytes
65       */
66      void nextBytes(byte[] bytes);
67  
68      /**
69       * Returns the next pseudorandom, uniformly distributed <code>int</code>
70       * value from this random number generator's sequence.
71       * All 2<font size="-1"><sup>32</sup></font> possible {@code int} values
72       * should be produced with  (approximately) equal probability.
73       *
74       * @return the next pseudorandom, uniformly distributed <code>int</code>
75       *  value from this random number generator's sequence
76       */
77      int nextInt();
78  
79      /**
80       * Returns a pseudorandom, uniformly distributed {@code int} value
81       * between 0 (inclusive) and the specified value (exclusive), drawn from
82       * this random number generator's sequence.
83       *
84       * @param n the bound on the random number to be returned.  Must be
85       * positive.
86       * @return  a pseudorandom, uniformly distributed {@code int}
87       * value between 0 (inclusive) and n (exclusive).
88       * @throws IllegalArgumentException  if n is not positive.
89       */
90      int nextInt(int n);
91  
92      /**
93       * Returns the next pseudorandom, uniformly distributed <code>long</code>
94       * value from this random number generator's sequence.  All
95       * 2<font size="-1"><sup>64</sup></font> possible {@code long} values
96       * should be produced with (approximately) equal probability.
97       *
98       * @return  the next pseudorandom, uniformly distributed <code>long</code>
99       *value from this random number generator's sequence
100      */
101     long nextLong();
102 
103     /**
104      * Returns the next pseudorandom, uniformly distributed
105      * <code>boolean</code> value from this random number generator's
106      * sequence.
107      *
108      * @return  the next pseudorandom, uniformly distributed
109      * <code>boolean</code> value from this random number generator's
110      * sequence
111      */
112     boolean nextBoolean();
113 
114     /**
115      * Returns the next pseudorandom, uniformly distributed <code>float</code>
116      * value between <code>0.0</code> and <code>1.0</code> from this random
117      * number generator's sequence.
118      *
119      * @return  the next pseudorandom, uniformly distributed <code>float</code>
120      * value between <code>0.0</code> and <code>1.0</code> from this
121      * random number generator's sequence
122      */
123     float nextFloat();
124 
125     /**
126      * Returns the next pseudorandom, uniformly distributed
127      * <code>double</code> value between <code>0.0</code> and
128      * <code>1.0</code> from this random number generator's sequence.
129      *
130      * @return  the next pseudorandom, uniformly distributed
131      *  <code>double</code> value between <code>0.0</code> and
132      *  <code>1.0</code> from this random number generator's sequence
133      */
134     double nextDouble();
135 
136     /**
137      * Returns the next pseudorandom, Gaussian ("normally") distributed
138      * <code>double</code> value with mean <code>0.0</code> and standard
139      * deviation <code>1.0</code> from this random number generator's sequence.
140      *
141      * @return  the next pseudorandom, Gaussian ("normally") distributed
142      * <code>double</code> value with mean <code>0.0</code> and
143      * standard deviation <code>1.0</code> from this random number
144      *  generator's sequence
145      */
146     double nextGaussian();
147 }