sample/java.util.Random.txt

   1 *java.util.Random* *Random* An instance of this class is used to generate a stre
   2
   3 public class Random
   4   extends    |java.lang.Object|
   5   implements |java.io.Serializable|
   6
   7 |java.util.Random_Description|
   8 |java.util.Random_Fields|
   9 |java.util.Random_Constructors|
  10 |java.util.Random_Methods|
  11
  12 ================================================================================
  13
  14 *java.util.Random_Constructors*
  15 |java.util.Random()|Creates a new random number generator.
  16 |java.util.Random(long)|Creates a new random number generator using a single
  17
  18 *java.util.Random_Methods*
  19 |java.util.Random.next(int)|Generates the next pseudorandom number.
  20 |java.util.Random.nextBoolean()|Returns the next pseudorandom, uniformly distri
  21 |java.util.Random.nextBytes(byte[])|Generates random bytes and places them into
  22 |java.util.Random.nextDouble()|Returns the next pseudorandom, uniformly distrib
  23 |java.util.Random.nextFloat()|Returns the next pseudorandom, uniformly distribu
  24 |java.util.Random.nextGaussian()|Returns the next pseudorandom, Gaussian ("norm
  25 |java.util.Random.nextInt()|Returns the next pseudorandom, uniformly distribute
  26 |java.util.Random.nextInt(int)|Returns a pseudorandom, uniformly distributed in
  27 |java.util.Random.nextLong()|Returns the next pseudorandom, uniformly distribut
  28 |java.util.Random.setSeed(long)|Sets the seed of this random number generator u
  29
  30 *java.util.Random_Description*
  31
  32 An instance of this class is used to generate a stream of pseudorandom numbers.
  33 The class uses a 48-bit seed, which is modified using a linear congruential
  34 formula. (See Donald Knuth, The Art of Computer Programming, Volume 2, Section
  35 3.2.1.)
  36
  37 If two instances of Random are created with the same seed, and the same
  38 sequence of method calls is made for each, they will generate and return
  39 identical sequences of numbers. In order to guarantee this property, particular
  40 algorithms are specified for the class Random. Java implementations must use
  41 all the algorithms shown here for the class Random, for the sake of absolute
  42 portability of Java code. However, subclasses of class Random are permitted to
  43 use other algorithms, so long as they adhere to the general contracts for all
  44 the methods.
  45
  46 The algorithms implemented by class Random use a protected utility method that
  47 on each invocation can supply up to 32 pseudorandomly generated bits.
  48
  49 Many applications will find the random method in class Math simpler to use.
  50
  51
  52 *java.util.Random()*
  53
  54 public Random()
  55
  56 Creates a new random number generator. This constructor sets the seed of the
  57 random number generator to a value very likely to be distinct from any other
  58 invocation of this constructor.
  59
  60
  61 *java.util.Random(long)*
  62
  63 public Random(long seed)
  64
  65 Creates a new random number generator using a single long seed:
  66
  67 public Random(long seed) { setSeed(seed); }
  68
  69 Used by method next to hold the state of the pseudorandom number generator.
  70
  71     seed - the initial seed.
  72
  73 *java.util.Random.next(int)*
  74
  75 protected int next(int bits)
  76
  77 Generates the next pseudorandom number. Subclass should override this, as this
  78 is used by all other methods. The general contract of next is that it returns
  79 an int value and if the argument bits is between 1 and 32 (inclusive), then
  80 that many low-order bits of the returned value will be (approximately)
  81 independently chosen bit values, each of which is (approximately) equally
  82 likely to be 0 or 1. The method next is implemented by class Random as follows:
  83
  84 synchronized protected int next(int bits) { seed = (seed * 0x5DEECE66DL + 0xBL)
  85 & ((1L >> (48 - bits)); }
  86
  87 This is a linear congruential pseudorandom number generator, as defined by D.
  88 H. Lehmer and described by Donald E. Knuth in The Art of Computer Programming,
  89 Volume 2: Seminumerical Algorithms, section 3.2.1.
  90
  91     bits - random bits
  92
  93     Returns: the next pseudorandom value from this random number generator's sequence.
  94 *java.util.Random.nextBoolean()*
  95
  96 public boolean nextBoolean()
  97
  98 Returns the next pseudorandom, uniformly distributed boolean value from this
  99 random number generator's sequence. The general contract of nextBoolean is that
 100 one boolean value is pseudorandomly generated and returned. The values true and
 101 false are produced with (approximately) equal probability. The method
 102 nextBoolean is implemented by class Random as follows:
 103
 104 public boolean nextBoolean() {return next(1) != 0;}
 105
 106
 107     Returns: the next pseudorandom, uniformly distributed boolean value from this random
 108              number generator's sequence.
 109 *java.util.Random.nextBytes(byte[])*
 110
 111 public void nextBytes(byte[] bytes)
 112
 113 Generates random bytes and places them into a user-supplied byte array. The
 114 number of random bytes produced is equal to the length of the byte array.
 115
 116     bytes - the non-null byte array in which to put the random bytes.
 117
 118 *java.util.Random.nextDouble()*
 119
 120 public double nextDouble()
 121
 122 Returns the next pseudorandom, uniformly distributed double value between 0.0
 123 and 1.0 from this random number generator's sequence. The general contract of
 124 nextDouble is that one double value, chosen (approximately) uniformly from the
 125 range 0.0d (inclusive) to 1.0d (exclusive), is pseudorandomly generated and
 126 returned. All 253 possible float values of the form mx2-53 , where m is a
 127 positive integer less than 253, are produced with (approximately) equal
 128 probability. The method nextDouble is implemented by class Random as follows:
 129
 130 public double nextDouble() { return (((long)next(26) The hedge "approximately"
 131 is used in the foregoing description only because the next method is only
 132 approximately an unbiased source of independently chosen bits. If it were a
 133 perfect source or randomly chosen bits, then the algorithm shown would choose
 134 double values from the stated range with perfect uniformity. [In early versions
 135 of Java, the result was incorrectly calculated as:
 136
 137 return (((long)next(27) This might seem to be equivalent, if not better, but in
 138 fact it introduced a large nonuniformity because of the bias in the rounding of
 139 floating-point numbers: it was three times as likely that the low-order bit of
 140 the significand would be 0 than that it would be 1! This nonuniformity probably
 141 doesn't matter much in practice, but we strive for perfection.]
 142
 143
 144     Returns: the next pseudorandom, uniformly distributed double value between 0.0 and 1.0
 145              from this random number generator's sequence.
 146 *java.util.Random.nextFloat()*
 147
 148 public float nextFloat()
 149
 150 Returns the next pseudorandom, uniformly distributed float value between 0.0
 151 and 1.0 from this random number generator's sequence. The general contract of
 152 nextFloat is that one float value, chosen (approximately) uniformly from the
 153 range 0.0f (inclusive) to 1.0f (exclusive), is pseudorandomly generated and
 154 returned. All 224 possible float values of the form mxwhere m is a positive
 155 integer less than 224 , are produced with (approximately) equal probability.
 156 The method nextFloat is implemented by class Random as follows:
 157
 158 public float nextFloat() { return next(24) / ((float)(1 The hedge
 159 "approximately" is used in the foregoing description only because the next
 160 method is only approximately an unbiased source of independently chosen bits.
 161 If it were a perfect source or randomly chosen bits, then the algorithm shown
 162 would choose float values from the stated range with perfect uniformity. [In
 163 early versions of Java, the result was incorrectly calculated as:
 164
 165 return next(30) / ((float)(1 This might seem to be equivalent, if not better,
 166 but in fact it introduced a slight nonuniformity because of the bias in the
 167 rounding of floating-point numbers: it was slightly more likely that the
 168 low-order bit of the significand would be 0 than that it would be 1.]
 169
 170
 171     Returns: the next pseudorandom, uniformly distributed float value between 0.0 and 1.0
 172              from this random number generator's sequence.
 173 *java.util.Random.nextGaussian()*
 174
 175 public synchronized double nextGaussian()
 176
 177 Returns the next pseudorandom, Gaussian ("normally") distributed double value
 178 with mean 0.0 and standard deviation 1.0 from this random number generator's
 179 sequence.
 180
 181 The general contract of nextGaussian is that one double value, chosen from
 182 (approximately) the usual normal distribution with mean 0.0 and standard
 183 deviation 1.0, is pseudorandomly generated and returned. The method
 184 nextGaussian is implemented by class Random as follows:
 185
 186 synchronized public double nextGaussian() { if (haveNextNextGaussian) {
 187 haveNextNextGaussian = false; return nextNextGaussian; } else { double v1, v2,
 188 s; do { v1 = 2 * nextDouble() - 1; // between -1.0 and 1.0 v2 = 2 *
 189 nextDouble() - 1; // between -1.0 and 1.0 s = v1 * v1 + v2 * v2; } while (s >=
 190 1 || s == 0); double multiplier = Math.sqrt(-2 * Math.log(s)/s);
 191 nextNextGaussian = v2 * multiplier; haveNextNextGaussian = true; return v1 *
 192 multiplier; } }
 193
 194 This uses the polar method of G. E. P. Box, M. E. Muller, and G. Marsaglia, as
 195 described by Donald E. Knuth in The Art of Computer Programming, Volume 2:
 196 Seminumerical Algorithms, section 3.4.1, subsection C, algorithm P. Note that
 197 it generates two independent values at the cost of only one call to Math.log
 198 and one call to Math.sqrt.
 199
 200
 201     Returns: the next pseudorandom, Gaussian ("normally") distributed double value with mean
 202              0.0 and standard deviation 1.0 from this random number generator's
 203              sequence.
 204 *java.util.Random.nextInt()*
 205
 206 public int nextInt()
 207
 208 Returns the next pseudorandom, uniformly distributed int value from this random
 209 number generator's sequence. The general contract of nextInt is that one int
 210 value is pseudorandomly generated and returned. All 232 possible int values are
 211 produced with (approximately) equal probability. The method nextInt is
 212 implemented by class Random as follows:
 213
 214 public int nextInt() { return next(32); }
 215
 216
 217     Returns: the next pseudorandom, uniformly distributed int value from this random number
 218              generator's sequence.
 219 *java.util.Random.nextInt(int)*
 220
 221 public int nextInt(int n)
 222
 223 Returns a pseudorandom, uniformly distributed int value between 0 (inclusive)
 224 and the specified value (exclusive), drawn from this random number generator's
 225 sequence. The general contract of nextInt is that one int value in the
 226 specified range is pseudorandomly generated and returned. All n possible int
 227 values are produced with (approximately) equal probability. The method
 228 nextInt(int n) is implemented by class Random as follows:
 229
 230 public int nextInt(int n) { if (n> 31);
 231
 232 int bits, val; do { bits = next(31); val = bits % n; } while(bits - val + (n-1)
 233
 234 The hedge "approximately" is used in the foregoing description only because the
 235 next method is only approximately an unbiased source of independently chosen
 236 bits. If it were a perfect source of randomly chosen bits, then the algorithm
 237 shown would choose int values from the stated range with perfect uniformity.
 238
 239 The algorithm is slightly tricky. It rejects values that would result in an
 240 uneven distribution (due to the fact that 2^31 is not divisible by n). The
 241 probability of a value being rejected depends on n. The worst case is n=2^30+1,
 242 for which the probability of a reject is 1/2, and the expected number of
 243 iterations before the loop terminates is 2.
 244
 245 The algorithm treats the case where n is a power of two specially: it returns
 246 the correct number of high-order bits from the underlying pseudo-random number
 247 generator. In the absence of special treatment, the correct number of low-order
 248 bits would be returned. Linear congruential pseudo-random number generators
 249 such as the one implemented by this class are known to have short periods in
 250 the sequence of values of their low-order bits. Thus, this special case greatly
 251 increases the length of the sequence of values returned by successive calls to
 252 this method if n is a small power of two.
 253
 254     n - the bound on the random number to be returned. Must be positive.
 255
 256     Returns: a pseudorandom, uniformly distributed int value between 0 (inclusive) and n
 257              (exclusive).
 258 *java.util.Random.nextLong()*
 259
 260 public long nextLong()
 261
 262 Returns the next pseudorandom, uniformly distributed long value from this
 263 random number generator's sequence. The general contract of nextLong is that
 264 one long value is pseudorandomly generated and returned. All 264 possible long
 265 values are produced with (approximately) equal probability. The method nextLong
 266 is implemented by class Random as follows:
 267
 268 public long nextLong() { return ((long)next(32)
 269
 270
 271     Returns: the next pseudorandom, uniformly distributed long value from this random number
 272              generator's sequence.
 273 *java.util.Random.setSeed(long)*
 274
 275 public synchronized void setSeed(long seed)
 276
 277 Sets the seed of this random number generator using a single long seed. The
 278 general contract of setSeed is that it alters the state of this random number
 279 generator object so as to be in exactly the same state as if it had just been
 280 created with the argument seed as a seed. The method setSeed is implemented by
 281 class Random as follows:
 282
 283 synchronized public void setSeed(long seed) { this.seed = (seed ^ 0x5DEECE66DL)
 284 & ((1L The implementation of setSeed by class Random happens to use only 48
 285 bits of the given seed. In general, however, an overriding method may use all
 286 64 bits of the long argument as a seed value.
 287
 288 Note: Although the seed value is an AtomicLong, this method must still be
 289 synchronized to ensure correct semantics of haveNextNextGaussian.
 290
 291     seed - the initial seed.
 292
 293