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 * https://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
18 /*
19 * This is not the original file distributed by the Apache Software Foundation
20 * It has been modified by the Hipparchus project
21 */
22 package org.hipparchus.random;
23
24
25 /**
26 * Interface for generators of random number sequences.
27 */
28 public interface RandomGenerator {
29
30 /**
31 * Sets the seed of the underlying random number generator using an
32 * <code>int</code> seed.
33 * <p>
34 * Sequences of values generated starting with the same seeds
35 * should be identical.
36 *
37 * @param seed the seed value
38 */
39 void setSeed(int seed);
40
41 /**
42 * Sets the seed of the underlying random number generator using an
43 * <code>int</code> array seed.
44 * <p>
45 * Sequences of values generated starting with the same seeds
46 * should be identical.
47 *
48 * @param seed the seed value
49 */
50 void setSeed(int[] seed);
51
52 /**
53 * Sets the seed of the underlying random number generator using a
54 * <code>long</code> seed.
55 * <p>
56 * Sequences of values generated starting with the same seeds
57 * should be identical.
58 *
59 * @param seed the seed value
60 */
61 void setSeed(long seed);
62
63 /**
64 * Generates random bytes and places them into a user-supplied
65 * byte array. The number of random bytes produced is equal to
66 * the length of the byte array.
67 *
68 * @param bytes the non-null byte array in which to put the random bytes
69 */
70 void nextBytes(byte[] bytes);
71
72 /**
73 * Generates random bytes and places them into a user-supplied
74 * byte array.
75 *
76 * @param bytes the non-null byte array in which to put the random bytes
77 * @param offset the starting index for inserting the generated bytes into
78 * the array
79 * @param len the number of bytes to generate
80 * @throws org.hipparchus.exception.MathIllegalArgumentException if {@code offset < 0} or
81 * {@code offset + len >= bytes.length}
82 */
83 void nextBytes(byte[] bytes, int offset, int len);
84
85 /**
86 * Returns the next pseudorandom, uniformly distributed {@code int}
87 * value from this random number generator's sequence.
88 * <p>
89 * All 2<sup>32</sup> possible {@code int} values should be produced
90 * with (approximately) equal probability.
91 *
92 * @return the next pseudorandom, uniformly distributed {@code int}
93 * value from this random number generator's sequence
94 */
95 int nextInt();
96
97 /**
98 * Returns a pseudorandom, uniformly distributed {@code int} value
99 * between 0 (inclusive) and the specified value (exclusive), drawn from
100 * this random number generator's sequence.
101 *
102 * @param n the bound on the random number to be returned. Must be positive.
103 * @return a pseudorandom, uniformly distributed {@code int}
104 * value between 0 (inclusive) and n (exclusive).
105 * @throws IllegalArgumentException if n is not positive.
106 */
107 int nextInt(int n);
108
109 /**
110 * Returns the next pseudorandom, uniformly distributed {@code long}
111 * value from this random number generator's sequence. All 2<sup>64</sup>
112 * possible {@code long} values should be produced with (approximately)
113 * equal probability.
114 *
115 * @return the next pseudorandom, uniformly distributed {@code long}
116 * value from this random number generator's sequence
117 */
118 long nextLong();
119
120 /**
121 * Returns a pseudorandom, uniformly distributed {@code int} value
122 * between 0 (inclusive) and the specified value (exclusive), drawn from
123 * this random number generator's sequence.
124 *
125 * @param n the bound on the random number to be returned. Must be positive.
126 * @return a pseudorandom, uniformly distributed {@code int}
127 * value between 0 (inclusive) and n (exclusive).
128 * @throws IllegalArgumentException if n is not positive.
129 */
130 long nextLong(long n);
131
132 /**
133 * Returns the next pseudorandom, uniformly distributed
134 * {@code boolean} value from this random number generator's sequence.
135 *
136 * @return the next pseudorandom, uniformly distributed
137 * <code>boolean</code> value from this random number generator's
138 * sequence
139 */
140 boolean nextBoolean();
141
142 /**
143 * Returns the next pseudorandom, uniformly distributed {@code float}
144 * value between <code>0.0</code> and <code>1.0</code> from this random
145 * number generator's sequence.
146 *
147 * @return the next pseudorandom, uniformly distributed {@code float}
148 * value between <code>0.0</code> and <code>1.0</code> from this
149 * random number generator's sequence
150 */
151 float nextFloat();
152
153 /**
154 * Returns the next pseudorandom, uniformly distributed
155 * <code>double</code> value between <code>0.0</code> and
156 * <code>1.0</code> from this random number generator's sequence.
157 *
158 * @return the next pseudorandom, uniformly distributed
159 * <code>double</code> value between <code>0.0</code> and
160 * <code>1.0</code> from this random number generator's sequence
161 */
162 double nextDouble();
163
164 /**
165 * Returns the next pseudorandom, Gaussian ("normally") distributed
166 * <code>double</code> value with mean <code>0.0</code> and standard
167 * deviation <code>1.0</code> from this random number generator's sequence.
168 *
169 * @return the next pseudorandom, Gaussian ("normally") distributed
170 * <code>double</code> value with mean <code>0.0</code> and
171 * standard deviation <code>1.0</code> from this random number
172 * generator's sequence
173 */
174 double nextGaussian();
175 }