001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.math.random;
018
019
020 /**
021 * Interface extracted from <code>java.util.Random</code>. This interface is
022 * implemented by {@link AbstractRandomGenerator}.
023 *
024 * @since 1.1
025 * @version $Revision: 949750 $ $Date: 2010-05-31 16:06:04 +0200 (lun. 31 mai 2010) $
026 */
027 public interface RandomGenerator {
028
029 /**
030 * Sets the seed of the underlying random number generator using an
031 * <code>int</code> seed.
032 * <p>Sequences of values generated starting with the same seeds
033 * should be identical.
034 * </p>
035 * @param seed the seed value
036 */
037 void setSeed(int seed);
038
039 /**
040 * Sets the seed of the underlying random number generator using an
041 * <code>int</code> array seed.
042 * <p>Sequences of values generated starting with the same seeds
043 * should be identical.
044 * </p>
045 * @param seed the seed value
046 */
047 void setSeed(int[] seed);
048
049 /**
050 * Sets the seed of the underlying random number generator using a
051 * <code>long</code> seed.
052 * <p>Sequences of values generated starting with the same seeds
053 * should be identical.
054 * </p>
055 * @param seed the seed value
056 */
057 void setSeed(long seed);
058
059 /**
060 * Generates random bytes and places them into a user-supplied
061 * byte array. The number of random bytes produced is equal to
062 * the length of the byte array.
063 *
064 * @param bytes the non-null byte array in which to put the
065 * random bytes
066 */
067 void nextBytes(byte[] bytes);
068
069 /**
070 * Returns the next pseudorandom, uniformly distributed <code>int</code>
071 * value from this random number generator's sequence.
072 * All 2<font size="-1"><sup>32</sup></font> possible <tt>int</tt> values
073 * should be produced with (approximately) equal probability.
074 *
075 * @return the next pseudorandom, uniformly distributed <code>int</code>
076 * value from this random number generator's sequence
077 */
078 int nextInt();
079
080 /**
081 * Returns a pseudorandom, uniformly distributed <tt>int</tt> value
082 * between 0 (inclusive) and the specified value (exclusive), drawn from
083 * this random number generator's sequence.
084 *
085 * @param n the bound on the random number to be returned. Must be
086 * positive.
087 * @return a pseudorandom, uniformly distributed <tt>int</tt>
088 * value between 0 (inclusive) and n (exclusive).
089 * @throws IllegalArgumentException if n is not positive.
090 */
091 int nextInt(int n);
092
093 /**
094 * Returns the next pseudorandom, uniformly distributed <code>long</code>
095 * value from this random number generator's sequence. All
096 * 2<font size="-1"><sup>64</sup></font> possible <tt>long</tt> values
097 * should be produced with (approximately) equal probability.
098 *
099 * @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 }