1 /*
2 * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.util;
27 import java.io.*;
28 import java.util.concurrent.atomic.AtomicLong;
29 import java.util.function.DoubleConsumer;
30 import java.util.function.IntConsumer;
31 import java.util.function.LongConsumer;
32 import java.util.stream.DoubleStream;
33 import java.util.stream.IntStream;
34 import java.util.stream.LongStream;
35 import java.util.stream.StreamSupport;
36
37 import jdk.internal.misc.Unsafe;
38
39 /**
40 * An instance of this class is used to generate a stream of
41 * pseudorandom numbers. The class uses a 48-bit seed, which is
42 * modified using a linear congruential formula. (See Donald Knuth,
43 * <i>The Art of Computer Programming, Volume 2</i>, Section 3.2.1.)
44 * <p>
45 * If two instances of {@code Random} are created with the same
46 * seed, and the same sequence of method calls is made for each, they
47 * will generate and return identical sequences of numbers. In order to
48 * guarantee this property, particular algorithms are specified for the
49 * class {@code Random}. Java implementations must use all the algorithms
50 * shown here for the class {@code Random}, for the sake of absolute
51 * portability of Java code. However, subclasses of class {@code Random}
52 * are permitted to use other algorithms, so long as they adhere to the
53 * general contracts for all the methods.
54 * <p>
55 * The algorithms implemented by class {@code Random} use a
56 * {@code protected} utility method that on each invocation can supply
57 * up to 32 pseudorandomly generated bits.
58 * <p>
59 * Many applications will find the method {@link Math#random} simpler to use.
60 *
61 * <p>Instances of {@code java.util.Random} are threadsafe.
62 * However, the concurrent use of the same {@code java.util.Random}
63 * instance across threads may encounter contention and consequent
64 * poor performance. Consider instead using
65 * {@link java.util.concurrent.ThreadLocalRandom} in multithreaded
66 * designs.
67 *
68 * <p>Instances of {@code java.util.Random} are not cryptographically
69 * secure. Consider instead using {@link java.security.SecureRandom} to
70 * get a cryptographically secure pseudo-random number generator for use
71 * by security-sensitive applications.
72 *
73 * @author Frank Yellin
74 * @since 1.0
75 */
76 public
77 class Random implements java.io.Serializable {
78 /** use serialVersionUID from JDK 1.1 for interoperability */
79 static final long serialVersionUID = 3905348978240129619L;
80
81 /**
82 * The internal state associated with this pseudorandom number generator.
83 * (The specs for the methods in this class describe the ongoing
84 * computation of this value.)
85 */
86 private final AtomicLong seed;
87
88 private static final long multiplier = 0x5DEECE66DL;
89 private static final long addend = 0xBL;
90 private static final long mask = (1L << 48) - 1;
91
92 private static final double DOUBLE_UNIT = 0x1.0p-53; // 1.0 / (1L << 53)
93
94 // IllegalArgumentException messages
95 static final String BadBound = "bound must be positive";
96 static final String BadRange = "bound must be greater than origin";
97 static final String BadSize = "size must be non-negative";
98
99 /**
100 * Creates a new random number generator. This constructor sets
101 * the seed of the random number generator to a value very likely
102 * to be distinct from any other invocation of this constructor.
103 */
104 public Random() {
105 this(seedUniquifier() ^ System.nanoTime());
106 }
107
108 private static long seedUniquifier() {
109 // L'Ecuyer, "Tables of Linear Congruential Generators of
110 // Different Sizes and Good Lattice Structure", 1999
111 for (;;) {
112 long current = seedUniquifier.get();
113 long next = current * 1181783497276652981L;
114 if (seedUniquifier.compareAndSet(current, next))
115 return next;
116 }
117 }
118
119 private static final AtomicLong seedUniquifier
120 = new AtomicLong(8682522807148012L);
121
122 /**
123 * Creates a new random number generator using a single {@code long} seed.
124 * The seed is the initial value of the internal state of the pseudorandom
125 * number generator which is maintained by method {@link #next}.
126 *
127 * <p>The invocation {@code new Random(seed)} is equivalent to:
128 * <pre> {@code
129 * Random rnd = new Random();
130 * rnd.setSeed(seed);}</pre>
131 *
132 * @param seed the initial seed
133 * @see #setSeed(long)
134 */
135 public Random(long seed) {
136 if (getClass() == Random.class)
137 this.seed = new AtomicLong(initialScramble(seed));
138 else {
139 // subclass might have overriden setSeed
140 this.seed = new AtomicLong();
141 setSeed(seed);
142 }
143 }
144
145 private static long initialScramble(long seed) {
146 return (seed ^ multiplier) & mask;
147 }
148
149 /**
150 * Sets the seed of this random number generator using a single
151 * {@code long} seed. The general contract of {@code setSeed} is
152 * that it alters the state of this random number generator object
153 * so as to be in exactly the same state as if it had just been
154 * created with the argument {@code seed} as a seed. The method
155 * {@code setSeed} is implemented by class {@code Random} by
156 * atomically updating the seed to
157 * <pre>{@code (seed ^ 0x5DEECE66DL) & ((1L << 48) - 1)}</pre>
158 * and clearing the {@code haveNextNextGaussian} flag used by {@link
159 * #nextGaussian}.
160 *
161 * <p>The implementation of {@code setSeed} by class {@code Random}
162 * happens to use only 48 bits of the given seed. In general, however,
163 * an overriding method may use all 64 bits of the {@code long}
164 * argument as a seed value.
165 *
166 * @param seed the initial seed
167 */
168 public synchronized void setSeed(long seed) {
169 this.seed.set(initialScramble(seed));
170 haveNextNextGaussian = false;
171 }
172
173 /**
174 * Generates the next pseudorandom number. Subclasses should
175 * override this, as this is used by all other methods.
176 *
177 * <p>The general contract of {@code next} is that it returns an
178 * {@code int} value and if the argument {@code bits} is between
179 * {@code 1} and {@code 32} (inclusive), then that many low-order
180 * bits of the returned value will be (approximately) independently
181 * chosen bit values, each of which is (approximately) equally
182 * likely to be {@code 0} or {@code 1}. The method {@code next} is
183 * implemented by class {@code Random} by atomically updating the seed to
184 * <pre>{@code (seed * 0x5DEECE66DL + 0xBL) & ((1L << 48) - 1)}</pre>
185 * and returning
186 * <pre>{@code (int)(seed >>> (48 - bits))}.</pre>
187 *
188 * This is a linear congruential pseudorandom number generator, as
189 * defined by D. H. Lehmer and described by Donald E. Knuth in
190 * <i>The Art of Computer Programming,</i> Volume 2:
191 * <i>Seminumerical Algorithms</i>, section 3.2.1.
192 *
193 * @param bits random bits
194 * @return the next pseudorandom value from this random number
195 * generator's sequence
196 * @since 1.1
197 */
198 protected int next(int bits) {
199 long oldseed, nextseed;
200 AtomicLong seed = this.seed;
201 do {
202 oldseed = seed.get();
203 nextseed = (oldseed * multiplier + addend) & mask;
204 } while (!seed.compareAndSet(oldseed, nextseed));
205 return (int)(nextseed >>> (48 - bits));
206 }
207
208 /**
209 * Generates random bytes and places them into a user-supplied
210 * byte array. The number of random bytes produced is equal to
211 * the length of the byte array.
212 *
213 * <p>The method {@code nextBytes} is implemented by class {@code Random}
214 * as if by:
215 * <pre> {@code
216 * public void nextBytes(byte[] bytes) {
217 * for (int i = 0; i < bytes.length; )
218 * for (int rnd = nextInt(), n = Math.min(bytes.length - i, 4);
219 * n-- > 0; rnd >>= 8)
220 * bytes[i++] = (byte)rnd;
221 * }}</pre>
222 *
223 * @param bytes the byte array to fill with random bytes
224 * @throws NullPointerException if the byte array is null
225 * @since 1.1
226 */
227 public void nextBytes(byte[] bytes) {
228 for (int i = 0, len = bytes.length; i < len; )
229 for (int rnd = nextInt(),
230 n = Math.min(len - i, Integer.SIZE/Byte.SIZE);
231 n-- > 0; rnd >>= Byte.SIZE)
232 bytes[i++] = (byte)rnd;
233 }
234
235 /**
236 * The form of nextLong used by LongStream Spliterators. If
237 * origin is greater than bound, acts as unbounded form of
238 * nextLong, else as bounded form.
239 *
240 * @param origin the least value, unless greater than bound
241 * @param bound the upper bound (exclusive), must not equal origin
242 * @return a pseudorandom value
243 */
244 final long internalNextLong(long origin, long bound) {
245 long r = nextLong();
246 if (origin < bound) {
247 long n = bound - origin, m = n - 1;
248 if ((n & m) == 0L) // power of two
249 r = (r & m) + origin;
250 else if (n > 0L) { // reject over-represented candidates
251 for (long u = r >>> 1; // ensure nonnegative
252 u + m - (r = u % n) < 0L; // rejection check
253 u = nextLong() >>> 1) // retry
254 ;
255 r += origin;
256 }
257 else { // range not representable as long
258 while (r < origin || r >= bound)
259 r = nextLong();
260 }
261 }
262 return r;
263 }
264
265 /**
266 * The form of nextInt used by IntStream Spliterators.
267 * For the unbounded case: uses nextInt().
268 * For the bounded case with representable range: uses nextInt(int bound)
269 * For the bounded case with unrepresentable range: uses nextInt()
270 *
271 * @param origin the least value, unless greater than bound
272 * @param bound the upper bound (exclusive), must not equal origin
273 * @return a pseudorandom value
274 */
275 final int internalNextInt(int origin, int bound) {
276 if (origin < bound) {
277 int n = bound - origin;
278 if (n > 0) {
279 return nextInt(n) + origin;
280 }
281 else { // range not representable as int
282 int r;
283 do {
284 r = nextInt();
285 } while (r < origin || r >= bound);
286 return r;
287 }
288 }
289 else {
290 return nextInt();
291 }
292 }
293
294 /**
295 * The form of nextDouble used by DoubleStream Spliterators.
296 *
297 * @param origin the least value, unless greater than bound
298 * @param bound the upper bound (exclusive), must not equal origin
299 * @return a pseudorandom value
300 */
301 final double internalNextDouble(double origin, double bound) {
302 double r = nextDouble();
303 if (origin < bound) {
304 r = r * (bound - origin) + origin;
305 if (r >= bound) // correct for rounding
306 r = Double.longBitsToDouble(Double.doubleToLongBits(bound) - 1);
307 }
308 return r;
309 }
310
311 /**
312 * Returns the next pseudorandom, uniformly distributed {@code int}
313 * value from this random number generator's sequence. The general
314 * contract of {@code nextInt} is that one {@code int} value is
315 * pseudorandomly generated and returned. All 2<sup>32</sup> possible
316 * {@code int} values are produced with (approximately) equal probability.
317 *
318 * <p>The method {@code nextInt} is implemented by class {@code Random}
319 * as if by:
320 * <pre> {@code
321 * public int nextInt() {
322 * return next(32);
323 * }}</pre>
324 *
325 * @return the next pseudorandom, uniformly distributed {@code int}
326 * value from this random number generator's sequence
327 */
328 public int nextInt() {
329 return next(32);
330 }
331
332 /**
333 * Returns a pseudorandom, uniformly distributed {@code int} value
334 * between 0 (inclusive) and the specified value (exclusive), drawn from
335 * this random number generator's sequence. The general contract of
336 * {@code nextInt} is that one {@code int} value in the specified range
337 * is pseudorandomly generated and returned. All {@code bound} possible
338 * {@code int} values are produced with (approximately) equal
339 * probability. The method {@code nextInt(int bound)} is implemented by
340 * class {@code Random} as if by:
341 * <pre> {@code
342 * public int nextInt(int bound) {
343 * if (bound <= 0)
344 * throw new IllegalArgumentException("bound must be positive");
345 *
346 * if ((bound & -bound) == bound) // i.e., bound is a power of 2
347 * return (int)((bound * (long)next(31)) >> 31);
348 *
349 * int bits, val;
350 * do {
351 * bits = next(31);
352 * val = bits % bound;
353 * } while (bits - val + (bound-1) < 0);
354 * return val;
355 * }}</pre>
356 *
357 * <p>The hedge "approximately" is used in the foregoing description only
358 * because the next method is only approximately an unbiased source of
359 * independently chosen bits. If it were a perfect source of randomly
360 * chosen bits, then the algorithm shown would choose {@code int}
361 * values from the stated range with perfect uniformity.
362 * <p>
363 * The algorithm is slightly tricky. It rejects values that would result
364 * in an uneven distribution (due to the fact that 2^31 is not divisible
365 * by n). The probability of a value being rejected depends on n. The
366 * worst case is n=2^30+1, for which the probability of a reject is 1/2,
367 * and the expected number of iterations before the loop terminates is 2.
368 * <p>
369 * The algorithm treats the case where n is a power of two specially: it
370 * returns the correct number of high-order bits from the underlying
371 * pseudo-random number generator. In the absence of special treatment,
372 * the correct number of <i>low-order</i> bits would be returned. Linear
373 * congruential pseudo-random number generators such as the one
374 * implemented by this class are known to have short periods in the
375 * sequence of values of their low-order bits. Thus, this special case
376 * greatly increases the length of the sequence of values returned by
377 * successive calls to this method if n is a small power of two.
378 *
379 * @param bound the upper bound (exclusive). Must be positive.
380 * @return the next pseudorandom, uniformly distributed {@code int}
381 * value between zero (inclusive) and {@code bound} (exclusive)
382 * from this random number generator's sequence
383 * @throws IllegalArgumentException if bound is not positive
384 * @since 1.2
385 */
386 public int nextInt(int bound) {
387 if (bound <= 0)
388 throw new IllegalArgumentException(BadBound);
389
390 int r = next(31);
391 int m = bound - 1;
392 if ((bound & m) == 0) // i.e., bound is a power of 2
393 r = (int)((bound * (long)r) >> 31);
394 else {
395 for (int u = r;
396 u - (r = u % bound) + m < 0;
397 u = next(31))
398 ;
399 }
400 return r;
401 }
402
403 /**
404 * Returns the next pseudorandom, uniformly distributed {@code long}
405 * value from this random number generator's sequence. The general
406 * contract of {@code nextLong} is that one {@code long} value is
407 * pseudorandomly generated and returned.
408 *
409 * <p>The method {@code nextLong} is implemented by class {@code Random}
410 * as if by:
411 * <pre> {@code
412 * public long nextLong() {
413 * return ((long)next(32) << 32) + next(32);
414 * }}</pre>
415 *
416 * Because class {@code Random} uses a seed with only 48 bits,
417 * this algorithm will not return all possible {@code long} values.
418 *
419 * @return the next pseudorandom, uniformly distributed {@code long}
420 * value from this random number generator's sequence
421 */
422 public long nextLong() {
423 // it's okay that the bottom word remains signed.
424 return ((long)(next(32)) << 32) + next(32);
425 }
426
427 /**
428 * Returns the next pseudorandom, uniformly distributed
429 * {@code boolean} value from this random number generator's
430 * sequence. The general contract of {@code nextBoolean} is that one
431 * {@code boolean} value is pseudorandomly generated and returned. The
432 * values {@code true} and {@code false} are produced with
433 * (approximately) equal probability.
434 *
435 * <p>The method {@code nextBoolean} is implemented by class {@code Random}
436 * as if by:
437 * <pre> {@code
438 * public boolean nextBoolean() {
439 * return next(1) != 0;
440 * }}</pre>
441 *
442 * @return the next pseudorandom, uniformly distributed
443 * {@code boolean} value from this random number generator's
444 * sequence
445 * @since 1.2
446 */
447 public boolean nextBoolean() {
448 return next(1) != 0;
449 }
450
451 /**
452 * Returns the next pseudorandom, uniformly distributed {@code float}
453 * value between {@code 0.0} and {@code 1.0} from this random
454 * number generator's sequence.
455 *
456 * <p>The general contract of {@code nextFloat} is that one
457 * {@code float} value, chosen (approximately) uniformly from the
458 * range {@code 0.0f} (inclusive) to {@code 1.0f} (exclusive), is
459 * pseudorandomly generated and returned. All 2<sup>24</sup> possible
460 * {@code float} values of the form <i>m x </i>2<sup>-24</sup>,
461 * where <i>m</i> is a positive integer less than 2<sup>24</sup>, are
462 * produced with (approximately) equal probability.
463 *
464 * <p>The method {@code nextFloat} is implemented by class {@code Random}
465 * as if by:
466 * <pre> {@code
467 * public float nextFloat() {
468 * return next(24) / ((float)(1 << 24));
469 * }}</pre>
470 *
471 * <p>The hedge "approximately" is used in the foregoing description only
472 * because the next method is only approximately an unbiased source of
473 * independently chosen bits. If it were a perfect source of randomly
474 * chosen bits, then the algorithm shown would choose {@code float}
475 * values from the stated range with perfect uniformity.<p>
476 * [In early versions of Java, the result was incorrectly calculated as:
477 * <pre> {@code
478 * return next(30) / ((float)(1 << 30));}</pre>
479 * This might seem to be equivalent, if not better, but in fact it
480 * introduced a slight nonuniformity because of the bias in the rounding
481 * of floating-point numbers: it was slightly more likely that the
482 * low-order bit of the significand would be 0 than that it would be 1.]
483 *
484 * @return the next pseudorandom, uniformly distributed {@code float}
485 * value between {@code 0.0} and {@code 1.0} from this
486 * random number generator's sequence
487 */
488 public float nextFloat() {
489 return next(24) / ((float)(1 << 24));
490 }
491
492 /**
493 * Returns the next pseudorandom, uniformly distributed
494 * {@code double} value between {@code 0.0} and
495 * {@code 1.0} from this random number generator's sequence.
496 *
497 * <p>The general contract of {@code nextDouble} is that one
498 * {@code double} value, chosen (approximately) uniformly from the
499 * range {@code 0.0d} (inclusive) to {@code 1.0d} (exclusive), is
500 * pseudorandomly generated and returned.
501 *
502 * <p>The method {@code nextDouble} is implemented by class {@code Random}
503 * as if by:
504 * <pre> {@code
505 * public double nextDouble() {
506 * return (((long)next(26) << 27) + next(27))
507 * / (double)(1L << 53);
508 * }}</pre>
509 *
510 * <p>The hedge "approximately" is used in the foregoing description only
511 * because the {@code next} method is only approximately an unbiased
512 * source of independently chosen bits. If it were a perfect source of
513 * randomly chosen bits, then the algorithm shown would choose
514 * {@code double} values from the stated range with perfect uniformity.
515 * <p>[In early versions of Java, the result was incorrectly calculated as:
516 * <pre> {@code
517 * return (((long)next(27) << 27) + next(27))
518 * / (double)(1L << 54);}</pre>
519 * This might seem to be equivalent, if not better, but in fact it
520 * introduced a large nonuniformity because of the bias in the rounding
521 * of floating-point numbers: it was three times as likely that the
522 * low-order bit of the significand would be 0 than that it would be 1!
523 * This nonuniformity probably doesn't matter much in practice, but we
524 * strive for perfection.]
525 *
526 * @return the next pseudorandom, uniformly distributed {@code double}
527 * value between {@code 0.0} and {@code 1.0} from this
528 * random number generator's sequence
529 * @see Math#random
530 */
531 public double nextDouble() {
532 return (((long)(next(26)) << 27) + next(27)) * DOUBLE_UNIT;
533 }
534
535 private double nextNextGaussian;
536 private boolean haveNextNextGaussian = false;
537
538 /**
539 * Returns the next pseudorandom, Gaussian ("normally") distributed
540 * {@code double} value with mean {@code 0.0} and standard
541 * deviation {@code 1.0} from this random number generator's sequence.
542 * <p>
543 * The general contract of {@code nextGaussian} is that one
544 * {@code double} value, chosen from (approximately) the usual
545 * normal distribution with mean {@code 0.0} and standard deviation
546 * {@code 1.0}, is pseudorandomly generated and returned.
547 *
548 * <p>The method {@code nextGaussian} is implemented by class
549 * {@code Random} as if by a threadsafe version of the following:
550 * <pre> {@code
551 * private double nextNextGaussian;
552 * private boolean haveNextNextGaussian = false;
553 *
554 * public double nextGaussian() {
555 * if (haveNextNextGaussian) {
556 * haveNextNextGaussian = false;
557 * return nextNextGaussian;
558 * } else {
559 * double v1, v2, s;
560 * do {
561 * v1 = 2 * nextDouble() - 1; // between -1.0 and 1.0
562 * v2 = 2 * nextDouble() - 1; // between -1.0 and 1.0
563 * s = v1 * v1 + v2 * v2;
564 * } while (s >= 1 || s == 0);
565 * double multiplier = StrictMath.sqrt(-2 * StrictMath.log(s)/s);
566 * nextNextGaussian = v2 * multiplier;
567 * haveNextNextGaussian = true;
568 * return v1 * multiplier;
569 * }
570 * }}</pre>
571 * This uses the <i>polar method</i> of G. E. P. Box, M. E. Muller, and
572 * G. Marsaglia, as described by Donald E. Knuth in <i>The Art of
573 * Computer Programming</i>, Volume 2: <i>Seminumerical Algorithms</i>,
574 * section 3.4.1, subsection C, algorithm P. Note that it generates two
575 * independent values at the cost of only one call to {@code StrictMath.log}
576 * and one call to {@code StrictMath.sqrt}.
577 *
578 * @return the next pseudorandom, Gaussian ("normally") distributed
579 * {@code double} value with mean {@code 0.0} and
580 * standard deviation {@code 1.0} from this random number
581 * generator's sequence
582 */
583 public synchronized double nextGaussian() {
584 // See Knuth, ACP, Section 3.4.1 Algorithm C.
585 if (haveNextNextGaussian) {
586 haveNextNextGaussian = false;
587 return nextNextGaussian;
588 } else {
589 double v1, v2, s;
590 do {
591 v1 = 2 * nextDouble() - 1; // between -1 and 1
592 v2 = 2 * nextDouble() - 1; // between -1 and 1
593 s = v1 * v1 + v2 * v2;
594 } while (s >= 1 || s == 0);
595 double multiplier = StrictMath.sqrt(-2 * StrictMath.log(s)/s);
596 nextNextGaussian = v2 * multiplier;
597 haveNextNextGaussian = true;
598 return v1 * multiplier;
599 }
600 }
601
602 // stream methods, coded in a way intended to better isolate for
603 // maintenance purposes the small differences across forms.
604
605 /**
606 * Returns a stream producing the given {@code streamSize} number of
607 * pseudorandom {@code int} values.
608 *
609 * <p>A pseudorandom {@code int} value is generated as if it's the result of
610 * calling the method {@link #nextInt()}.
611 *
612 * @param streamSize the number of values to generate
613 * @return a stream of pseudorandom {@code int} values
614 * @throws IllegalArgumentException if {@code streamSize} is
615 * less than zero
616 * @since 1.8
617 */
618 public IntStream ints(long streamSize) {
619 if (streamSize < 0L)
620 throw new IllegalArgumentException(BadSize);
621 return StreamSupport.intStream
622 (new RandomIntsSpliterator
623 (this, 0L, streamSize, Integer.MAX_VALUE, 0),
624 false);
625 }
626
627 /**
628 * Returns an effectively unlimited stream of pseudorandom {@code int}
629 * values.
630 *
631 * <p>A pseudorandom {@code int} value is generated as if it's the result of
632 * calling the method {@link #nextInt()}.
633 *
634 * @implNote This method is implemented to be equivalent to {@code
635 * ints(Long.MAX_VALUE)}.
636 *
637 * @return a stream of pseudorandom {@code int} values
638 * @since 1.8
639 */
640 public IntStream ints() {
641 return StreamSupport.intStream
642 (new RandomIntsSpliterator
643 (this, 0L, Long.MAX_VALUE, Integer.MAX_VALUE, 0),
644 false);
645 }
646
647 /**
648 * Returns a stream producing the given {@code streamSize} number
649 * of pseudorandom {@code int} values, each conforming to the given
650 * origin (inclusive) and bound (exclusive).
651 *
652 * <p>A pseudorandom {@code int} value is generated as if it's the result of
653 * calling the following method with the origin and bound:
654 * <pre> {@code
655 * int nextInt(int origin, int bound) {
656 * int n = bound - origin;
657 * if (n > 0) {
658 * return nextInt(n) + origin;
659 * }
660 * else { // range not representable as int
661 * int r;
662 * do {
663 * r = nextInt();
664 * } while (r < origin || r >= bound);
665 * return r;
666 * }
667 * }}</pre>
668 *
669 * @param streamSize the number of values to generate
670 * @param randomNumberOrigin the origin (inclusive) of each random value
671 * @param randomNumberBound the bound (exclusive) of each random value
672 * @return a stream of pseudorandom {@code int} values,
673 * each with the given origin (inclusive) and bound (exclusive)
674 * @throws IllegalArgumentException if {@code streamSize} is
675 * less than zero, or {@code randomNumberOrigin}
676 * is greater than or equal to {@code randomNumberBound}
677 * @since 1.8
678 */
679 public IntStream ints(long streamSize, int randomNumberOrigin,
680 int randomNumberBound) {
681 if (streamSize < 0L)
682 throw new IllegalArgumentException(BadSize);
683 if (randomNumberOrigin >= randomNumberBound)
684 throw new IllegalArgumentException(BadRange);
685 return StreamSupport.intStream
686 (new RandomIntsSpliterator
687 (this, 0L, streamSize, randomNumberOrigin, randomNumberBound),
688 false);
689 }
690
691 /**
692 * Returns an effectively unlimited stream of pseudorandom {@code
693 * int} values, each conforming to the given origin (inclusive) and bound
694 * (exclusive).
695 *
696 * <p>A pseudorandom {@code int} value is generated as if it's the result of
697 * calling the following method with the origin and bound:
698 * <pre> {@code
699 * int nextInt(int origin, int bound) {
700 * int n = bound - origin;
701 * if (n > 0) {
702 * return nextInt(n) + origin;
703 * }
704 * else { // range not representable as int
705 * int r;
706 * do {
707 * r = nextInt();
708 * } while (r < origin || r >= bound);
709 * return r;
710 * }
711 * }}</pre>
712 *
713 * @implNote This method is implemented to be equivalent to {@code
714 * ints(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.
715 *
716 * @param randomNumberOrigin the origin (inclusive) of each random value
717 * @param randomNumberBound the bound (exclusive) of each random value
718 * @return a stream of pseudorandom {@code int} values,
719 * each with the given origin (inclusive) and bound (exclusive)
720 * @throws IllegalArgumentException if {@code randomNumberOrigin}
721 * is greater than or equal to {@code randomNumberBound}
722 * @since 1.8
723 */
724 public IntStream ints(int randomNumberOrigin, int randomNumberBound) {
725 if (randomNumberOrigin >= randomNumberBound)
726 throw new IllegalArgumentException(BadRange);
727 return StreamSupport.intStream
728 (new RandomIntsSpliterator
729 (this, 0L, Long.MAX_VALUE, randomNumberOrigin, randomNumberBound),
730 false);
731 }
732
733 /**
734 * Returns a stream producing the given {@code streamSize} number of
735 * pseudorandom {@code long} values.
736 *
737 * <p>A pseudorandom {@code long} value is generated as if it's the result
738 * of calling the method {@link #nextLong()}.
739 *
740 * @param streamSize the number of values to generate
741 * @return a stream of pseudorandom {@code long} values
742 * @throws IllegalArgumentException if {@code streamSize} is
743 * less than zero
744 * @since 1.8
745 */
746 public LongStream longs(long streamSize) {
747 if (streamSize < 0L)
748 throw new IllegalArgumentException(BadSize);
749 return StreamSupport.longStream
750 (new RandomLongsSpliterator
751 (this, 0L, streamSize, Long.MAX_VALUE, 0L),
752 false);
753 }
754
755 /**
756 * Returns an effectively unlimited stream of pseudorandom {@code long}
757 * values.
758 *
759 * <p>A pseudorandom {@code long} value is generated as if it's the result
760 * of calling the method {@link #nextLong()}.
761 *
762 * @implNote This method is implemented to be equivalent to {@code
763 * longs(Long.MAX_VALUE)}.
764 *
765 * @return a stream of pseudorandom {@code long} values
766 * @since 1.8
767 */
768 public LongStream longs() {
769 return StreamSupport.longStream
770 (new RandomLongsSpliterator
771 (this, 0L, Long.MAX_VALUE, Long.MAX_VALUE, 0L),
772 false);
773 }
774
775 /**
776 * Returns a stream producing the given {@code streamSize} number of
777 * pseudorandom {@code long}, each conforming to the given origin
778 * (inclusive) and bound (exclusive).
779 *
780 * <p>A pseudorandom {@code long} value is generated as if it's the result
781 * of calling the following method with the origin and bound:
782 * <pre> {@code
783 * long nextLong(long origin, long bound) {
784 * long r = nextLong();
785 * long n = bound - origin, m = n - 1;
786 * if ((n & m) == 0L) // power of two
787 * r = (r & m) + origin;
788 * else if (n > 0L) { // reject over-represented candidates
789 * for (long u = r >>> 1; // ensure nonnegative
790 * u + m - (r = u % n) < 0L; // rejection check
791 * u = nextLong() >>> 1) // retry
792 * ;
793 * r += origin;
794 * }
795 * else { // range not representable as long
796 * while (r < origin || r >= bound)
797 * r = nextLong();
798 * }
799 * return r;
800 * }}</pre>
801 *
802 * @param streamSize the number of values to generate
803 * @param randomNumberOrigin the origin (inclusive) of each random value
804 * @param randomNumberBound the bound (exclusive) of each random value
805 * @return a stream of pseudorandom {@code long} values,
806 * each with the given origin (inclusive) and bound (exclusive)
807 * @throws IllegalArgumentException if {@code streamSize} is
808 * less than zero, or {@code randomNumberOrigin}
809 * is greater than or equal to {@code randomNumberBound}
810 * @since 1.8
811 */
812 public LongStream longs(long streamSize, long randomNumberOrigin,
813 long randomNumberBound) {
814 if (streamSize < 0L)
815 throw new IllegalArgumentException(BadSize);
816 if (randomNumberOrigin >= randomNumberBound)
817 throw new IllegalArgumentException(BadRange);
818 return StreamSupport.longStream
819 (new RandomLongsSpliterator
820 (this, 0L, streamSize, randomNumberOrigin, randomNumberBound),
821 false);
822 }
823
824 /**
825 * Returns an effectively unlimited stream of pseudorandom {@code
826 * long} values, each conforming to the given origin (inclusive) and bound
827 * (exclusive).
828 *
829 * <p>A pseudorandom {@code long} value is generated as if it's the result
830 * of calling the following method with the origin and bound:
831 * <pre> {@code
832 * long nextLong(long origin, long bound) {
833 * long r = nextLong();
834 * long n = bound - origin, m = n - 1;
835 * if ((n & m) == 0L) // power of two
836 * r = (r & m) + origin;
837 * else if (n > 0L) { // reject over-represented candidates
838 * for (long u = r >>> 1; // ensure nonnegative
839 * u + m - (r = u % n) < 0L; // rejection check
840 * u = nextLong() >>> 1) // retry
841 * ;
842 * r += origin;
843 * }
844 * else { // range not representable as long
845 * while (r < origin || r >= bound)
846 * r = nextLong();
847 * }
848 * return r;
849 * }}</pre>
850 *
851 * @implNote This method is implemented to be equivalent to {@code
852 * longs(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.
853 *
854 * @param randomNumberOrigin the origin (inclusive) of each random value
855 * @param randomNumberBound the bound (exclusive) of each random value
856 * @return a stream of pseudorandom {@code long} values,
857 * each with the given origin (inclusive) and bound (exclusive)
858 * @throws IllegalArgumentException if {@code randomNumberOrigin}
859 * is greater than or equal to {@code randomNumberBound}
860 * @since 1.8
861 */
862 public LongStream longs(long randomNumberOrigin, long randomNumberBound) {
863 if (randomNumberOrigin >= randomNumberBound)
864 throw new IllegalArgumentException(BadRange);
865 return StreamSupport.longStream
866 (new RandomLongsSpliterator
867 (this, 0L, Long.MAX_VALUE, randomNumberOrigin, randomNumberBound),
868 false);
869 }
870
871 /**
872 * Returns a stream producing the given {@code streamSize} number of
873 * pseudorandom {@code double} values, each between zero
874 * (inclusive) and one (exclusive).
875 *
876 * <p>A pseudorandom {@code double} value is generated as if it's the result
877 * of calling the method {@link #nextDouble()}.
878 *
879 * @param streamSize the number of values to generate
880 * @return a stream of {@code double} values
881 * @throws IllegalArgumentException if {@code streamSize} is
882 * less than zero
883 * @since 1.8
884 */
885 public DoubleStream doubles(long streamSize) {
886 if (streamSize < 0L)
887 throw new IllegalArgumentException(BadSize);
888 return StreamSupport.doubleStream
889 (new RandomDoublesSpliterator
890 (this, 0L, streamSize, Double.MAX_VALUE, 0.0),
891 false);
892 }
893
894 /**
895 * Returns an effectively unlimited stream of pseudorandom {@code
896 * double} values, each between zero (inclusive) and one
897 * (exclusive).
898 *
899 * <p>A pseudorandom {@code double} value is generated as if it's the result
900 * of calling the method {@link #nextDouble()}.
901 *
902 * @implNote This method is implemented to be equivalent to {@code
903 * doubles(Long.MAX_VALUE)}.
904 *
905 * @return a stream of pseudorandom {@code double} values
906 * @since 1.8
907 */
908 public DoubleStream doubles() {
909 return StreamSupport.doubleStream
910 (new RandomDoublesSpliterator
911 (this, 0L, Long.MAX_VALUE, Double.MAX_VALUE, 0.0),
912 false);
913 }
914
915 /**
916 * Returns a stream producing the given {@code streamSize} number of
917 * pseudorandom {@code double} values, each conforming to the given origin
918 * (inclusive) and bound (exclusive).
919 *
920 * <p>A pseudorandom {@code double} value is generated as if it's the result
921 * of calling the following method with the origin and bound:
922 * <pre> {@code
923 * double nextDouble(double origin, double bound) {
924 * double r = nextDouble();
925 * r = r * (bound - origin) + origin;
926 * if (r >= bound) // correct for rounding
927 * r = Math.nextDown(bound);
928 * return r;
929 * }}</pre>
930 *
931 * @param streamSize the number of values to generate
932 * @param randomNumberOrigin the origin (inclusive) of each random value
933 * @param randomNumberBound the bound (exclusive) of each random value
934 * @return a stream of pseudorandom {@code double} values,
935 * each with the given origin (inclusive) and bound (exclusive)
936 * @throws IllegalArgumentException if {@code streamSize} is
937 * less than zero
938 * @throws IllegalArgumentException if {@code randomNumberOrigin}
939 * is greater than or equal to {@code randomNumberBound}
940 * @since 1.8
941 */
942 public DoubleStream doubles(long streamSize, double randomNumberOrigin,
943 double randomNumberBound) {
944 if (streamSize < 0L)
945 throw new IllegalArgumentException(BadSize);
946 if (!(randomNumberOrigin < randomNumberBound))
947 throw new IllegalArgumentException(BadRange);
948 return StreamSupport.doubleStream
949 (new RandomDoublesSpliterator
950 (this, 0L, streamSize, randomNumberOrigin, randomNumberBound),
951 false);
952 }
953
954 /**
955 * Returns an effectively unlimited stream of pseudorandom {@code
956 * double} values, each conforming to the given origin (inclusive) and bound
957 * (exclusive).
958 *
959 * <p>A pseudorandom {@code double} value is generated as if it's the result
960 * of calling the following method with the origin and bound:
961 * <pre> {@code
962 * double nextDouble(double origin, double bound) {
963 * double r = nextDouble();
964 * r = r * (bound - origin) + origin;
965 * if (r >= bound) // correct for rounding
966 * r = Math.nextDown(bound);
967 * return r;
968 * }}</pre>
969 *
970 * @implNote This method is implemented to be equivalent to {@code
971 * doubles(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.
972 *
973 * @param randomNumberOrigin the origin (inclusive) of each random value
974 * @param randomNumberBound the bound (exclusive) of each random value
975 * @return a stream of pseudorandom {@code double} values,
976 * each with the given origin (inclusive) and bound (exclusive)
977 * @throws IllegalArgumentException if {@code randomNumberOrigin}
978 * is greater than or equal to {@code randomNumberBound}
979 * @since 1.8
980 */
981 public DoubleStream doubles(double randomNumberOrigin, double randomNumberBound) {
982 if (!(randomNumberOrigin < randomNumberBound))
983 throw new IllegalArgumentException(BadRange);
984 return StreamSupport.doubleStream
985 (new RandomDoublesSpliterator
986 (this, 0L, Long.MAX_VALUE, randomNumberOrigin, randomNumberBound),
987 false);
988 }
989
990 /**
991 * Spliterator for int streams. We multiplex the four int
992 * versions into one class by treating a bound less than origin as
993 * unbounded, and also by treating "infinite" as equivalent to
994 * Long.MAX_VALUE. For splits, it uses the standard divide-by-two
995 * approach. The long and double versions of this class are
996 * identical except for types.
997 */
998 static final class RandomIntsSpliterator implements Spliterator.OfInt {
999 final Random rng;
1000 long index;
1001 final long fence;
1002 final int origin;
1003 final int bound;
1004 RandomIntsSpliterator(Random rng, long index, long fence,
1005 int origin, int bound) {
1006 this.rng = rng; this.index = index; this.fence = fence;
1007 this.origin = origin; this.bound = bound;
1008 }
1009
1010 public RandomIntsSpliterator trySplit() {
1011 long i = index, m = (i + fence) >>> 1;
1012 return (m <= i) ? null :
1013 new RandomIntsSpliterator(rng, i, index = m, origin, bound);
1014 }
1015
1016 public long estimateSize() {
1017 return fence - index;
1018 }
1019
1020 public int characteristics() {
1021 return (Spliterator.SIZED | Spliterator.SUBSIZED |
1022 Spliterator.NONNULL | Spliterator.IMMUTABLE);
1023 }
1024
1025 public boolean tryAdvance(IntConsumer consumer) {
1026 if (consumer == null) throw new NullPointerException();
1027 long i = index, f = fence;
1028 if (i < f) {
1029 consumer.accept(rng.internalNextInt(origin, bound));
1030 index = i + 1;
1031 return true;
1032 }
1033 return false;
1034 }
1035
1036 public void forEachRemaining(IntConsumer consumer) {
1037 if (consumer == null) throw new NullPointerException();
1038 long i = index, f = fence;
1039 if (i < f) {
1040 index = f;
1041 Random r = rng;
1042 int o = origin, b = bound;
1043 do {
1044 consumer.accept(r.internalNextInt(o, b));
1045 } while (++i < f);
1046 }
1047 }
1048 }
1049
1050 /**
1051 * Spliterator for long streams.
1052 */
1053 static final class RandomLongsSpliterator implements Spliterator.OfLong {
1054 final Random rng;
1055 long index;
1056 final long fence;
1057 final long origin;
1058 final long bound;
1059 RandomLongsSpliterator(Random rng, long index, long fence,
1060 long origin, long bound) {
1061 this.rng = rng; this.index = index; this.fence = fence;
1062 this.origin = origin; this.bound = bound;
1063 }
1064
1065 public RandomLongsSpliterator trySplit() {
1066 long i = index, m = (i + fence) >>> 1;
1067 return (m <= i) ? null :
1068 new RandomLongsSpliterator(rng, i, index = m, origin, bound);
1069 }
1070
1071 public long estimateSize() {
1072 return fence - index;
1073 }
1074
1075 public int characteristics() {
1076 return (Spliterator.SIZED | Spliterator.SUBSIZED |
1077 Spliterator.NONNULL | Spliterator.IMMUTABLE);
1078 }
1079
1080 public boolean tryAdvance(LongConsumer consumer) {
1081 if (consumer == null) throw new NullPointerException();
1082 long i = index, f = fence;
1083 if (i < f) {
1084 consumer.accept(rng.internalNextLong(origin, bound));
1085 index = i + 1;
1086 return true;
1087 }
1088 return false;
1089 }
1090
1091 public void forEachRemaining(LongConsumer consumer) {
1092 if (consumer == null) throw new NullPointerException();
1093 long i = index, f = fence;
1094 if (i < f) {
1095 index = f;
1096 Random r = rng;
1097 long o = origin, b = bound;
1098 do {
1099 consumer.accept(r.internalNextLong(o, b));
1100 } while (++i < f);
1101 }
1102 }
1103
1104 }
1105
1106 /**
1107 * Spliterator for double streams.
1108 */
1109 static final class RandomDoublesSpliterator implements Spliterator.OfDouble {
1110 final Random rng;
1111 long index;
1112 final long fence;
1113 final double origin;
1114 final double bound;
1115 RandomDoublesSpliterator(Random rng, long index, long fence,
1116 double origin, double bound) {
1117 this.rng = rng; this.index = index; this.fence = fence;
1118 this.origin = origin; this.bound = bound;
1119 }
1120
1121 public RandomDoublesSpliterator trySplit() {
1122 long i = index, m = (i + fence) >>> 1;
1123 return (m <= i) ? null :
1124 new RandomDoublesSpliterator(rng, i, index = m, origin, bound);
1125 }
1126
1127 public long estimateSize() {
1128 return fence - index;
1129 }
1130
1131 public int characteristics() {
1132 return (Spliterator.SIZED | Spliterator.SUBSIZED |
1133 Spliterator.NONNULL | Spliterator.IMMUTABLE);
1134 }
1135
1136 public boolean tryAdvance(DoubleConsumer consumer) {
1137 if (consumer == null) throw new NullPointerException();
1138 long i = index, f = fence;
1139 if (i < f) {
1140 consumer.accept(rng.internalNextDouble(origin, bound));
1141 index = i + 1;
1142 return true;
1143 }
1144 return false;
1145 }
1146
1147 public void forEachRemaining(DoubleConsumer consumer) {
1148 if (consumer == null) throw new NullPointerException();
1149 long i = index, f = fence;
1150 if (i < f) {
1151 index = f;
1152 Random r = rng;
1153 double o = origin, b = bound;
1154 do {
1155 consumer.accept(r.internalNextDouble(o, b));
1156 } while (++i < f);
1157 }
1158 }
1159 }
1160
1161 /**
1162 * Serializable fields for Random.
1163 *
1164 * @serialField seed long
1165 * seed for random computations
1166 * @serialField nextNextGaussian double
1167 * next Gaussian to be returned
1168 * @serialField haveNextNextGaussian boolean
1169 * nextNextGaussian is valid
1170 */
1171 private static final ObjectStreamField[] serialPersistentFields = {
1172 new ObjectStreamField("seed", Long.TYPE),
1173 new ObjectStreamField("nextNextGaussian", Double.TYPE),
1174 new ObjectStreamField("haveNextNextGaussian", Boolean.TYPE)
1175 };
1176
1177 /**
1178 * Reconstitute the {@code Random} instance from a stream (that is,
1179 * deserialize it).
1180 */
1181 private void readObject(java.io.ObjectInputStream s)
1182 throws java.io.IOException, ClassNotFoundException {
1183
1184 ObjectInputStream.GetField fields = s.readFields();
1185
1186 // The seed is read in as {@code long} for
1187 // historical reasons, but it is converted to an AtomicLong.
1188 long seedVal = fields.get("seed", -1L);
1189 if (seedVal < 0)
1190 throw new java.io.StreamCorruptedException(
1191 "Random: invalid seed");
1192 resetSeed(seedVal);
1193 nextNextGaussian = fields.get("nextNextGaussian", 0.0);
1194 haveNextNextGaussian = fields.get("haveNextNextGaussian", false);
1195 }
1196
1197 /**
1198 * Save the {@code Random} instance to a stream.
1199 */
1200 private synchronized void writeObject(ObjectOutputStream s)
1201 throws IOException {
1202
1203 // set the values of the Serializable fields
1204 ObjectOutputStream.PutField fields = s.putFields();
1205
1206 // The seed is serialized as a long for historical reasons.
1207 fields.put("seed", seed.get());
1208 fields.put("nextNextGaussian", nextNextGaussian);
1209 fields.put("haveNextNextGaussian", haveNextNextGaussian);
1210
1211 // save them
1212 s.writeFields();
1213 }
1214
1215 // Support for resetting seed while deserializing
1216 private static final Unsafe unsafe = Unsafe.getUnsafe();
1217 private static final long seedOffset;
1218 static {
1219 try {
1220 seedOffset = unsafe.objectFieldOffset
1221 (Random.class.getDeclaredField("seed"));
1222 } catch (Exception ex) { throw new Error(ex); }
1223 }
1224 private void resetSeed(long seedVal) {
1225 unsafe.putObjectVolatile(this, seedOffset, new AtomicLong(seedVal));
1226 }
1227 }
1228