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; 020 021/** 022 * <p>Utility library that supplements the standard {@link Random} class.</p> 023 * 024 * @since 3.3 025 * 026 * @version $Id: RandomUtils.java 1606051 2014-06-27 12:22:17Z ggregory $ 027 */ 028public class RandomUtils { 029 030 /** 031 * Random object used by random method. This has to be not local to the 032 * random method so as to not return the same value in the same millisecond. 033 */ 034 private static final Random RANDOM = new Random(); 035 036 /** 037 * <p> 038 * {@code RandomUtils} instances should NOT be constructed in standard 039 * programming. Instead, the class should be used as 040 * {@code RandomUtils.nextBytes(5);}. 041 * </p> 042 * 043 * <p> 044 * This constructor is public to permit tools that require a JavaBean 045 * instance to operate. 046 * </p> 047 */ 048 public RandomUtils() { 049 super(); 050 } 051 052 /** 053 * <p> 054 * Creates an array of random bytes. 055 * </p> 056 * 057 * @param count 058 * the size of the returned array 059 * @return the random byte array 060 * @throws IllegalArgumentException if {@code count} is negative 061 */ 062 public static byte[] nextBytes(final int count) { 063 Validate.isTrue(count >= 0, "Count cannot be negative."); 064 065 final byte[] result = new byte[count]; 066 RANDOM.nextBytes(result); 067 return result; 068 } 069 070 /** 071 * <p> 072 * Returns a random integer within the specified range. 073 * </p> 074 * 075 * @param startInclusive 076 * the smallest value that can be returned, must be non-negative 077 * @param endExclusive 078 * the upper bound (not included) 079 * @throws IllegalArgumentException 080 * if {@code startInclusive > endExclusive} or if 081 * {@code startInclusive} is negative 082 * @return the random integer 083 */ 084 public static int nextInt(final int startInclusive, final int endExclusive) { 085 Validate.isTrue(endExclusive >= startInclusive, 086 "Start value must be smaller or equal to end value."); 087 Validate.isTrue(startInclusive >= 0, "Both range values must be non-negative."); 088 089 if (startInclusive == endExclusive) { 090 return startInclusive; 091 } 092 093 return startInclusive + RANDOM.nextInt(endExclusive - startInclusive); 094 } 095 096 /** 097 * <p> 098 * Returns a random long within the specified range. 099 * </p> 100 * 101 * @param startInclusive 102 * the smallest value that can be returned, must be non-negative 103 * @param endExclusive 104 * the upper bound (not included) 105 * @throws IllegalArgumentException 106 * if {@code startInclusive > endExclusive} or if 107 * {@code startInclusive} is negative 108 * @return the random long 109 */ 110 public static long nextLong(final long startInclusive, final long endExclusive) { 111 Validate.isTrue(endExclusive >= startInclusive, 112 "Start value must be smaller or equal to end value."); 113 Validate.isTrue(startInclusive >= 0, "Both range values must be non-negative."); 114 115 if (startInclusive == endExclusive) { 116 return startInclusive; 117 } 118 119 return (long) nextDouble(startInclusive, endExclusive); 120 } 121 122 123 /** 124 * <p> 125 * Returns a random double within the specified range. 126 * </p> 127 * 128 * @param startInclusive 129 * the smallest value that can be returned, must be non-negative 130 * @param endInclusive 131 * the upper bound (included) 132 * @throws IllegalArgumentException 133 * if {@code startInclusive > endInclusive} or if 134 * {@code startInclusive} is negative 135 * @return the random double 136 */ 137 public static double nextDouble(final double startInclusive, final double endInclusive) { 138 Validate.isTrue(endInclusive >= startInclusive, 139 "Start value must be smaller or equal to end value."); 140 Validate.isTrue(startInclusive >= 0, "Both range values must be non-negative."); 141 142 if (startInclusive == endInclusive) { 143 return startInclusive; 144 } 145 146 return startInclusive + ((endInclusive - startInclusive) * RANDOM.nextDouble()); 147 } 148 149 /** 150 * <p> 151 * Returns a random float within the specified range. 152 * </p> 153 * 154 * @param startInclusive 155 * the smallest value that can be returned, must be non-negative 156 * @param endInclusive 157 * the upper bound (included) 158 * @throws IllegalArgumentException 159 * if {@code startInclusive > endInclusive} or if 160 * {@code startInclusive} is negative 161 * @return the random float 162 */ 163 public static float nextFloat(final float startInclusive, final float endInclusive) { 164 Validate.isTrue(endInclusive >= startInclusive, 165 "Start value must be smaller or equal to end value."); 166 Validate.isTrue(startInclusive >= 0, "Both range values must be non-negative."); 167 168 if (startInclusive == endInclusive) { 169 return startInclusive; 170 } 171 172 return startInclusive + ((endInclusive - startInclusive) * RANDOM.nextFloat()); 173 } 174}