    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *     http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.lang3;
    018
    019import java.util.Random;
    020import java.util.concurrent.ThreadLocalRandom;
    021
    022/**
    023 * Utility library that supplements the standard {@link Random} class.
    024 *
    025 * <p>Caveat: Instances of {@link Random} are not cryptographically secure.</p>
    026 *
    027 * <p>Please note that the Apache Commons project provides a component
    028 * dedicated to pseudo-random number generation, namely
    029 * <a href="https://commons.apache.org/proper/commons-rng/">Commons RNG</a>, that may be
    030 * a better choice for applications with more stringent requirements
    031 * (performance and/or correctness).</p>
    032 *
    033 * @deprecated Use Apache Commons RNG's optimized <a href="https://commons.apache.org/proper/commons-rng/commons-rng-client-api/apidocs/org/apache/commons/rng/UniformRandomProvider.html">UniformRandomProvider</a>
    034 * @since 3.3
    035 */
    036@Deprecated
    037public class RandomUtils {
    038
    039    /**
    040     * Generates a random boolean value.
    041     *
    042     * @return the random boolean
    043     * @since 3.5
    044     */
    045    public static boolean nextBoolean() {
    046        return random().nextBoolean();
    047    }
    048
    049    /**
    050     * Generates an array of random bytes.
    051     *
    052     * @param count
    053     *            the size of the returned array
    054     * @return the random byte array
    055     * @throws IllegalArgumentException if {@code count} is negative
    056     */
    057    public static byte[] nextBytes(final int count) {
    058        Validate.isTrue(count >= 0, "Count cannot be negative.");
    059
    060        final byte[] result = new byte[count];
    061        random().nextBytes(result);
    062        return result;
    063    }
    064
    065    /**
    066     * Generates a random double between 0 (inclusive) and Double.MAX_VALUE (exclusive).
    067     *
    068     * @return the random double
    069     * @see #nextDouble(double, double)
    070     * @since 3.5
    071     */
    072    public static double nextDouble() {
    073        return nextDouble(0, Double.MAX_VALUE);
    074    }
    075
    076    /**
    077     * Generates a random double within the specified range.
    078     *
    079     * @param startInclusive
    080     *            the smallest value that can be returned, must be non-negative
    081     * @param endExclusive
    082     *            the upper bound (not included)
    083     * @throws IllegalArgumentException
    084     *             if {@code startInclusive > endExclusive} or if
    085     *             {@code startInclusive} is negative
    086     * @return the random double
    087     */
    088    public static double nextDouble(final double startInclusive, final double endExclusive) {
    089        Validate.isTrue(endExclusive >= startInclusive,
    090                "Start value must be smaller or equal to end value.");
    091        Validate.isTrue(startInclusive >= 0, "Both range values must be non-negative.");
    092
    093        if (startInclusive == endExclusive) {
    094            return startInclusive;
    095        }
    096
    097        return startInclusive + ((endExclusive - startInclusive) * random().nextDouble());
    098    }
    099
    100    /**
    101     * Generates a random float between 0 (inclusive) and Float.MAX_VALUE (exclusive).
    102     *
    103     * @return the random float
    104     * @see #nextFloat(float, float)
    105     * @since 3.5
    106     */
    107    public static float nextFloat() {
    108        return nextFloat(0, Float.MAX_VALUE);
    109    }
    110
    111    /**
    112     * Generates a random float within the specified range.
    113     *
    114     * @param startInclusive
    115     *            the smallest value that can be returned, must be non-negative
    116     * @param endExclusive
    117     *            the upper bound (not included)
    118     * @throws IllegalArgumentException
    119     *             if {@code startInclusive > endExclusive} or if
    120     *             {@code startInclusive} is negative
    121     * @return the random float
    122     */
    123    public static float nextFloat(final float startInclusive, final float endExclusive) {
    124        Validate.isTrue(endExclusive >= startInclusive,
    125                "Start value must be smaller or equal to end value.");
    126        Validate.isTrue(startInclusive >= 0, "Both range values must be non-negative.");
    127
    128        if (startInclusive == endExclusive) {
    129            return startInclusive;
    130        }
    131
    132        return startInclusive + ((endExclusive - startInclusive) * random().nextFloat());
    133    }
    134
    135    /**
    136     * Generates a random int between 0 (inclusive) and Integer.MAX_VALUE (exclusive).
    137     *
    138     * @return the random integer
    139     * @see #nextInt(int, int)
    140     * @since 3.5
    141     */
    142    public static int nextInt() {
    143        return nextInt(0, Integer.MAX_VALUE);
    144    }
    145
    146    /**
    147     * Generates a random integer within the specified range.
    148     *
    149     * @param startInclusive
    150     *            the smallest value that can be returned, must be non-negative
    151     * @param endExclusive
    152     *            the upper bound (not included)
    153     * @throws IllegalArgumentException
    154     *             if {@code startInclusive > endExclusive} or if
    155     *             {@code startInclusive} is negative
    156     * @return the random integer
    157     */
    158    public static int nextInt(final int startInclusive, final int endExclusive) {
    159        Validate.isTrue(endExclusive >= startInclusive,
    160                "Start value must be smaller or equal to end value.");
    161        Validate.isTrue(startInclusive >= 0, "Both range values must be non-negative.");
    162
    163        if (startInclusive == endExclusive) {
    164            return startInclusive;
    165        }
    166
    167        return startInclusive + random().nextInt(endExclusive - startInclusive);
    168    }
    169
    170    /**
    171     * Generates a random long between 0 (inclusive) and Long.MAX_VALUE (exclusive).
    172     *
    173     * @return the random long
    174     * @see #nextLong(long, long)
    175     * @since 3.5
    176     */
    177    public static long nextLong() {
    178        return nextLong(Long.MAX_VALUE);
    179    }
    180
    181    /**
    182     * Generates a {@code long} value between 0 (inclusive) and the specified
    183     * value (exclusive).
    184     *
    185     * @param n Bound on the random number to be returned.  Must be positive.
    186     * @return a random {@code long} value between 0 (inclusive) and {@code n}
    187     * (exclusive).
    188     */
    189    private static long nextLong(final long n) {
    190        // Extracted from o.a.c.rng.core.BaseProvider.nextLong(long)
    191        long bits;
    192        long val;
    193        do {
    194            bits = random().nextLong() >>> 1;
    195            val  = bits % n;
    196        } while (bits - val + (n - 1) < 0);
    197
    198        return val;
    199    }
    200
    201    /**
    202     * Generates a random long within the specified range.
    203     *
    204     * @param startInclusive
    205     *            the smallest value that can be returned, must be non-negative
    206     * @param endExclusive
    207     *            the upper bound (not included)
    208     * @throws IllegalArgumentException
    209     *             if {@code startInclusive > endExclusive} or if
    210     *             {@code startInclusive} is negative
    211     * @return the random long
    212     */
    213    public static long nextLong(final long startInclusive, final long endExclusive) {
    214        Validate.isTrue(endExclusive >= startInclusive,
    215                "Start value must be smaller or equal to end value.");
    216        Validate.isTrue(startInclusive >= 0, "Both range values must be non-negative.");
    217
    218        if (startInclusive == endExclusive) {
    219            return startInclusive;
    220        }
    221
    222        return startInclusive + nextLong(endExclusive - startInclusive);
    223    }
    224
    225    private static ThreadLocalRandom random() {
    226        return ThreadLocalRandom.current();
    227    }
    228
    229    /**
    230     * {@link RandomUtils} instances should NOT be constructed in standard
    231     * programming. Instead, the class should be used as
    232     * {@code RandomUtils.nextBytes(5);}.
    233     * <p>
    234     * This constructor is public to permit tools that require a JavaBean
    235     * instance to operate.
    236     * </p>
    237     */
    238    public RandomUtils() {
    239    }
    240}