1 /*

     2  * Copyright (c) 2013, 2019, 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.random;

    27 

    28 import java.util.function.Consumer;

    29 import java.util.function.DoubleConsumer;

    30 import java.util.function.IntConsumer;

    31 import java.util.function.LongConsumer;

    32 import java.util.random.RandomGenerator.SplittableGenerator;

    33 import java.util.Spliterator;

    34 import java.util.stream.DoubleStream;

    35 import java.util.stream.IntStream;

    36 import java.util.stream.LongStream;

    37 import java.util.stream.Stream;

    38 import java.util.stream.StreamSupport;

    39 

    40 /**

    41  * Low-level utility methods helpful for implementing pseudorandom number generators.

    42  *

    43  * This class is mostly for library writers creating specific implementations of the

    44  * interface {@link RandomGenerator}.

    45  *

    46  * @since 14

    47  */

    48 public class RandomSupport {

    49 

    50     /*

    51      * Implementation Overview.

    52      *

    53      * This class provides utility methods and constants frequently

    54      * useful in the implementation of pseudorandom number generators

    55      * that satisfy the interface {@link RandomGenerator}.

    56      *

    57      * File organization: First some message strings, then the main

    58      * public methods, followed by a non-public base spliterator class.

    59      */

    60 

    61     // IllegalArgumentException messages

    62     static final String BAD_SIZE = "size must be non-negative";

    63     static final String BAD_DISTANCE = "jump distance must be finite, positive, and an exact integer";

    64     static final String BAD_BOUND = "bound must be positive";

    65     static final String BAD_FLOATING_BOUND = "bound must be finite and positive";

    66     static final String BAD_RANGE = "bound must be greater than origin";

    67 

    68     /* ---------------- public methods ---------------- */

    69 

    70     /**

    71      * Check a {@code long} proposed stream size for validity.

    72      *

    73      * @param streamSize the proposed stream size

    74      *

    75      * @throws IllegalArgumentException if {@code streamSize} is negative

    76      */

    77     public static void checkStreamSize(long streamSize) {

    78         if (streamSize < 0L)

    79             throw new IllegalArgumentException(BAD_SIZE);

    80     }

    81 

    82     /**

    83      * Check a {@code double} proposed jump distance for validity.

    84      *

    85      * @param distance the proposed jump distance

    86      *

    87      * @throws IllegalArgumentException if {@code size} fails to be positive, finite, and an exact integer

    88      */

    89     public static void checkJumpDistance(double distance) {

    90         if (!(distance > 0.0 && distance < Float.POSITIVE_INFINITY

    91                              && distance == Math.floor(distance))) {

    92             throw new IllegalArgumentException(BAD_DISTANCE);

    93         }

    94     }

    95 

    96     /**

    97      * Checks a {@code float} upper bound value for validity.

    98      *

    99      * @param bound the upper bound (exclusive)

   100      *

   101      * @throws IllegalArgumentException if {@code bound} fails to be positive and finite

   102      */

   103     public static void checkBound(float bound) {

   104         if (!(bound > 0.0 && bound < Float.POSITIVE_INFINITY)) {

   105             throw new IllegalArgumentException(BAD_FLOATING_BOUND);

   106         }

   107     }

   108 

   109     /**

   110      * Checks a {@code double} upper bound value for validity.

   111      *

   112      * @param bound the upper bound (exclusive)

   113      *

   114      * @throws IllegalArgumentException if {@code bound} fails to be positive and finite

   115      */

   116     public static void checkBound(double bound) {

   117         if (!(bound > 0.0 && bound < Double.POSITIVE_INFINITY)) {

   118             throw new IllegalArgumentException(BAD_FLOATING_BOUND);

   119         }

   120     }

   121 

   122     /**

   123      * Checks an {@code int} upper bound value for validity.

   124      *

   125      * @param bound the upper bound (exclusive)

   126      *

   127      * @throws IllegalArgumentException if {@code bound} is not positive

   128      */

   129     public static void checkBound(int bound) {

   130         if (bound <= 0) {

   131             throw new IllegalArgumentException(BAD_BOUND);

   132         }

   133     }

   134 

   135     /**

   136      * Checks a {@code long} upper bound value for validity.

   137      *

   138      * @param bound the upper bound (exclusive)

   139      *

   140      * @throws IllegalArgumentException if {@code bound} is not positive

   141      */

   142     public static void checkBound(long bound) {

   143         if (bound <= 0) {

   144             throw new IllegalArgumentException(BAD_BOUND);

   145         }

   146     }

   147 

   148     /**

   149      * Checks a {@code float} range for validity.

   150      *

   151      * @param origin the least value (inclusive) in the range

   152      * @param bound  the upper bound (exclusive) of the range

   153      *

   154      * @throws IllegalArgumentException if {@code origin} is not finite, {@code bound} is not finite,

   155      *                                  or {@code bound - origin} is not finite

   156      */

   157     public static void checkRange(float origin, float bound) {

   158         if (!(origin < bound && (bound - origin) < Float.POSITIVE_INFINITY)) {

   159             throw new IllegalArgumentException(BAD_RANGE);

   160         }

   161     }

   162 

   163     /**

   164      * Checks a {@code double} range for validity.

   165      *

   166      * @param origin the least value (inclusive) in the range

   167      * @param bound  the upper bound (exclusive) of the range

   168      *

   169      * @throws IllegalArgumentException if {@code origin} is not finite, {@code bound} is not finite,

   170      *                                  or {@code bound - origin} is not finite

   171      */

   172     public static void checkRange(double origin, double bound) {

   173         if (!(origin < bound && (bound - origin) < Double.POSITIVE_INFINITY)) {

   174             throw new IllegalArgumentException(BAD_RANGE);

   175         }

   176     }

   177 

   178     /**

   179      * Checks an {@code int} range for validity.

   180      *

   181      * @param origin the least value that can be returned

   182      * @param bound  the upper bound (exclusive) for the returned value

   183      *

   184      * @throws IllegalArgumentException if {@code origin} is greater than or equal to {@code bound}

   185      */

   186     public static void checkRange(int origin, int bound) {

   187         if (origin >= bound) {

   188             throw new IllegalArgumentException(BAD_RANGE);

   189         }

   190     }

   191 

   192     /**

   193      * Checks a {@code long} range for validity.

   194      *

   195      * @param origin the least value that can be returned

   196      * @param bound  the upper bound (exclusive) for the returned value

   197      *

   198      * @throws IllegalArgumentException if {@code origin} is greater than or equal to {@code bound}

   199      */

   200     public static void checkRange(long origin, long bound) {

   201         if (origin >= bound) {

   202             throw new IllegalArgumentException(BAD_RANGE);

   203         }

   204     }

   205 

   206     /**

   207      * Given an array of seed bytes of any length, construct an array

   208      * of {@code long} seed values of length {@code n}, such that the

   209      * last {@code z} values are not all zero.

   210      *

   211      * @param seed an array of {@code byte} values

   212      * @param n the length of the result array (should be nonnegative)

   213      * @param z the number of trailing result elements that are required

   214      *        to be not all zero (should be nonnegative but not larger

   215      *        than {@code n})

   216      *

   217      * @return an array of length {@code n} containing {@code long} seed values

   218      */

   219     public static long[] convertSeedBytesToLongs(byte[] seed, int n, int z) {

   220         final long[] result = new long[n];

   221         final int m = Math.min(seed.length, n << 3);

   222         // Distribute seed bytes into the words to be formed.

   223         for (int j = 0; j < m; j++) {

   224             result[j>>3] = (result[j>>3] << 8) | seed[j];

   225         }

   226         // If there aren't enough seed bytes for all the words we need,

   227         // use a SplitMix-style PRNG to fill in the rest.

   228         long v = result[0];

   229         for (int j = (m + 7) >> 3; j < n; j++) {

   230             result[j] = mixMurmur64(v += SILVER_RATIO_64);

   231         }

   232         // Finally, we need to make sure the last z words are not all zero.

   233         search: {

   234             for (int j = n - z; j < n; j++) {

   235                 if (result[j] != 0) break search;

   236             }

   237             // If they are, fill in using a SplitMix-style PRNG.

   238             // Using "& ~1L" in the next line defends against the case z==1

   239             // by guaranteeing that the first generated value will be nonzero.

   240             long w = result[0] & ~1L;

   241             for (int j = n - z; j < n; j++) {

   242                 result[j] = mixMurmur64(w += SILVER_RATIO_64);

   243             }

   244         }

   245         return result;

   246     }

   247 

   248     /**

   249      * Given an array of seed bytes of any length, construct an array

   250      * of {@code int} seed values of length {@code n}, such that the

   251      * last {@code z} values are not all zero.

   252      *

   253      * @param seed an array of {@code byte} values

   254      * @param n the length of the result array (should be nonnegative)

   255      * @param z the number of trailing result elements that are required

   256      *        to be not all zero (should be nonnegative but not larger

   257      *        than {@code n})

   258      *

   259      * @return an array of length {@code n} containing {@code int} seed values

   260      */

   261     public static int[] convertSeedBytesToInts(byte[] seed, int n, int z) {

   262         final int[] result = new int[n];

   263         final int m = Math.min(seed.length, n << 2);

   264         // Distribute seed bytes into the words to be formed.

   265         for (int j = 0; j < m; j++) {

   266             result[j>>2] = (result[j>>2] << 8) | seed[j];

   267         }

   268         // If there aren't enough seed bytes for all the words we need,

   269         // use a SplitMix-style PRNG to fill in the rest.

   270         int v = result[0];

   271         for (int j = (m + 3) >> 2; j < n; j++) {

   272             result[j] = mixMurmur32(v += SILVER_RATIO_32);

   273         }

   274         // Finally, we need to make sure the last z words are not all zero.

   275         search: {

   276             for (int j = n - z; j < n; j++) {

   277                 if (result[j] != 0) break search;

   278             }

   279             // If they are, fill in using a SplitMix-style PRNG.

   280             // Using "& ~1" in the next line defends against the case z==1

   281             // by guaranteeing that the first generated value will be nonzero.

   282             int w = result[0] & ~1;

   283             for (int j = n - z; j < n; j++) {

   284                 result[j] = mixMurmur32(w += SILVER_RATIO_32);

   285             }

   286         }

   287         return result;

   288     }

   289 

   290     /*

   291      * Bounded versions of nextX methods used by streams, as well as

   292      * the public nextX(origin, bound) methods.  These exist mainly to

   293      * avoid the need for multiple versions of stream spliterators

   294      * across the different exported forms of streams.

   295      */

   296 

   297     /**

   298      * This is the form of {@code nextLong} used by a {@link LongStream}

   299      * {@link Spliterator} and by the public method

   300      * {@code nextLong(origin, bound)}.  If {@code origin} is greater

   301      * than {@code bound}, then this method simply calls the unbounded

   302      * version of {@code nextLong()}, choosing pseudorandomly from

   303      * among all 2<sup>64</sup> possible {@code long} values}, and

   304      * otherwise uses one or more calls to {@code nextLong()} to

   305      * choose a value pseudorandomly from the possible values

   306      * between {@code origin} (inclusive) and {@code bound} (exclusive).

   307      *

   308      * @implNote This method first calls {@code nextLong()} to obtain

   309      * a {@code long} value that is assumed to be pseudorandomly

   310      * chosen uniformly and independently from the 2<sup>64</sup>

   311      * possible {@code long} values (that is, each of the 2<sup>64</sup>

   312      * possible long values is equally likely to be chosen).

   313      * Under some circumstances (when the specified range is not

   314      * a power of 2), {@code nextLong()} may be called additional times

   315      * to ensure that that the values in the specified range are

   316      * equally likely to be chosen (provided the assumption holds).

   317      * <p>

   318      * The implementation considers four cases:

   319      * <ol>

   320      *

   321      * <li> If the {@code} bound} is less than or equal to the {@code origin}

   322      *      (indicated an unbounded form), the 64-bit {@code long} value

   323      *      obtained from {@code nextLong()} is returned directly.

   324      *

   325      * <li> Otherwise, if the length <i>n</i> of the specified range is an

   326      *      exact power of two 2<sup><i>m</i></sup> for some integer

   327      *      <i>m</i>, then return the sum of {@code origin} and the

   328      *      <i>m</i> lowest-order bits of the value from {@code nextLong()}.

   329      *

   330      * <li> Otherwise, if the length <i>n</i> of the specified range

   331      *      is less than 2<sup>63</sup>, then the basic idea is to use the

   332      *      remainder modulo <i>n</i> of the value from {@code nextLong()},

   333      *      but with this approach some values will be over-represented.

   334      *      Therefore a loop is used to avoid potential bias by rejecting

   335      *      candidates that are too large.  Assuming that the results from

   336      *      {@code nextLong()} are truly chosen uniformly and independently,

   337      *      the expected number of iterations will be somewhere between

   338      *      1 and 2, depending on the precise value of <i>n</i>.

   339      *

   340      * <li> Otherwise, the length <i>n</i> of the specified range

   341      *      cannot be represented as a positive {@code long} value.

   342      *      A loop repeatedly calls {@code nextlong()} until obtaining

   343      *      a suitable candidate,  Again, the expected number of iterations

   344      *      is less than 2.

   345      *

   346      * </ol>

   347      *

   348      * @param rng a random number generator to be used as a

   349      *        source of pseudorandom {@code long} values

   350      * @param origin the least value that can be produced,

   351      *        unless greater than or equal to {@code bound}

   352      * @param bound the upper bound (exclusive), unless {@code origin}

   353      *        is greater than or equal to {@code bound}

   354      *

   355      * @return a pseudorandomly chosen {@code long} value,

   356      *         which will be between {@code origin} (inclusive) and

   357      *         {@code bound} exclusive unless {@code origin}

   358      *         is greater than or equal to {@code bound}

   359      */

   360     public static long boundedNextLong(RandomGenerator rng, long origin, long bound) {

   361         long r = rng.nextLong();

   362         if (origin < bound) {

   363             // It's not case (1).

   364             final long n = bound - origin;

   365             final long m = n - 1;

   366             if ((n & m) == 0L) {

   367                 // It is case (2): length of range is a power of 2.

   368                 r = (r & m) + origin;

   369             } else if (n > 0L) {

   370                 // It is case (3): need to reject over-represented candidates.

   371                 /* This loop takes an unlovable form (but it works):

   372                    because the first candidate is already available,

   373                    we need a break-in-the-middle construction,

   374                    which is concisely but cryptically performed

   375                    within the while-condition of a body-less for loop. */

   376                 for (long u = r >>> 1;            // ensure nonnegative

   377                      u + m - (r = u % n) < 0L;    // rejection check

   378                      u = rng.nextLong() >>> 1) // retry

   379                     ;

   380                 r += origin;

   381             }

   382             else {

   383                 // It is case (4): length of range not representable as long.

   384                 while (r < origin || r >= bound)

   385                     r = rng.nextLong();

   386             }

   387         }

   388         return r;

   389     }

   390 

   391     /**

   392      * This is the form of {@code nextLong} used by the public method

   393      * {@code nextLong(bound)}.  This is essentially a version of

   394      * {@code boundedNextLong(origin, bound)} that has been

   395      * specialized for the case where the {@code origin} is zero

   396      * and the {@code bound} is greater than zero.  The value

   397      * returned is chosen pseudorandomly from nonnegative integer

   398      * values less than {@code bound}.

   399      *

   400      * @implNote This method first calls {@code nextLong()} to obtain

   401      * a {@code long} value that is assumed to be pseudorandomly

   402      * chosen uniformly and independently from the 2<sup>64</sup>

   403      * possible {@code long} values (that is, each of the 2<sup>64</sup>

   404      * possible long values is equally likely to be chosen).

   405      * Under some circumstances (when the specified range is not

   406      * a power of 2), {@code nextLong()} may be called additional times

   407      * to ensure that that the values in the specified range are

   408      * equally likely to be chosen (provided the assumption holds).

   409      * <p>

   410      * The implementation considers two cases:

   411      * <ol>

   412      *

   413      * <li> If {@code bound} is an exact power of two 2<sup><i>m</i></sup>

   414      *      for some integer <i>m</i>, then return the sum of {@code origin}

   415      *      and the <i>m</i> lowest-order bits of the value from

   416      *      {@code nextLong()}.

   417      *

   418      * <li> Otherwise, the basic idea is to use the remainder modulo

   419      *      <i>bound</i> of the value from {@code nextLong()},

   420      *      but with this approach some values will be over-represented.

   421      *      Therefore a loop is used to avoid potential bias by rejecting

   422      *      candidates that vare too large.  Assuming that the results from

   423      *      {@code nextLong()} are truly chosen uniformly and independently,

   424      *      the expected number of iterations will be somewhere between

   425      *      1 and 2, depending on the precise value of <i>bound</i>.

   426      *

   427      * </ol>

   428      *

   429      * @param rng a random number generator to be used as a

   430      *        source of pseudorandom {@code long} values

   431      * @param bound the upper bound (exclusive); must be greater than zero

   432      *

   433      * @return a pseudorandomly chosen {@code long} value

   434      */

   435     public static long boundedNextLong(RandomGenerator rng, long bound) {

   436         // Specialize boundedNextLong for origin == 0, bound > 0

   437         final long m = bound - 1;

   438         long r = rng.nextLong();

   439         if ((bound & m) == 0L) {

   440             // The bound is a power of 2.

   441             r &= m;

   442         } else {

   443             // Must reject over-represented candidates

   444             /* This loop takes an unlovable form (but it works):

   445                because the first candidate is already available,

   446                we need a break-in-the-middle construction,

   447                which is concisely but cryptically performed

   448                within the while-condition of a body-less for loop. */

   449             for (long u = r >>> 1;

   450                  u + m - (r = u % bound) < 0L;

   451                  u = rng.nextLong() >>> 1)

   452                 ;

   453         }

   454         return r;

   455     }

   456 

   457     /**

   458      * This is the form of {@code nextInt} used by an {@link IntStream}

   459      * {@link Spliterator} and by the public method

   460      * {@code nextInt(origin, bound)}.  If {@code origin} is greater

   461      * than {@code bound}, then this method simply calls the unbounded

   462      * version of {@code nextInt()}, choosing pseudorandomly from

   463      * among all 2<sup>64</sup> possible {@code int} values}, and

   464      * otherwise uses one or more calls to {@code nextInt()} to

   465      * choose a value pseudorandomly from the possible values

   466      * between {@code origin} (inclusive) and {@code bound} (exclusive).

   467      *

   468      * @param rng a random number generator to be used as a

   469      *        source of pseudorandom {@code int} values

   470      * @param origin the least value that can be produced,

   471      *        unless greater than or equal to {@code bound}

   472      * @param bound the upper bound (exclusive), unless {@code origin}

   473      *        is greater than or equal to {@code bound}

   474      *

   475      * @return a pseudorandomly chosen {@code int} value,

   476      *         which will be between {@code origin} (inclusive) and

   477      *         {@code bound} exclusive unless {@code origin}

   478      *         is greater than or equal to {@code bound}

   479      *

   480      * @implNote The implementation of this method is identical to

   481      *           the implementation of {@code nextLong(origin, bound)}

   482      *           except that {@code int} values and the {@code nextInt()}

   483      *           method are used rather than {@code long} values and the

   484      *           {@code nextLong()} method.

   485      */

   486     public static int boundedNextInt(RandomGenerator rng, int origin, int bound) {

   487         int r = rng.nextInt();

   488         if (origin < bound) {

   489             // It's not case (1).

   490             final int n = bound - origin;

   491             final int m = n - 1;

   492             if ((n & m) == 0) {

   493                 // It is case (2): length of range is a power of 2.

   494                 r = (r & m) + origin;

   495             } else if (n > 0) {

   496                 // It is case (3): need to reject over-represented candidates.

   497                 for (int u = r >>> 1;

   498                      u + m - (r = u % n) < 0;

   499                      u = rng.nextInt() >>> 1)

   500                     ;

   501                 r += origin;

   502             }

   503             else {

   504                 // It is case (4): length of range not representable as long.

   505                 while (r < origin || r >= bound) {

   506                     r = rng.nextInt();

   507                 }

   508             }

   509         }

   510         return r;

   511     }

   512 

   513     /**

   514      * This is the form of {@code nextInt} used by the public method

   515      * {@code nextInt(bound)}.  This is essentially a version of

   516      * {@code boundedNextInt(origin, bound)} that has been

   517      * specialized for the case where the {@code origin} is zero

   518      * and the {@code bound} is greater than zero.  The value

   519      * returned is chosen pseudorandomly from nonnegative integer

   520      * values less than {@code bound}.

   521      *

   522      * @param rng a random number generator to be used as a

   523      *        source of pseudorandom {@code long} values

   524      * @param bound the upper bound (exclusive); must be greater than zero

   525      *

   526      * @return a pseudorandomly chosen {@code long} value

   527      *

   528      * @implNote The implementation of this method is identical to

   529      *           the implementation of {@code nextLong(bound)}

   530      *           except that {@code int} values and the {@code nextInt()}

   531      *           method are used rather than {@code long} values and the

   532      *           {@code nextLong()} method.

   533      */

   534     public static int boundedNextInt(RandomGenerator rng, int bound) {

   535         // Specialize boundedNextInt for origin == 0, bound > 0

   536         final int m = bound - 1;

   537         int r = rng.nextInt();

   538         if ((bound & m) == 0) {

   539             // The bound is a power of 2.

   540             r &= m;

   541         } else {

   542             // Must reject over-represented candidates

   543             for (int u = r >>> 1;

   544                  u + m - (r = u % bound) < 0;

   545                  u = rng.nextInt() >>> 1)

   546                 ;

   547         }

   548         return r;

   549     }

   550 

   551     /**

   552      * This is the form of {@code nextDouble} used by a {@link DoubleStream}

   553      * {@link Spliterator} and by the public method

   554      * {@code nextDouble(origin, bound)}.  If {@code origin} is greater

   555      * than {@code bound}, then this method simply calls the unbounded

   556      * version of {@code nextDouble()}, and otherwise scales and translates

   557      * the result of a call to {@code nextDouble()} so that it lies

   558      * between {@code origin} (inclusive) and {@code bound} (exclusive).

   559      *

   560      * @implNote The implementation considers two cases:

   561      * <ol>

   562      *

   563      * <li> If the {@code bound} is less than or equal to the {@code origin}

   564      *      (indicated an unbounded form), the 64-bit {@code double} value

   565      *      obtained from {@code nextDouble()} is returned directly.

   566      *

   567      * <li> Otherwise, the result of a call to {@code nextDouble} is

   568      *      multiplied by {@code (bound - origin)}, then {@code origin}

   569      *      is added, and then if this this result is not less than

   570      *      {@code bound} (which can sometimes occur because of rounding),

   571      *      it is replaced with the largest {@code double} value that

   572      *      is less than {@code bound}.

   573      *

   574      * </ol>

   575      *

   576      * @param rng a random number generator to be used as a

   577      *        source of pseudorandom {@code double} values

   578      * @param origin the least value that can be produced,

   579      *        unless greater than or equal to {@code bound}; must be finite

   580      * @param bound the upper bound (exclusive), unless {@code origin}

   581      *        is greater than or equal to {@code bound}; must be finite

   582      * @return a pseudorandomly chosen {@code double} value,

   583      *         which will be between {@code origin} (inclusive) and

   584      *         {@code bound} exclusive unless {@code origin}

   585      *         is greater than or equal to {@code bound},

   586      *         in which case it will be between 0.0 (inclusive)

   587      *         and 1.0 (exclusive)

   588      */

   589     public static double boundedNextDouble(RandomGenerator rng, double origin, double bound) {

   590         double r = rng.nextDouble();

   591         if (origin < bound) {

   592             r = r * (bound - origin) + origin;

   593             if (r >= bound)  // may need to correct a rounding problem

   594                 r = Double.longBitsToDouble(Double.doubleToLongBits(bound) - 1);

   595         }

   596         return r;

   597     }

   598 

   599     /**

   600      * This is the form of {@code nextDouble} used by the public method

   601      * {@code nextDouble(bound)}.  This is essentially a version of

   602      * {@code boundedNextDouble(origin, bound)} that has been

   603      * specialized for the case where the {@code origin} is zero

   604      * and the {@code bound} is greater than zero.

   605      *

   606      * @implNote The result of a call to {@code nextDouble} is

   607      *      multiplied by {@code bound}, and then if this result is

   608      *      not less than {@code bound} (which can sometimes occur

   609      *      because of rounding), it is replaced with the largest

   610      *      {@code double} value that is less than {@code bound}.

   611      *

   612      * @param rng a random number generator to be used as a

   613      *        source of pseudorandom {@code double} values

   614      * @param bound the upper bound (exclusive); must be finite and

   615      *        greater than zero

   616      * @return a pseudorandomly chosen {@code double} value

   617      *         between zero (inclusive) and {@code bound} (exclusive)

   618      */

   619     public static double boundedNextDouble(RandomGenerator rng, double bound) {

   620         // Specialize boundedNextDouble for origin == 0, bound > 0

   621         double r = rng.nextDouble();

   622         r = r * bound;

   623         if (r >= bound)  // may need to correct a rounding problem

   624             r = Double.longBitsToDouble(Double.doubleToLongBits(bound) - 1);

   625         return r;

   626     }

   627 

   628     /**

   629      * This is the form of {@code nextFloat} used by a {@code Stream<Float>}

   630      * {@link Spliterator} (if there were any) and by the public method

   631      * {@code nextFloat(origin, bound)}.  If {@code origin} is greater

   632      * than {@code bound}, then this method simply calls the unbounded

   633      * version of {@code nextFloat()}, and otherwise scales and translates

   634      * the result of a call to {@code nextFloat()} so that it lies

   635      * between {@code origin} (inclusive) and {@code bound} (exclusive).

   636      *

   637      * @implNote The implementation of this method is identical to

   638      *     the implementation of {@code nextDouble(origin, bound)}

   639      *     except that {@code float} values and the {@code nextFloat()}

   640      *     method are used rather than {@code double} values and the

   641      *     {@code nextDouble()} method.

   642      *

   643      * @param rng a random number generator to be used as a

   644      *        source of pseudorandom {@code float} values

   645      * @param origin the least value that can be produced,

   646      *        unless greater than or equal to {@code bound}; must be finite

   647      * @param bound the upper bound (exclusive), unless {@code origin}

   648      *        is greater than or equal to {@code bound}; must be finite

   649      * @return a pseudorandomly chosen {@code float} value,

   650      *         which will be between {@code origin} (inclusive) and

   651      *         {@code bound} exclusive unless {@code origin}

   652      *         is greater than or equal to {@code bound},

   653      *         in which case it will be between 0.0 (inclusive)

   654      *         and 1.0 (exclusive)

   655      */

   656     public static float boundedNextFloat(RandomGenerator rng, float origin, float bound) {

   657         float r = rng.nextFloat();

   658         if (origin < bound) {

   659             r = r * (bound - origin) + origin;

   660             if (r >= bound) // may need to correct a rounding problem

   661                 r = Float.intBitsToFloat(Float.floatToIntBits(bound) - 1);

   662         }

   663         return r;

   664     }

   665 

   666     /**

   667      * This is the form of {@code nextFloat} used by the public method

   668      * {@code nextFloat(bound)}.  This is essentially a version of

   669      * {@code boundedNextFloat(origin, bound)} that has been

   670      * specialized for the case where the {@code origin} is zero

   671      * and the {@code bound} is greater than zero.

   672      *

   673      * @implNote The implementation of this method is identical to

   674      *     the implementation of {@code nextDouble(bound)}

   675      *     except that {@code float} values and the {@code nextFloat()}

   676      *     method are used rather than {@code double} values and the

   677      *     {@code nextDouble()} method.

   678      *

   679      * @param rng a random number generator to be used as a

   680      *        source of pseudorandom {@code float} values

   681      * @param bound the upper bound (exclusive); must be finite and

   682      *        greater than zero

   683      * @return a pseudorandomly chosen {@code float} value

   684      *         between zero (inclusive) and {@code bound} (exclusive)

   685      */

   686     public static float boundedNextFloat(RandomGenerator rng, float bound) {

   687         // Specialize boundedNextFloat for origin == 0, bound > 0

   688         float r = rng.nextFloat();

   689         r = r * bound;

   690         if (r >= bound) // may need to correct a rounding problem

   691             r = Float.intBitsToFloat(Float.floatToIntBits(bound) - 1);

   692         return r;

   693     }

   694 

   695     // The following decides which of two strategies initialSeed() will use.

   696     private static boolean secureRandomSeedRequested() {

   697         String pp = java.security.AccessController.doPrivileged(

   698                 new sun.security.action.GetPropertyAction(

   699                         "java.util.secureRandomSeed"));

   700         return (pp != null && pp.equalsIgnoreCase("true"));

   701     }

   702 

   703     private static final boolean useSecureRandomSeed = secureRandomSeedRequested();

   704 

   705     /**

   706      * Returns a {@code long} value (chosen from some

   707      * machine-dependent entropy source) that may be useful for

   708      * initializing a source of seed values for instances of {@link RandomGenerator}

   709      * created by zero-argument constructors.  (This method should

   710      * <i>not</i> be called repeatedly, once per constructed

   711      * object; at most it should be called once per class.)

   712      *

   713      * @return a {@code long} value, randomly chosen using

   714      *         appropriate environmental entropy

   715      */

   716     public static long initialSeed() {

   717         if (useSecureRandomSeed) {

   718             byte[] seedBytes = java.security.SecureRandom.getSeed(8);

   719             long s = (long)(seedBytes[0]) & 0xffL;

   720             for (int i = 1; i < 8; ++i)

   721                 s = (s << 8) | ((long)(seedBytes[i]) & 0xffL);

   722             return s;

   723         }

   724         return (mixStafford13(System.currentTimeMillis()) ^

   725                 mixStafford13(System.nanoTime()));

   726     }

   727 

   728     /**

   729      * The first 32 bits of the golden ratio (1+sqrt(5))/2, forced to be odd.

   730      * Useful for producing good Weyl sequences or as an arbitrary nonzero odd value.

   731      */

   732     public static final int  GOLDEN_RATIO_32 = 0x9e3779b9;

   733 

   734     /**

   735      * The first 64 bits of the golden ratio (1+sqrt(5))/2, forced to be odd.

   736      * Useful for producing good Weyl sequences or as an arbitrary nonzero odd value.

   737      */

   738     public static final long GOLDEN_RATIO_64 = 0x9e3779b97f4a7c15L;

   739 

   740     /**

   741      * The first 32 bits of the silver ratio 1+sqrt(2), forced to be odd.

   742      * Useful for producing good Weyl sequences or as an arbitrary nonzero odd value.

   743      */

   744     public static final int  SILVER_RATIO_32 = 0x6A09E667;

   745 

   746     /**

   747      * The first 64 bits of the silver ratio 1+sqrt(2), forced to be odd.

   748      * Useful for producing good Weyl sequences or as an arbitrary nonzero odd value.

   749      */

   750     public static final long SILVER_RATIO_64 = 0x6A09E667F3BCC909L;

   751 

   752     /**

   753      * Computes the 64-bit mixing function for MurmurHash3.

   754      * This is a 64-bit hashing function with excellent avalanche statistics.

   755      * https://github.com/aappleby/smhasher/wiki/MurmurHash3

   756      *

   757      * Note that if the argument {@code z} is 0, the result is 0.

   758      *

   759      * @param z any long value

   760      *

   761      * @return the result of hashing z

   762      */

   763     public static long mixMurmur64(long z) {

   764         z = (z ^ (z >>> 33)) * 0xff51afd7ed558ccdL;

   765         z = (z ^ (z >>> 33)) * 0xc4ceb9fe1a85ec53L;

   766         return z ^ (z >>> 33);

   767     }

   768 

   769     /**

   770      * Computes Stafford variant 13 of the 64-bit mixing function for MurmurHash3.

   771      * This is a 64-bit hashing function with excellent avalanche statistics.

   772      * http://zimbry.blogspot.com/2011/09/better-bit-mixing-improving-on.html

   773      *

   774      * Note that if the argument {@code z} is 0, the result is 0.

   775      *

   776      * @param z any long value

   777      *

   778      * @return the result of hashing z

   779      */

   780     public static long mixStafford13(long z) {

   781         z = (z ^ (z >>> 30)) * 0xbf58476d1ce4e5b9L;

   782         z = (z ^ (z >>> 27)) * 0x94d049bb133111ebL;

   783         return z ^ (z >>> 31);

   784     }

   785 

   786     /**

   787      * Computes Doug Lea's 64-bit mixing function.

   788      * This is a 64-bit hashing function with excellent avalanche statistics.

   789      * It has the advantages of using the same multiplicative constant twice

   790      * and of using only 32-bit shifts.

   791      *

   792      * Note that if the argument {@code z} is 0, the result is 0.

   793      *

   794      * @param z any long value

   795      *

   796      * @return the result of hashing z

   797      */

   798     public static long mixLea64(long z) {

   799         z = (z ^ (z >>> 32)) * 0xdaba0b6eb09322e3L;

   800         z = (z ^ (z >>> 32)) * 0xdaba0b6eb09322e3L;

   801         return z ^ (z >>> 32);

   802     }

   803 

   804     /**

   805      * Computes the 32-bit mixing function for MurmurHash3.

   806      * This is a 32-bit hashing function with excellent avalanche statistics.

   807      * https://github.com/aappleby/smhasher/wiki/MurmurHash3

   808      *

   809      * Note that if the argument {@code z} is 0, the result is 0.

   810      *

   811      * @param z any long value

   812      *

   813      * @return the result of hashing z

   814      */

   815     public static int mixMurmur32(int z) {

   816         z = (z ^ (z >>> 16)) * 0x85ebca6b;

   817         z = (z ^ (z >>> 13)) * 0xc2b2ae35;

   818         return z ^ (z >>> 16);

   819     }

   820 

   821     /**

   822      * Computes Doug Lea's 32-bit mixing function.

   823      * This is a 32-bit hashing function with excellent avalanche statistics.

   824      * It has the advantages of using the same multiplicative constant twice

   825      * and of using only 16-bit shifts.

   826      *

   827      * Note that if the argument {@code z} is 0, the result is 0.

   828      *

   829      * @param z any long value

   830      *

   831      * @return the result of hashing z

   832      */

   833     public static int mixLea32(int z) {

   834         z = (z ^ (z >>> 16)) * 0xd36d884b;

   835         z = (z ^ (z >>> 16)) * 0xd36d884b;

   836         return z ^ (z >>> 16);

   837     }

   838 

   839     // Non-public (package only) support for spliterators needed by AbstractSplittableGenerator

   840     // and AbstractArbitrarilyJumpableGenerator and AbstractSharedGenerator

   841 

   842     /**

   843      * Base class for making Spliterator classes for streams of randomly chosen values.

   844      */

   845     public abstract static class RandomSpliterator {

   846 

   847         /** low range value */

   848         public long index;

   849 

   850         /** high range value */

   851         public final long fence;

   852 

   853         /**

   854          * Constructor

   855          *

   856          * @param index  low range value

   857          * @param fence  high range value

   858          */

   859         public RandomSpliterator(long index, long fence) {

   860             this.index = index; this.fence = fence;

   861         }

   862 

   863         /**

   864          * Returns estimated size.

   865          *

   866          * @return estimated size

   867          */

   868         public long estimateSize() {

   869             return fence - index;

   870         }

   871 

   872         /**

   873          * Returns characteristics.

   874          *

   875          * @return characteristics

   876          */

   877         public int characteristics() {

   878             return (Spliterator.SIZED | Spliterator.SUBSIZED |

   879                     Spliterator.NONNULL | Spliterator.IMMUTABLE);

   880         }

   881     }

   882 

   883 

   884     /*

   885      * Implementation support for nextExponential() and nextGaussian() methods of RandomGenerator.

   886      *

   887      * Each is implemented using McFarland's fast modified ziggurat algorithm (largely

   888      * table-driven, with rare cases handled by computation and rejection sampling).

   889      * Walker's alias method for sampling a discrete distribution also plays a role.

   890      *

   891      * The tables themselves, as well as a number of associated parameters, are defined

   892      * in class java.util.DoubleZigguratTables, which is automatically generated by the

   893      * program create_ziggurat_tables.c (which takes only a few seconds to run).

   894      *

   895      * For more information about the algorithms, see these articles:

   896      *

   897      * Christopher D. McFarland.  2016 (published online 24 Jun 2015).  A modified ziggurat

   898      * algorithm for generating exponentially and normally distributed pseudorandom numbers.

   899      * Journal of Statistical Computation and Simulation 86 (7), pages 1281-1294.

   900      * https://www.tandfonline.com/doi/abs/10.1080/00949655.2015.1060234

   901      * Also at https://arxiv.org/abs/1403.6870 (26 March 2014).

   902      *

   903      * Alastair J. Walker.  1977.  An efficient method for generating discrete random

   904      * variables with general distributions. ACM Trans. Math. Software 3, 3

   905      * (September 1977), 253-256. DOI: https://doi.org/10.1145/355744.355749

   906      *

   907      * Certain details of these algorithms depend critically on the quality of the

   908      * low-order bits delivered by NextLong().  These algorithms should not be used

   909      * with RNG algorithms (such as a simple Linear Congruential Generator) whose

   910      * low-order output bits do not have good statistical quality.

   911      */

   912 

   913     // Implementation support for nextExponential()

   914 

   915     static double computeNextExponential(RandomGenerator rng) {

   916         long U1 = rng.nextLong();

   917         // Experimentation on a variety of machines indicates that it is overall much faster

   918         // to do the following & and < operations on longs rather than first cast U1 to int

   919         // (but then we need to cast to int before doing the array indexing operation).

   920         long i = U1 & DoubleZigguratTables.exponentialLayerMask;

   921         if (i < DoubleZigguratTables.exponentialNumberOfLayers) {

   922             // This is the fast path (occurring more than 98% of the time).  Make an early exit.

   923             return DoubleZigguratTables.exponentialX[(int)i] * (U1 >>> 1);

   924         }

   925         // We didn't use the upper part of U1 after all.  We'll be able to use it later.

   926 

   927         for (double extra = 0.0; ; ) {

   928             // Use Walker's alias method to sample an (unsigned) integer j from a discrete

   929             // probability distribution that includes the tail and all the ziggurat overhangs;

   930             // j will be less than DoubleZigguratTables.exponentialNumberOfLayers + 1.

   931             long UA = rng.nextLong();

   932             int j = (int)UA & DoubleZigguratTables.exponentialAliasMask;

   933             if (UA >= DoubleZigguratTables.exponentialAliasThreshold[j]) {

   934                 j = DoubleZigguratTables.exponentialAliasMap[j] &

   935                     DoubleZigguratTables.exponentialSignCorrectionMask;

   936             }

   937             if (j > 0) {   // Sample overhang j

   938                 // For the exponential distribution, every overhang is convex.

   939                 final double[] X = DoubleZigguratTables.exponentialX;

   940                 final double[] Y = DoubleZigguratTables.exponentialY;

   941                 for (;; U1 = (rng.nextLong() >>> 1)) {

   942                     long U2 = (rng.nextLong() >>> 1);

   943                     // Compute the actual x-coordinate of the randomly chosen point.

   944                     double x = (X[j] * 0x1.0p63) + ((X[j-1] - X[j]) * (double)U1);

   945                     // Does the point lie below the curve?

   946                     long Udiff = U2 - U1;

   947                     if (Udiff < 0) {

   948                         // We picked a point in the upper-right triangle.  None of those can be

   949                         // accepted.  So remap the point into the lower-left triangle and try that.

   950                         // In effect, we swap U1 and U2, and invert the sign of Udiff.

   951                         Udiff = -Udiff;

   952                         U2 = U1;

   953                         U1 -= Udiff;

   954                     }

   955                     if (Udiff >= DoubleZigguratTables.exponentialConvexMargin) {

   956                         return x + extra;   // The chosen point is way below the curve; accept it.

   957                     }

   958                     // Compute the actual y-coordinate of the randomly chosen point.

   959                     double y = (Y[j] * 0x1.0p63) + ((Y[j] - Y[j-1]) * (double)U2);

   960                     // Now see how that y-coordinate compares to the curve

   961                     if (y <= Math.exp(-x)) {

   962                         return x + extra;   // The chosen point is below the curve; accept it.

   963                     }

   964                     // Otherwise, we reject this sample and have to try again.

   965                 }

   966             }

   967             // We are now committed to sampling from the tail.  We could do a recursive call

   968             // and then add X[0] but we save some time and stack space by using an iterative loop.

   969             extra += DoubleZigguratTables.exponentialX0;

   970             // This is like the first five lines of this method, but if it returns, it first adds "extra".

   971             U1 = rng.nextLong();

   972             i = U1 & DoubleZigguratTables.exponentialLayerMask;

   973             if (i < DoubleZigguratTables.exponentialNumberOfLayers) {

   974                 return DoubleZigguratTables.exponentialX[(int)i] * (U1 >>> 1) + extra;

   975             }

   976         }

   977     }

   978 

   979     // Implementation support for nextGaussian()

   980 

   981     static double computeNextGaussian(RandomGenerator rng) {

   982         long U1 = rng.nextLong();

   983         // Experimentation on a variety of machines indicates that it is overall much faster

   984         // to do the following & and < operations on longs rather than first cast U1 to int

   985         // (but then we need to cast to int before doing the array indexing operation).

   986         long i = U1 & DoubleZigguratTables.normalLayerMask;

   987 

   988         if (i < DoubleZigguratTables.normalNumberOfLayers) {

   989             // This is the fast path (occurring more than 98% of the time).  Make an early exit.

   990             return DoubleZigguratTables.normalX[(int)i] * U1;   // Note that the sign bit of U1 is used here.

   991         }

   992         // We didn't use the upper part of U1 after all.

   993         // Pull U1 apart into a sign bit and a 63-bit value for later use.

   994         double signBit = (U1 >= 0) ? 1.0 : -1.0;

   995         U1 = (U1 << 1) >>> 1;

   996 

   997         // Use Walker's alias method to sample an (unsigned) integer j from a discrete

   998         // probability distribution that includes the tail and all the ziggurat overhangs;

   999         // j will be less than DoubleZigguratTables.normalNumberOfLayers + 1.

  1000         long UA = rng.nextLong();

  1001         int j = (int)UA & DoubleZigguratTables.normalAliasMask;

  1002         if (UA >= DoubleZigguratTables.normalAliasThreshold[j]) {

  1003             j = DoubleZigguratTables.normalAliasMap[j] & DoubleZigguratTables.normalSignCorrectionMask;

  1004         }

  1005 

  1006         double x;

  1007         // Now the goal is to choose the result, which will be multiplied by signBit just before return.

  1008 

  1009         // There are four kinds of overhangs:

  1010         //

  1011         //  j == 0                          :  Sample from tail

  1012         //  0 < j < normalInflectionIndex   :  Overhang is convex; can reject upper-right triangle

  1013         //  j == normalInflectionIndex      :  Overhang includes the inflection point

  1014         //  j > normalInflectionIndex       :  Overhang is concave; can accept point in lower-left triangle

  1015         //

  1016         // Choose one of four loops to compute x, each specialized for a specific kind of overhang.

  1017         // Conditional statements are arranged such that the more likely outcomes are first.

  1018 

  1019         // In the three cases other than the tail case:

  1020         // U1 represents a fraction (scaled by 2**63) of the width of rectangle measured from the left.

  1021         // U2 represents a fraction (scaled by 2**63) of the height of rectangle measured from the top.

  1022         // Together they indicate a randomly chosen point within the rectangle.

  1023 

  1024         final double[] X = DoubleZigguratTables.normalX;

  1025         final double[] Y = DoubleZigguratTables.normalY;

  1026         if (j > DoubleZigguratTables.normalInflectionIndex) {   // Concave overhang

  1027             for (;; U1 = (rng.nextLong() >>> 1)) {

  1028                 long U2 = (rng.nextLong() >>> 1);

  1029                 // Compute the actual x-coordinate of the randomly chosen point.

  1030                 x = (X[j] * 0x1.0p63) + ((X[j-1] - X[j]) * (double)U1);

  1031                 // Does the point lie below the curve?

  1032                 long Udiff = U2 - U1;

  1033                 if (Udiff >= 0) {

  1034                     break;   // The chosen point is in the lower-left triangle; accept it.

  1035                 }

  1036                 if (Udiff <= -DoubleZigguratTables.normalConcaveMargin) {

  1037                     continue;   // The chosen point is way above the curve; reject it.

  1038                 }

  1039                 // Compute the actual y-coordinate of the randomly chosen point.

  1040                 double y = (Y[j] * 0x1.0p63) + ((Y[j] - Y[j-1]) * (double)U2);

  1041                 // Now see how that y-coordinate compares to the curve

  1042                 if (y <= Math.exp(-0.5*x*x)) {

  1043                     break;   // The chosen point is below the curve; accept it.

  1044                 }

  1045                 // Otherwise, we reject this sample and have to try again.

  1046             }

  1047         } else if (j == 0) {   // Tail

  1048             // Tail-sampling method of Marsaglia and Tsang.  See any one of:

  1049             // Marsaglia and Tsang. 1984. A fast, easily implemented method for sampling from decreasing

  1050             //    or symmetric unimodal density functions. SIAM J. Sci. Stat. Comput. 5, 349-359.

  1051             // Marsaglia and Tsang. 1998. The Monty Python method for generating random variables.

  1052             //    ACM Trans. Math. Softw. 24, 3 (September 1998), 341-350.  See page 342, step (4).

  1053             //    http://doi.org/10.1145/292395.292453

  1054             // Thomas, Luk, Leong, and Villasenor. 2007. Gaussian random number generators.

  1055             //    ACM Comput. Surv. 39, 4, Article 11 (November 2007).  See Algorithm 16.

  1056             //    http://doi.org/10.1145/1287620.1287622

  1057             // Compute two separate random exponential samples and then compare them in certain way.

  1058             do {

  1059                 x = (1.0 / DoubleZigguratTables.normalX0) * computeNextExponential(rng);

  1060             } while (computeNextExponential(rng) < 0.5*x*x);

  1061             x += DoubleZigguratTables.normalX0;

  1062         } else if (j < DoubleZigguratTables.normalInflectionIndex) {   // Convex overhang

  1063             for (;; U1 = (rng.nextLong() >>> 1)) {

  1064                 long U2 = (rng.nextLong() >>> 1);

  1065                 // Compute the actual x-coordinate of the randomly chosen point.

  1066                 x = (X[j] * 0x1.0p63) + ((X[j-1] - X[j]) * (double)U1);

  1067                 // Does the point lie below the curve?

  1068                 long Udiff = U2 - U1;

  1069                 if (Udiff < 0) {

  1070                     // We picked a point in the upper-right triangle.  None of those can be accepted.

  1071                     // So remap the point into the lower-left triangle and try that.

  1072                     // In effect, we swap U1 and U2, and invert the sign of Udiff.

  1073                     Udiff = -Udiff;

  1074                     U2 = U1;

  1075                     U1 -= Udiff;

  1076                 }

  1077                 if (Udiff >= DoubleZigguratTables.normalConvexMargin) {

  1078                     break;   // The chosen point is way below the curve; accept it.

  1079                 }

  1080                 // Compute the actual y-coordinate of the randomly chosen point.

  1081                 double y = (Y[j] * 0x1.0p63) + ((Y[j] - Y[j-1]) * (double)U2);

  1082                 // Now see how that y-coordinate compares to the curve

  1083                 if (y <= Math.exp(-0.5*x*x)) break; // The chosen point is below the curve; accept it.

  1084                 // Otherwise, we reject this sample and have to try again.

  1085             }

  1086         } else {

  1087             // The overhang includes the inflection point, so the curve is both convex and concave

  1088             for (;; U1 = (rng.nextLong() >>> 1)) {

  1089                 long U2 = (rng.nextLong() >>> 1);

  1090                 // Compute the actual x-coordinate of the randomly chosen point.

  1091                 x = (X[j] * 0x1.0p63) + ((X[j-1] - X[j]) * (double)U1);

  1092                 // Does the point lie below the curve?

  1093                 long Udiff = U2 - U1;

  1094                 if (Udiff >= DoubleZigguratTables.normalConvexMargin) {

  1095                     break;   // The chosen point is way below the curve; accept it.

  1096                 }

  1097                 if (Udiff <= -DoubleZigguratTables.normalConcaveMargin) {

  1098                     continue;   // The chosen point is way above the curve; reject it.

  1099                 }

  1100                 // Compute the actual y-coordinate of the randomly chosen point.

  1101                 double y = (Y[j] * 0x1.0p63) + ((Y[j] - Y[j-1]) * (double)U2);

  1102                 // Now see how that y-coordinate compares to the curve

  1103                 if (y <= Math.exp(-0.5*x*x)) {

  1104                     break;   // The chosen point is below the curve; accept it.

  1105                 }

  1106                 // Otherwise, we reject this sample and have to try again.

  1107             }

  1108         }

  1109         return signBit*x;

  1110     }

  1111 

  1112     /**

  1113      * This class overrides the stream-producing methods (such as {@code ints()})

  1114      * in class {@link AbstractGenerator} to provide {@link Spliterator}-based

  1115      * implmentations that support potentially parallel execution.

  1116      *

  1117      * To implement a pseudorandom number generator, the programmer needs

  1118      * only to extend this class and provide implementations for the methods

  1119      * {@code nextInt()}, {@code nextLong()}, {@code makeIntsSpliterator},

  1120      * {@code makeLongsSpliterator}, and {@code makeDoublesSpliterator}.

  1121      *

  1122      * This class is not public; it provides shared code to the public

  1123      * classes {@link AbstractSplittableGenerator}, {@link AbstractSharedGenerator},

  1124      * and {@link AbstractArbitrarilyJumpableGenerator}.

  1125      *

  1126      * @since 14

  1127      */

  1128     public abstract static class AbstractSpliteratorGenerator implements RandomGenerator {

  1129         /*

  1130          * Implementation Overview.

  1131          *

  1132          * This class provides most of the "user API" methods needed to

  1133          * satisfy the interface RandomGenerator.  An implementation of this

  1134          * interface need only extend this class and provide implementations

  1135          * of six methods: nextInt, nextLong, and nextDouble (the versions