public final class StdRandom extends Object
Overview.
The StdRandom
class provides static methods for generating
random number from various discrete and continuous distributions,
including uniform, Bernoulli, geometric, Gaussian, exponential, Pareto,
Poisson, and Cauchy. It also provides method for shuffling an
array or subarray and generating random permutations.
Conventions.
By convention, all intervals are half open. For example,
uniformDouble(-1.0, 1.0)
returns a random number between
-1.0
(inclusive) and 1.0
(exclusive).
Similarly, shuffle(a, lo, hi)
shuffles the hi - lo
elements in the array a[]
, starting at index lo
(inclusive) and ending at index hi
(exclusive).
Performance. The methods all take constant expected time, except those that involve arrays. The shuffle method takes time linear in the subarray to be shuffled; the discrete methods take time linear in the length of the argument array.
Additional information. For additional documentation, see Section 2.2 of Computer Science: An Interdisciplinary Approach by Robert Sedgewick and Kevin Wayne.
Modifier and Type | Method and Description |
---|---|
static boolean |
bernoulli()
Returns a random boolean from a Bernoulli distribution with success
probability 1/2.
|
static boolean |
bernoulli(double p)
Returns a random boolean from a Bernoulli distribution with success
probability p.
|
static double |
cauchy()
Returns a random real number from the Cauchy distribution.
|
static int |
discrete(double[] probabilities)
Returns a random integer from the specified discrete distribution.
|
static int |
discrete(int[] frequencies)
Returns a random integer from the specified discrete distribution.
|
static double |
exp(double lambda)
Returns a random real number from an exponential distribution
with rate λ.
|
static double |
gaussian()
Returns a random real number from a standard Gaussian distribution.
|
static double |
gaussian(double mu,
double sigma)
Returns a random real number from a Gaussian distribution with mean μ
and standard deviation σ.
|
static int |
geometric(double p)
Returns a random integer from a geometric distribution with success
probability p.
|
static long |
getSeed()
Returns the seed of the pseudo-random number generator.
|
static void |
main(String[] args)
Unit tests the methods in this class.
|
static double |
pareto()
Returns a random real number from the standard Pareto distribution.
|
static double |
pareto(double alpha)
Returns a random real number from a Pareto distribution with
shape parameter α.
|
static int[] |
permutation(int n)
Returns a uniformly random permutation of n elements.
|
static int[] |
permutation(int n,
int k)
Returns a uniformly random permutation of k of n elements.
|
static int |
poisson(double lambda)
Returns a random integer from a Poisson distribution with mean λ.
|
static double |
random()
Deprecated.
Replaced by
uniformDouble() . |
static void |
setSeed(long s)
Sets the seed of the pseudo-random number generator.
|
static void |
shuffle(char[] a)
Rearranges the elements of the specified array in uniformly random order.
|
static void |
shuffle(double[] a)
Rearranges the elements of the specified array in uniformly random order.
|
static void |
shuffle(double[] a,
int lo,
int hi)
Rearranges the elements of the specified subarray in uniformly random order.
|
static void |
shuffle(int[] a)
Rearranges the elements of the specified array in uniformly random order.
|
static void |
shuffle(int[] a,
int lo,
int hi)
Rearranges the elements of the specified subarray in uniformly random order.
|
static void |
shuffle(Object[] a)
Rearranges the elements of the specified array in uniformly random order.
|
static void |
shuffle(Object[] a,
int lo,
int hi)
Rearranges the elements of the specified subarray in uniformly random order.
|
static double |
uniform()
Deprecated.
Replaced by
uniformDouble() . |
static double |
uniform(double a,
double b)
Deprecated.
Replaced by
uniformDouble(double a, double b) . |
static int |
uniform(int n)
Deprecated.
Replaced by
uniformInt(int n) . |
static int |
uniform(int a,
int b)
Deprecated.
Replaced by
uniformInt(int a, int b) . |
static long |
uniform(long n)
Deprecated.
Replaced by
uniformLong(long n) . |
static double |
uniformDouble()
Returns a random real number uniformly in [0, 1).
|
static double |
uniformDouble(double a,
double b)
Returns a random real number uniformly in [a, b).
|
static int |
uniformInt(int n)
Returns a random integer uniformly in [0, n).
|
static int |
uniformInt(int a,
int b)
Returns a random integer uniformly in [a, b).
|
static long |
uniformLong(long n)
Returns a random long integer uniformly in [0, n).
|
public static void setSeed(long s)
s
- the seedpublic static long getSeed()
@Deprecated public static double uniform()
uniformDouble()
.public static double uniformDouble()
@Deprecated public static int uniform(int n)
uniformInt(int n)
.n
- number of possible integersn
(exclusive)IllegalArgumentException
- if n <= 0
public static int uniformInt(int n)
n
- number of possible integersn
(exclusive)IllegalArgumentException
- if n <= 0
@Deprecated public static long uniform(long n)
uniformLong(long n)
.n
- number of possible long
integersn
(exclusive)IllegalArgumentException
- if n <= 0
public static long uniformLong(long n)
n
- number of possible long
integersn
(exclusive)IllegalArgumentException
- if n <= 0
@Deprecated public static double random()
uniformDouble()
.@Deprecated public static int uniform(int a, int b)
uniformInt(int a, int b)
.a
- the left endpointb
- the right endpointIllegalArgumentException
- if b <= a
IllegalArgumentException
- if b - a >= Integer.MAX_VALUE
public static int uniformInt(int a, int b)
a
- the left endpointb
- the right endpointIllegalArgumentException
- if b <= a
IllegalArgumentException
- if b - a >= Integer.MAX_VALUE
@Deprecated public static double uniform(double a, double b)
uniformDouble(double a, double b)
.a
- the left endpointb
- the right endpointIllegalArgumentException
- unless a < b
public static double uniformDouble(double a, double b)
a
- the left endpointb
- the right endpointIllegalArgumentException
- unless a < b
public static boolean bernoulli(double p)
p
- the probability of returning true
true
with probability p
and
false
with probability 1 - p
IllegalArgumentException
- unless 0
≤ p
≤ 1.0
public static boolean bernoulli()
true
with probability 1/2 and
false
with probability 1/2public static double gaussian()
public static double gaussian(double mu, double sigma)
mu
- the meansigma
- the standard deviationmu
and standard deviation sigma
public static int geometric(double p)
p
- the parameter of the geometric distributionp
; or Integer.MAX_VALUE
if
p
is (nearly) equal to 1.0
.IllegalArgumentException
- unless p >= 0.0
and p <= 1.0
public static int poisson(double lambda)
lambda
- the mean of the Poisson distributionlambda
IllegalArgumentException
- unless lambda > 0.0
and not infinitepublic static double pareto()
public static double pareto(double alpha)
alpha
- shape parameteralpha
IllegalArgumentException
- unless alpha > 0.0
public static double cauchy()
public static int discrete(double[] probabilities)
probabilities
- the probability of occurrence of each integeri
with probability probabilities[i]
IllegalArgumentException
- if probabilities
is null
IllegalArgumentException
- if sum of array entries is not (very nearly) equal to 1.0
IllegalArgumentException
- unless probabilities[i] >= 0.0
for each index i
public static int discrete(int[] frequencies)
frequencies
- the frequency of occurrence of each integeri
with probability proportional to frequencies[i]
IllegalArgumentException
- if frequencies
is null
IllegalArgumentException
- if all array entries are 0
IllegalArgumentException
- if frequencies[i]
is negative for any index i
IllegalArgumentException
- if sum of frequencies exceeds Integer.MAX_VALUE
(231 - 1)public static double exp(double lambda)
lambda
- the rate of the exponential distributionlambda
IllegalArgumentException
- unless lambda > 0.0
public static void shuffle(Object[] a)
a
- the array to shuffleIllegalArgumentException
- if a
is null
public static void shuffle(double[] a)
a
- the array to shuffleIllegalArgumentException
- if a
is null
public static void shuffle(int[] a)
a
- the array to shuffleIllegalArgumentException
- if a
is null
public static void shuffle(char[] a)
a
- the array to shuffleIllegalArgumentException
- if a
is null
public static void shuffle(Object[] a, int lo, int hi)
a
- the array to shufflelo
- the left endpoint (inclusive)hi
- the right endpoint (exclusive)IllegalArgumentException
- if a
is null
IllegalArgumentException
- unless (0 <= lo) && (lo < hi) && (hi <= a.length)
public static void shuffle(double[] a, int lo, int hi)
a
- the array to shufflelo
- the left endpoint (inclusive)hi
- the right endpoint (exclusive)IllegalArgumentException
- if a
is null
IllegalArgumentException
- unless (0 <= lo) && (lo < hi) && (hi <= a.length)
public static void shuffle(int[] a, int lo, int hi)
a
- the array to shufflelo
- the left endpoint (inclusive)hi
- the right endpoint (exclusive)IllegalArgumentException
- if a
is null
IllegalArgumentException
- unless (0 <= lo) && (lo < hi) && (hi <= a.length)
public static int[] permutation(int n)
n
- number of elementsn
that is a uniformly random permutation
of 0
, 1
, ..., n-1
IllegalArgumentException
- if n
is negativepublic static int[] permutation(int n, int k)
n
- number of elementsk
- number of elements to selectk
that is a uniformly random permutation
of k
of the elements from 0
, 1
, ..., n-1
IllegalArgumentException
- if n
is negativeIllegalArgumentException
- unless 0 <= k <= n
public static void main(String[] args)
args
- the command-line arguments