    001    /*
    002     * Licensed to the Apache Software Foundation (ASF) under one
    003     * or more contributor license agreements.  See the NOTICE file
    004     * distributed with this work for additional information
    005     * regarding copyright ownership.  The ASF licenses this file
    006     * to you under the Apache License, Version 2.0 (the
    007     * "License"); you may not use this file except in compliance
    008     * with the License.  You may obtain a copy of the License at
    009     *
    010     * http://www.apache.org/licenses/LICENSE-2.0
    011     *
    012     * Unless required by applicable law or agreed to in writing,
    013     * software distributed under the License is distributed on an
    014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    015     * KIND, either express or implied.  See the License for the
    016     * specific language governing permissions and limitations
    017     * under the License.
    018     */
    019    package org.apache.commons.lang.math;
    020
    021    import java.util.Random;
    022
    023    /**
    024     * <p><code>RandomUtils</code> is a wrapper that supports all possible
    025     * {@link java.util.Random} methods via the {@link java.lang.Math#random()}
    026     * method and its system-wide <code>Random</code> object.
    027     *
    028     * @author Gary D. Gregory
    029     * @since 2.0
    030     * @version $Id: RandomUtils.java 906320 2010-02-04 01:41:10Z sebb $
    031     */
    032    public class RandomUtils {
    033
    034        /**
    035         * An instance of {@link JVMRandom}.
    036         */
    037        public static final Random JVM_RANDOM = new JVMRandom();
    038
    039    // should be possible for JVM_RANDOM?
    040    //    public static void nextBytes(byte[]) {
    041    //    public synchronized double nextGaussian();
    042    //    }
    043
    044        /**
    045         * <p>Returns the next pseudorandom, uniformly distributed int value
    046         * from the Math.random() sequence.</p>
    047         * <b>N.B. All values are >= 0.<b>
    048         * @return the random int
    049         */
    050        public static int nextInt() {
    051            return nextInt(JVM_RANDOM);
    052        }
    053
    054        /**
    055         * <p>Returns the next pseudorandom, uniformly distributed int value
    056         * from the given <code>random</code> sequence.</p>
    057         *
    058         * @param random the Random sequence generator.
    059         * @return the random int
    060         */
    061        public static int nextInt(Random random) {
    062            return random.nextInt();
    063        }
    064
    065        /**
    066         * <p>Returns a pseudorandom, uniformly distributed int value
    067         * between <code>0</code> (inclusive) and the specified value
    068         * (exclusive), from the Math.random() sequence.</p>
    069         *
    070         * @param n  the specified exclusive max-value
    071         * @return the random int
    072         */
    073        public static int nextInt(int n) {
    074            return nextInt(JVM_RANDOM, n);
    075        }
    076
    077        /**
    078         * <p>Returns a pseudorandom, uniformly distributed int value
    079         * between <code>0</code> (inclusive) and the specified value
    080         * (exclusive), from the given Random sequence.</p>
    081         *
    082         * @param random the Random sequence generator.
    083         * @param n  the specified exclusive max-value
    084         * @return the random int
    085         */
    086        public static int nextInt(Random random, int n) {
    087            // check this cannot return 'n'
    088            return random.nextInt(n);
    089        }
    090
    091        /**
    092         * <p>Returns the next pseudorandom, uniformly distributed long value
    093         * from the Math.random() sequence.</p>
    094         * <b>N.B. All values are >= 0.<b>
    095         * @return the random long
    096         */
    097        public static long nextLong() {
    098            return nextLong(JVM_RANDOM);
    099        }
    100
    101        /**
    102         * <p>Returns the next pseudorandom, uniformly distributed long value
    103         * from the given Random sequence.</p>
    104         *
    105         * @param random the Random sequence generator.
    106         * @return the random long
    107         */
    108        public static long nextLong(Random random) {
    109            return random.nextLong();
    110        }
    111
    112        /**
    113         * <p>Returns the next pseudorandom, uniformly distributed boolean value
    114         * from the Math.random() sequence.</p>
    115         *
    116         * @return the random boolean
    117         */
    118        public static boolean nextBoolean() {
    119            return nextBoolean(JVM_RANDOM);
    120        }
    121
    122        /**
    123         * <p>Returns the next pseudorandom, uniformly distributed boolean value
    124         * from the given random sequence.</p>
    125         *
    126         * @param random the Random sequence generator.
    127         * @return the random boolean
    128         */
    129        public static boolean nextBoolean(Random random) {
    130            return random.nextBoolean();
    131        }
    132
    133        /**
    134         * <p>Returns the next pseudorandom, uniformly distributed float value
    135         * between <code>0.0</code> and <code>1.0</code> from the Math.random()
    136         * sequence.</p>
    137         *
    138         * @return the random float
    139         */
    140        public static float nextFloat() {
    141            return nextFloat(JVM_RANDOM);
    142        }
    143
    144        /**
    145         * <p>Returns the next pseudorandom, uniformly distributed float value
    146         * between <code>0.0</code> and <code>1.0</code> from the given Random
    147         * sequence.</p>
    148         *
    149         * @param random the Random sequence generator.
    150         * @return the random float
    151         */
    152        public static float nextFloat(Random random) {
    153            return random.nextFloat();
    154        }
    155
    156        /**
    157         * <p>Returns the next pseudorandom, uniformly distributed float value
    158         * between <code>0.0</code> and <code>1.0</code> from the Math.random()
    159         * sequence.</p>
    160         *
    161         * @return the random double
    162         */
    163        public static double nextDouble() {
    164            return nextDouble(JVM_RANDOM);
    165        }
    166
    167        /**
    168         * <p>Returns the next pseudorandom, uniformly distributed float value
    169         * between <code>0.0</code> and <code>1.0</code> from the given Random
    170         * sequence.</p>
    171         *
    172         * @param random the Random sequence generator.
    173         * @return the random double
    174         */
    175        public static double nextDouble(Random random) {
    176            return random.nextDouble();
    177        }
    178
    179    }