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}