Mercurial > hg > openjdk > lambda > jdk
changeset 9539:b96a8477538a
Doc updates.
| author | psandoz |
|---|---|
| date | Mon, 19 Aug 2013 10:48:57 +0200 |
| parents | 3db1d8103766 |
| children | 82e4ef346a7c |
| files | src/share/classes/java/util/Random.java src/share/classes/java/util/concurrent/ThreadLocalRandom.java |
| diffstat | 2 files changed, 201 insertions(+), 13 deletions(-) [+] |
line wrap: on
line diff
--- a/src/share/classes/java/util/Random.java Fri Aug 16 15:14:39 2013 -0700 +++ b/src/share/classes/java/util/Random.java Mon Aug 19 10:48:57 2013 +0200 @@ -264,7 +264,9 @@ /** * The form of nextInt used by IntStream Spliterators. - * Exactly the same as long version, except for types. + * For the unbounded case, consistent with nextInt(). + * For the bounded case, consistent with nextInt(int bound) + * for power of two and a representable range. * * @param origin the least value, unless greater than bound * @param bound the upper bound (exclusive), must not equal origin @@ -337,23 +339,23 @@ * between 0 (inclusive) and the specified value (exclusive), drawn from * this random number generator's sequence. The general contract of * {@code nextInt} is that one {@code int} value in the specified range - * is pseudorandomly generated and returned. All {@code n} possible + * is pseudorandomly generated and returned. All {@code bound} possible * {@code int} values are produced with (approximately) equal - * probability. The method {@code nextInt(int n)} is implemented by + * probability. The method {@code nextInt(int bound)} is implemented by * class {@code Random} as if by: * <pre> {@code - * public int nextInt(int n) { - * if (n <= 0) - * throw new IllegalArgumentException("n must be positive"); + * public int nextInt(int bound) { + * if (bound <= 0) + * throw new IllegalArgumentException("bound must be positive"); * - * if ((n & -n) == n) // i.e., n is a power of 2 - * return (int)((n * (long)next(31)) >> 31); + * if ((bound & -bound) == bound) // i.e., bound is a power of 2 + * return (int)((bound * (long)next(31)) >> 31); * * int bits, val; * do { * bits = next(31); - * val = bits % n; - * } while (bits - val + (n-1) < 0); + * val = bits % bound; + * } while (bits - val + (bound-1) < 0); * return val; * }}</pre> * @@ -382,9 +384,9 @@ * @param bound the bound on the random number to be returned. Must be * positive. * @return the next pseudorandom, uniformly distributed {@code int} - * value between {@code 0} (inclusive) and {@code n} (exclusive) + * value between {@code 0} (inclusive) and {@code bound} (exclusive) * from this random number generator's sequence - * @throws IllegalArgumentException if n is not positive + * @throws IllegalArgumentException if bound is not positive * @since 1.2 */ public int nextInt(int bound) { @@ -408,15 +410,35 @@ * Returns a pseudorandom {@code int} value between the specified * origin (inclusive) and the specified bound (exclusive). * + * <p>The method {@code nextInt(int origin, int bound)} is implemented by + * class {@code Random} as if by: + * <pre {@code + * public int nextInt(int origin, int bound) { + * if (origin >= bound) + * throw new IllegalArgumentException("bound must be greater than origin"); + * + * int r; + * if (bound - origin > 0) + * r = nextInt(bound - origin) + origin; + * else { + * do { + * r = next(32); + * } while (r < origin || r >= bound); + * } + * return r; + * }}</pre> + * + * nextInt(bound - origin) + origin + * * @param origin the least value returned * @param bound the upper bound (exclusive) * @return a pseudorandom {@code int} value between the origin * (inclusive) and the bound (exclusive) * @throws IllegalArgumentException if {@code origin} is greater than * or equal to {@code bound} + * @since 1.8 */ public int nextInt(int origin, int bound) { - // @@@ Document algorithm as for other int methods? if (origin >= bound) throw new IllegalArgumentException(BadRange); return internalNextInt(origin, bound); @@ -450,11 +472,33 @@ * Returns a pseudorandom {@code long} value between zero (inclusive) * and the specified bound (exclusive). * + * <p>The method {@code nextLong(long bound)} is implemented by class + * {@code Random} as if by: + * <pre>{@code + * public long nextLong(long bound) { + * if (bound <= 0) + * throw new IllegalArgumentException("bound must be positive"); + * + * long r = nextLong(); + * long n = bound - origin, m = n - 1; + * if ((n & m) == 0L) + * r = (r & m) + origin; + * else if (n > 0L) { + * for (long u = r >>> 1; + * u + m - (r = u % n) < 0L; + * u = nextLong() >>> 1) + * ; + * r += origin; + * } + * return r; + * }}</pre> + * * @param bound the bound on the random number to be returned. Must be * positive. * @return a pseudorandom {@code long} value between zero * (inclusive) and the bound (exclusive) * @throws IllegalArgumentException if {@code bound} is not positive + * @since 1.8 */ public long nextLong(long bound) { if (bound <= 0) @@ -466,12 +510,31 @@ * Returns a pseudorandom {@code long} value between the specified * origin (inclusive) and the specified bound (exclusive). * + * <p>The method {@code nextLong(long origin, long bound)} is implemented by + * class {@code Random} as if by: + * <pre>{@code + * public long nextLong(long origin, long bound) { + * if (origin >= bound) + * throw new IllegalArgumentException("bound must be greater than origin"); + * + * long r; + * if (bound - origin > 0) + * r = nextLong(bound - origin) + origin; + * else { + * do { + * r = nextLong(); + * } while (r < origin || r >= bound); + * } + * return r; + * }}</pre> + * * @param origin the least value returned * @param bound the upper bound (exclusive) * @return a pseudorandom {@code long} value between the origin * (inclusive) and the bound (exclusive) * @throws IllegalArgumentException if {@code origin} is greater than * or equal to {@code bound} + * @since 1.8 */ public long nextLong(long origin, long bound) { if (origin >= bound) @@ -592,11 +655,24 @@ * Returns a pseudorandom {@code double} value between 0.0 * (inclusive) and the specified bound (exclusive). * + * <p>The method {@code nextDouble(double bound)} is implemented by class + * {@code Random} as if by: + * <pre>{@code + * public double nextDouble(double bound) { + * if (!(bound > 0.0)) + * throw new IllegalArgumentException("bound must be positive"); + * + * double result = nextDouble() * bound; + * return (result < bound) ? result : + * Double.longBitsToDouble(Double.doubleToLongBits(bound) - 1); + * }}</pre> + * * @param bound the bound on the random number to be returned. Must be * positive. * @return a pseudorandom {@code double} value between zero * (inclusive) and the bound (exclusive) * @throws IllegalArgumentException if {@code bound} is not positive + * @since 1.8 */ public double nextDouble(double bound) { if (!(bound > 0.0)) @@ -610,12 +686,25 @@ * Returns a pseudorandom {@code double} value between the specified * origin (inclusive) and bound (exclusive). * + * <p>The method {@code nextDouble(double origin, double bound)} is + * implemented by class {@code Random} as if by: + * <pre>{@code + * public double nextDouble(double origin, double bound) { + * if (!(origin < bound)) + * throw new IllegalArgumentException("bound must be greater than origin"); + * + * double result = nextDouble() * bound + origin; + * return (result < bound) ? result : + * Double.longBitsToDouble(Double.doubleToLongBits(bound) - 1); + * }}</pre> + * * @param origin the least value returned * @param bound the upper bound * @return a pseudorandom {@code double} value between the origin * (inclusive) and the bound (exclusive) * @throws IllegalArgumentException if {@code origin} is greater than * or equal to {@code bound} + * @since 1.8 */ public double nextDouble(double origin, double bound) { if (!(origin < bound)) @@ -697,10 +786,14 @@ * Returns a stream producing the given {@code streamSize} number of * pseudorandom {@code int} values. * + * <p>A pseudorandom {@code int} value is generated as if it's the result of + * calling the method {@link #nextInt()}. + * * @param streamSize the number of values to generate * @return a stream of pseudorandom {@code int} values * @throws IllegalArgumentException if {@code streamSize} is * less than zero + * @since 1.8 */ public IntStream ints(long streamSize) { if (streamSize < 0L) @@ -715,10 +808,14 @@ * Returns an effectively unlimited stream of pseudorandom {@code int} * values. * + * <p>A pseudorandom {@code int} value is generated as if it's the result of + * calling the method {@link #nextInt()}. + * * @implNote This method is implemented to be equivalent to {@code * ints(Long.MAX_VALUE)}. * * @return a stream of pseudorandom {@code int} values + * @since 1.8 */ public IntStream ints() { return StreamSupport.intStream @@ -732,6 +829,9 @@ * pseudorandom {@code int} values, each conforming to the given * origin and bound. * + * <p>A pseudorandom {@code int} value is generated as if it's the result of + * calling the method {@link #nextInt(int, int)} with the origin and bound. + * * @param streamSize the number of values to generate * @param randomNumberOrigin the origin of each random value * @param randomNumberBound the bound of each random value @@ -740,6 +840,7 @@ * @throws IllegalArgumentException if {@code streamSize} is * less than zero, or {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} + * @since 1.8 */ public IntStream ints(long streamSize, int randomNumberOrigin, int randomNumberBound) { @@ -757,6 +858,9 @@ * Returns an effectively unlimited stream of pseudorandom {@code * int} values, each conforming to the given origin and bound. * + * <p>A pseudorandom {@code int} value is generated as if it's the result of + * calling the method {@link #nextInt(int, int)} with the origin and bound. + * * @implNote This method is implemented to be equivalent to {@code * ints(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}. * @@ -766,6 +870,7 @@ * each with the given origin and bound * @throws IllegalArgumentException if {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} + * @since 1.8 */ public IntStream ints(int randomNumberOrigin, int randomNumberBound) { if (randomNumberOrigin >= randomNumberBound) @@ -780,10 +885,14 @@ * Returns a stream producing the given {@code streamSize} number of * pseudorandom {@code long} values. * + * <p>A pseudorandom {@code long} value is generated as if it's the result + * of calling the method {@link #nextLong()}. + * * @param streamSize the number of values to generate * @return a stream of pseudorandom {@code long} values * @throws IllegalArgumentException if {@code streamSize} is * less than zero + * @since 1.8 */ public LongStream longs(long streamSize) { if (streamSize < 0L) @@ -798,10 +907,14 @@ * Returns an effectively unlimited stream of pseudorandom {@code long} * values. * + * <p>A pseudorandom {@code long} value is generated as if it's the result + * of calling the method {@link #nextLong()}. + * * @implNote This method is implemented to be equivalent to {@code * longs(Long.MAX_VALUE)}. * * @return a stream of pseudorandom {@code long} values + * @since 1.8 */ public LongStream longs() { return StreamSupport.longStream @@ -815,6 +928,10 @@ * pseudorandom {@code long} values, each conforming to the * given origin and bound. * + * <p>A pseudorandom {@code long} value is generated as if it's the result + * of calling the method {@link #nextLong(long, long)} with the origin and + * bound. + * * @param streamSize the number of values to generate * @param randomNumberOrigin the origin of each random value * @param randomNumberBound the bound of each random value @@ -823,6 +940,7 @@ * @throws IllegalArgumentException if {@code streamSize} is * less than zero, or {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} + * @since 1.8 */ public LongStream longs(long streamSize, long randomNumberOrigin, long randomNumberBound) { @@ -840,6 +958,10 @@ * Returns an effectively unlimited stream of pseudorandom {@code * long} values, each conforming to the given origin and bound. * + * <p>A pseudorandom {@code long} value is generated as if it's the result + * of calling the method {@link #nextLong(long, long)} with the origin and + * bound. + * * @implNote This method is implemented to be equivalent to {@code * longs(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}. * @@ -849,6 +971,7 @@ * each with the given origin and bound * @throws IllegalArgumentException if {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} + * @since 1.8 */ public LongStream longs(long randomNumberOrigin, long randomNumberBound) { if (randomNumberOrigin >= randomNumberBound) @@ -864,10 +987,14 @@ * pseudorandom {@code double} values, each between zero * (inclusive) and one (exclusive). * + * <p>A pseudorandom {@code double} value is generated as if it's the result + * of calling the method {@link #nextDouble()}}. + * * @param streamSize the number of values to generate * @return a stream of {@code double} values * @throws IllegalArgumentException if {@code streamSize} is * less than zero + * @since 1.8 */ public DoubleStream doubles(long streamSize) { if (streamSize < 0L) @@ -883,10 +1010,14 @@ * double} values, each between zero (inclusive) and one * (exclusive). * + * <p>A pseudorandom {@code double} value is generated as if it's the result + * of calling the method {@link #nextDouble()}}. + * * @implNote This method is implemented to be equivalent to {@code * doubles(Long.MAX_VALUE)}. * * @return a stream of pseudorandom {@code double} values + * @since 1.8 */ public DoubleStream doubles() { return StreamSupport.doubleStream @@ -900,6 +1031,10 @@ * pseudorandom {@code double} values, each conforming to the * given origin and bound. * + * <p>A pseudorandom {@code double} value is generated as if it's the result + * of calling the method {@link #nextDouble(double, double)} with the origin + * and bound. + * * @param streamSize the number of values to generate * @param randomNumberOrigin the origin of each random value * @param randomNumberBound the bound of each random value @@ -909,6 +1044,7 @@ * less than zero * @throws IllegalArgumentException if {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} + * @since 1.8 */ public DoubleStream doubles(long streamSize, double randomNumberOrigin, double randomNumberBound) { @@ -926,6 +1062,10 @@ * Returns an effectively unlimited stream of pseudorandom {@code * double} values, each conforming to the given origin and bound. * + * <p>A pseudorandom {@code double} value is generated as if it's the result + * of calling the method {@link #nextDouble(double, double)} with the origin + * and bound. + * * @implNote This method is implemented to be equivalent to {@code * doubles(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}. * @@ -935,6 +1075,7 @@ * each with the given origin and bound * @throws IllegalArgumentException if {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} + * @since 1.8 */ public DoubleStream doubles(double randomNumberOrigin, double randomNumberBound) { if (!(randomNumberOrigin < randomNumberBound))
--- a/src/share/classes/java/util/concurrent/ThreadLocalRandom.java Fri Aug 16 15:14:39 2013 -0700 +++ b/src/share/classes/java/util/concurrent/ThreadLocalRandom.java Mon Aug 19 10:48:57 2013 +0200 @@ -1,4 +1,33 @@ /* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +/* + * This file is available under and governed by the GNU General Public + * License version 2 only, as published by the Free Software Foundation. + * However, the following notice accompanied the original version of this + * file: + * * Written by Doug Lea with assistance from members of JCP JSR-166 * Expert Group and released to the public domain, as explained at * http://creativecommons.org/publicdomain/zero/1.0/ @@ -284,6 +313,7 @@ * Returns a pseudorandom {@code int} value. * * @return a pseudorandom {@code int} value + * @since 1.8 */ public int nextInt() { return mix32(nextSeed()); @@ -298,6 +328,7 @@ * @return a pseudorandom {@code int} value between zero * (inclusive) and the bound (exclusive) * @throws IllegalArgumentException if {@code bound} is not positive + * @since 1.8 */ public int nextInt(int bound) { if (bound <= 0) @@ -336,6 +367,7 @@ * Returns a pseudorandom {@code long} value. * * @return a pseudorandom {@code long} value + * @since 1.8 */ public long nextLong() { return mix64(nextSeed()); @@ -390,6 +422,7 @@ * * @return a pseudorandom {@code double} value between zero * (inclusive) and one (exclusive) + * @since 1.8 */ public double nextDouble() { return (mix64(nextSeed()) >>> 11) * DOUBLE_UNIT; @@ -434,6 +467,7 @@ * Returns a pseudorandom {@code boolean} value. * * @return a pseudorandom {@code boolean} value + * @since 1.8 */ public boolean nextBoolean() { return mix32(nextSeed()) < 0; @@ -445,6 +479,7 @@ * * @return a pseudorandom {@code float} value between zero * (inclusive) and one (exclusive) + * @since 1.8 */ public float nextFloat() { return (mix32(nextSeed()) >>> 8) * FLOAT_UNIT; @@ -479,6 +514,7 @@ * @return a stream of pseudorandom {@code int} values * @throws IllegalArgumentException if {@code streamSize} is * less than zero + * @since 1.8 */ @Override public IntStream ints(long streamSize) { @@ -498,6 +534,7 @@ * ints(Long.MAX_VALUE)}. * * @return a stream of pseudorandom {@code int} values + * @since 1.8 */ @Override public IntStream ints() { @@ -520,6 +557,7 @@ * @throws IllegalArgumentException if {@code streamSize} is * less than zero, or {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} + * @since 1.8 */ @Override public IntStream ints(long streamSize, int randomNumberOrigin, @@ -547,6 +585,7 @@ * each with the given origin and bound * @throws IllegalArgumentException if {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} + * @since 1.8 */ @Override public IntStream ints(int randomNumberOrigin, int randomNumberBound) { @@ -566,6 +605,7 @@ * @return a stream of pseudorandom {@code long} values * @throws IllegalArgumentException if {@code streamSize} is * less than zero + * @since 1.8 */ @Override public LongStream longs(long streamSize) { @@ -585,6 +625,7 @@ * longs(Long.MAX_VALUE)}. * * @return a stream of pseudorandom {@code long} values + * @since 1.8 */ @Override public LongStream longs() { @@ -607,6 +648,7 @@ * @throws IllegalArgumentException if {@code streamSize} is * less than zero, or {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} + * @since 1.8 */ @Override public LongStream longs(long streamSize, long randomNumberOrigin, @@ -634,6 +676,7 @@ * each with the given origin and bound * @throws IllegalArgumentException if {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} + * @since 1.8 */ @Override public LongStream longs(long randomNumberOrigin, long randomNumberBound) { @@ -654,6 +697,7 @@ * @return a stream of {@code double} values * @throws IllegalArgumentException if {@code streamSize} is * less than zero + * @since 1.8 */ @Override public DoubleStream doubles(long streamSize) { @@ -674,6 +718,7 @@ * doubles(Long.MAX_VALUE)}. * * @return a stream of pseudorandom {@code double} values + * @since 1.8 */ @Override public DoubleStream doubles() { @@ -697,6 +742,7 @@ * less than zero * @throws IllegalArgumentException if {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} + * @since 1.8 */ @Override public DoubleStream doubles(long streamSize, double randomNumberOrigin, @@ -724,6 +770,7 @@ * each with the given origin and bound * @throws IllegalArgumentException if {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} + * @since 1.8 */ @Override public DoubleStream doubles(double randomNumberOrigin, double randomNumberBound) {