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.math.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 $Revision: 796543 $ $Date: 2009-07-21 17:32:38 -0400 (Tue, 21 Jul 2009) $
26 */
27 public interface RandomGenerator {
28
29 /**
30 * Sets the seed of the underyling 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 underyling 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 underyling 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 }