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 singlelon
  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 distributedint
  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 3, Section
  35 3.2.1.)
  36
  37 If two instances ofRandomare created with the same seed, and the same sequence
  38 of method calls is made for each, they will generate and return identical
  39 sequences of numbers. In order to guarantee this property, particular
  40 algorithms are specified for the classRandom. Java implementations must use all
  41 the algorithms shown here for the classRandom, for the sake of absolute
  42 portability of Java code. However, subclasses of classRandomare 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 classRandomuse aprotectedutility method that on
  47 each invocation can supply up to 32 pseudorandomly generated bits.
  48
  49 Many applications will find the method (|java.lang.Math|) simpler to use.
  50
  51
  52
  53 *java.util.Random()*
  54
  55 public Random()
  56
  57 Creates a new random number generator. This constructor sets the seed of the
  58 random number generator to a value very likely to be distinct from any other
  59 invocation of this constructor.
  60
  61
  62 *java.util.Random(long)*
  63
  64 public Random(long seed)
  65
  66 Creates a new random number generator using a singlelongseed. The seed is the
  67 initial value of the internal state of the pseudorandom number generator which
  68 is maintained by method (|java.util.Random|) .
  69
  70 The invocationnew Random(seed)is equivalent to:
  71
  72 Random rnd = new Random(); rnd.setSeed(seed);
  73
  74     seed - the initial seed
  75
  76 *java.util.Random.next(int)*
  77
  78 protected int next(int bits)
  79
  80 Generates the next pseudorandom number. Subclasses should override this, as
  81 this is used by all other methods.
  82
  83 The general contract ofnextis that it returns anintvalue and if the
  84 argumentbitsis between1and32(inclusive), then that many low-order bits of the
  85 returned value will be (approximately) independently chosen bit values, each of
  86 which is (approximately) equally likely to be0or1. The methodnextis implemented
  87 by classRandomby atomically updating the seed to
  88
  89 (seed * 0x5DEECE66DL + 0xBL) & ((1L << 48) - 1)
  90
  91 and returning
  92
  93 (int)(seed >>> (48 - bits)).
  94
  95 This is a linear congruential pseudorandom number generator, as defined by D.
  96 H. Lehmer and described by Donald E. Knuth in The Art of Computer Programming,
  97 Volume 3: Seminumerical Algorithms, section 3.2.1.
  98
  99
 100     bits - random bits
 101
 102     Returns: the next pseudorandom value from this random number generator's sequence
 103
 104 *java.util.Random.nextBoolean()*
 105
 106 public boolean nextBoolean()
 107
 108 Returns the next pseudorandom, uniformly distributedbooleanvalue from this
 109 random number generator's sequence. The general contract ofnextBooleanis that
 110 onebooleanvalue is pseudorandomly generated and returned. The
 111 valuestrueandfalseare produced with (approximately) equal probability.
 112
 113 The methodnextBooleanis implemented by classRandomas if by:
 114
 115 public boolean nextBoolean() { return next(1) != 0; }
 116
 117
 118
 119     Returns: the next pseudorandom, uniformly distributed {@code boolean} value from this
 120              random number generator's sequence
 121
 122 *java.util.Random.nextBytes(byte[])*
 123
 124 public void nextBytes(byte[] bytes)
 125
 126 Generates random bytes and places them into a user-supplied byte array. The
 127 number of random bytes produced is equal to the length of the byte array.
 128
 129 The methodnextBytesis implemented by classRandomas if by:
 130
 131 public void nextBytes(byte[] bytes) { for (int i = 0; i 0; rnd >>= 8)
 132 bytes[i++] = (byte)rnd; }
 133
 134
 135     bytes - the byte array to fill with random bytes
 136
 137 *java.util.Random.nextDouble()*
 138
 139 public double nextDouble()
 140
 141 Returns the next pseudorandom, uniformly distributeddoublevalue
 142 between0.0and1.0from this random number generator's sequence.
 143
 144 The general contract ofnextDoubleis that onedoublevalue, chosen (approximately)
 145 uniformly from the range0.0d(inclusive) to1.0d(exclusive), is pseudorandomly
 146 generated and returned.
 147
 148 The methodnextDoubleis implemented by classRandomas if by:
 149
 150 public double nextDouble() { return (((long)next(26) << 27) + next(27)) /
 151 (double)(1L << 53); }
 152
 153 The hedge "approximately" is used in the foregoing description only because
 154 thenextmethod is only approximately an unbiased source of independently chosen
 155 bits. If it were a perfect source of randomly chosen bits, then the algorithm
 156 shown would choosedoublevalues from the stated range with perfect uniformity.
 157 [In early versions of Java, the result was incorrectly calculated as:
 158
 159 return (((long)next(27) << 27) + next(27)) / (double)(1L << 54);
 160
 161 This might seem to be equivalent, if not better, but in fact it introduced a
 162 large nonuniformity because of the bias in the rounding of floating-point
 163 numbers: it was three times as likely that the low-order bit of the significand
 164 would be 0 than that it would be 1! This nonuniformity probably doesn't matter
 165 much in practice, but we strive for perfection.]
 166
 167
 168
 169     Returns: the next pseudorandom, uniformly distributed {@code double} value between
 170              {@code 0.0} and {@code 1.0} from this random number generator's
 171              sequence
 172
 173 *java.util.Random.nextFloat()*
 174
 175 public float nextFloat()
 176
 177 Returns the next pseudorandom, uniformly distributedfloatvalue
 178 between0.0and1.0from this random number generator's sequence.
 179
 180 The general contract ofnextFloatis that onefloatvalue, chosen (approximately)
 181 uniformly from the range0.0f(inclusive) to1.0f(exclusive), is pseudorandomly
 182 generated and returned. All 224 possiblefloatvalues of the form mxwhere m is a
 183 positive integer less than 224 , are produced with (approximately) equal
 184 probability.
 185
 186 The methodnextFloatis implemented by classRandomas if by:
 187
 188 public float nextFloat() { return next(24) / ((float)(1 << 24)); }
 189
 190 The hedge "approximately" is used in the foregoing description only because the
 191 next method is only approximately an unbiased source of independently chosen
 192 bits. If it were a perfect source of randomly chosen bits, then the algorithm
 193 shown would choosefloatvalues from the stated range with perfect uniformity.
 194 [In early versions of Java, the result was incorrectly calculated as:
 195
 196 return next(30) / ((float)(1 << 30));
 197
 198 This might seem to be equivalent, if not better, but in fact it introduced a
 199 slight nonuniformity because of the bias in the rounding of floating-point
 200 numbers: it was slightly more likely that the low-order bit of the significand
 201 would be 0 than that it would be 1.]
 202
 203
 204
 205     Returns: the next pseudorandom, uniformly distributed {@code float} value between {@code
 206              0.0} and {@code 1.0} from this random number generator's sequence
 207
 208 *java.util.Random.nextGaussian()*
 209
 210 public synchronized double nextGaussian()
 211
 212 Returns the next pseudorandom, Gaussian ("normally") distributeddoublevalue
 213 with mean0.0and standard deviation1.0from this random number generator's
 214 sequence.
 215
 216 The general contract ofnextGaussianis that onedoublevalue, chosen from
 217 (approximately) the usual normal distribution with mean0.0and standard
 218 deviation1.0, is pseudorandomly generated and returned.
 219
 220 The methodnextGaussianis implemented by classRandomas if by a threadsafe
 221 version of the following:
 222
 223 private double nextNextGaussian; private boolean haveNextNextGaussian = false;
 224
 225 public double nextGaussian() { if (haveNextNextGaussian) { haveNextNextGaussian
 226 = false; return nextNextGaussian; } else { double v1, v2, s; do { v1 = 2 *
 227 nextDouble() - 1; // between -1.0 and 1.0 v2 = 2 * nextDouble() - 1; // between
 228 -1.0 and 1.0 s = v1 * v1 + v2 * v2; } while (s >= 1 || s == 0); double
 229 multiplier = StrictMath.sqrt(-2 * StrictMath.log(s)/s); nextNextGaussian = v2 *
 230 multiplier; haveNextNextGaussian = true; return v1 * multiplier; } }
 231
 232 This uses the polar method of G. E. P. Box, M. E. Muller, and G. Marsaglia, as
 233 described by Donald E. Knuth in The Art of Computer Programming, Volume 3:
 234 Seminumerical Algorithms, section 3.4.1, subsection C, algorithm P. Note that
 235 it generates two independent values at the cost of only one call
 236 toStrictMath.logand one call toStrictMath.sqrt.
 237
 238
 239
 240     Returns: the next pseudorandom, Gaussian ("normally") distributed {@code double} value
 241              with mean {@code 0.0} and standard deviation {@code 1.0} from this
 242              random number generator's sequence
 243
 244 *java.util.Random.nextInt()*
 245
 246 public int nextInt()
 247
 248 Returns the next pseudorandom, uniformly distributedintvalue from this random
 249 number generator's sequence. The general contract ofnextIntis that oneintvalue
 250 is pseudorandomly generated and returned. All 232 possibleintvalues are
 251 produced with (approximately) equal probability.
 252
 253 The methodnextIntis implemented by classRandomas if by:
 254
 255 public int nextInt() { return next(32); }
 256
 257
 258
 259     Returns: the next pseudorandom, uniformly distributed {@code int} value from this random
 260              number generator's sequence
 261
 262 *java.util.Random.nextInt(int)*
 263
 264 public int nextInt(int n)
 265
 266 Returns a pseudorandom, uniformly distributedintvalue between 0 (inclusive) and
 267 the specified value (exclusive), drawn from this random number generator's
 268 sequence. The general contract ofnextIntis that oneintvalue in the specified
 269 range is pseudorandomly generated and returned. Allnpossibleintvalues are
 270 produced with (approximately) equal probability. The methodnextInt(int n)is
 271 implemented by classRandomas if by:
 272
 273 public int nextInt(int n) { if (n > 31);
 274
 275 int bits, val; do { bits = next(31); val = bits % n; } while (bits - val +
 276 (n-1) < 0); return val; }
 277
 278 The hedge "approximately" is used in the foregoing description only because the
 279 next method is only approximately an unbiased source of independently chosen
 280 bits. If it were a perfect source of randomly chosen bits, then the algorithm
 281 shown would chooseintvalues from the stated range with perfect uniformity.
 282
 283 The algorithm is slightly tricky. It rejects values that would result in an
 284 uneven distribution (due to the fact that 2^31 is not divisible by n). The
 285 probability of a value being rejected depends on n. The worst case is n=2^30+1,
 286 for which the probability of a reject is 1/2, and the expected number of
 287 iterations before the loop terminates is 2.
 288
 289 The algorithm treats the case where n is a power of two specially: it returns
 290 the correct number of high-order bits from the underlying pseudo-random number
 291 generator. In the absence of special treatment, the correct number of low-order
 292 bits would be returned. Linear congruential pseudo-random number generators
 293 such as the one implemented by this class are known to have short periods in
 294 the sequence of values of their low-order bits. Thus, this special case greatly
 295 increases the length of the sequence of values returned by successive calls to
 296 this method if n is a small power of two.
 297
 298
 299     n - the bound on the random number to be returned. Must be positive.
 300
 301     Returns: the next pseudorandom, uniformly distributed {@code int} value between {@code
 302              0} (inclusive) and {@code n} (exclusive) from this random number
 303              generator's sequence
 304
 305 *java.util.Random.nextLong()*
 306
 307 public long nextLong()
 308
 309 Returns the next pseudorandom, uniformly distributedlongvalue from this random
 310 number generator's sequence. The general contract ofnextLongis that
 311 onelongvalue is pseudorandomly generated and returned.
 312
 313 The methodnextLongis implemented by classRandomas if by:
 314
 315 public long nextLong() { return ((long)next(32) << 32) + next(32); }
 316
 317 Because classRandomuses a seed with only 48 bits, this algorithm will not
 318 return all possiblelongvalues.
 319
 320
 321
 322     Returns: the next pseudorandom, uniformly distributed {@code long} value from this
 323              random number generator's sequence
 324
 325 *java.util.Random.setSeed(long)*
 326
 327 public synchronized void setSeed(long seed)
 328
 329 Sets the seed of this random number generator using a singlelongseed. The
 330 general contract ofsetSeedis that it alters the state of this random number
 331 generator object so as to be in exactly the same state as if it had just been
 332 created with the argumentseedas a seed. The methodsetSeedis implemented by
 333 classRandomby atomically updating the seed to
 334
 335 (seed ^ 0x5DEECE66DL) & ((1L << 48) - 1)
 336
 337 and clearing thehaveNextNextGaussianflag used by (|java.util.Random|) .
 338
 339 The implementation ofsetSeedby classRandomhappens to use only 48 bits of the
 340 given seed. In general, however, an overriding method may use all 64 bits of
 341 thelongargument as a seed value.
 342
 343
 344     seed - the initial seed
 345
 346