org.apache.commons.math.random
Interface RandomData

All Known Implementing Classes:

RandomDataImpl

public interface RandomData

Random data generation utilities.

Version:

$Revision: 780975 $ $Date: 2009-06-02 11:05:37 +0200 (mar. 02 juin 2009) $

Method Summary

double	nextExponential(double mean) Generates a random value from the exponential distribution with expected value = mean.
double	nextGaussian(double mu, double sigma) Generates a random value from the Normal (or Gaussian) distribution with the given mean and standard deviation.
String	nextHexString(int len) Generates a random string of hex characters of length len.
int	nextInt(int lower, int upper) Generates a uniformly distributed random integer between lower and upper (endpoints included).
long	nextLong(long lower, long upper) Generates a uniformly distributed random long integer between lower and upper (endpoints included).
int[]	nextPermutation(int n, int k) Generates an integer array of length k whose entries are selected randomly, without repetition, from the integers 0 through n-1 (inclusive).
long	nextPoisson(double mean) Generates a random value from the Poisson distribution with the given mean.
Object[]	nextSample(Collection<?> c, int k) Returns an array of k objects selected randomly from the Collection c.
String	nextSecureHexString(int len) Generates a random string of hex characters from a secure random sequence.
int	nextSecureInt(int lower, int upper) Generates a uniformly distributed random integer between lower and upper (endpoints included) from a secure random sequence.
long	nextSecureLong(long lower, long upper) Generates a random long integer between lower and upper (endpoints included).
double	nextUniform(double lower, double upper) Generates a uniformly distributed random value from the open interval (lower,upper) (i.e., endpoints excluded).

Method Detail

nextHexString

String nextHexString(int len)

Generates a random string of hex characters of length len.

The generated string will be random, but not cryptographically secure. To generate cryptographically secure strings, use nextSecureHexString

Preconditions:

• len > 0 (otherwise an IllegalArgumentException is thrown.)

Parameters:

len - the length of the string to be generated

Returns:

random string of hex characters of length len

nextInt

int nextInt(int lower,
            int upper)

Generates a uniformly distributed random integer between lower and upper (endpoints included).

The generated integer will be random, but not cryptographically secure. To generate cryptographically secure integer sequences, use nextSecureInt.

Preconditions:

• lower < upper (otherwise an IllegalArgumentException is thrown.)

Parameters:

lower - lower bound for generated integer

upper - upper bound for generated integer

Returns:

a random integer greater than or equal to lower and less than or equal to upper.

nextLong

long nextLong(long lower,
              long upper)

Generates a uniformly distributed random long integer between lower and upper (endpoints included).

The generated long integer values will be random, but not cryptographically secure. To generate cryptographically secure sequences of longs, use nextSecureLong

Preconditions:

• lower < upper (otherwise an IllegalArgumentException is thrown.)

Parameters:

lower - lower bound for generated integer

upper - upper bound for generated integer

Returns:

a random integer greater than or equal to lower and less than or equal to upper.

nextSecureHexString

String nextSecureHexString(int len)

Generates a random string of hex characters from a secure random sequence.

If cryptographic security is not required, use nextHexString().

Preconditions:

• len > 0 (otherwise an IllegalArgumentException is thrown.)

Parameters:

len - length of return string

Returns:

the random hex string

nextSecureInt

int nextSecureInt(int lower,
                  int upper)

Generates a uniformly distributed random integer between lower and upper (endpoints included) from a secure random sequence.

Sequences of integers generated using this method will be cryptographically secure. If cryptographic security is not required, nextInt should be used instead of this method.

Definition: Secure Random Sequence

Preconditions:

• lower < upper (otherwise an IllegalArgumentException is thrown.)

Parameters:

lower - lower bound for generated integer

upper - upper bound for generated integer

Returns:

a random integer greater than or equal to lower and less than or equal to upper.

nextSecureLong

long nextSecureLong(long lower,
                    long upper)

Generates a random long integer between lower and upper (endpoints included).

Sequences of long values generated using this method will be cryptographically secure. If cryptographic security is not required, nextLong should be used instead of this method.

Definition: Secure Random Sequence

Preconditions:

• lower < upper (otherwise an IllegalArgumentException is thrown.)

Parameters:

lower - lower bound for generated integer

upper - upper bound for generated integer

Returns:

a long integer greater than or equal to lower and less than or equal to upper.

nextPoisson

long nextPoisson(double mean)

Generates a random value from the Poisson distribution with the given mean.

Definition: Poisson Distribution

Preconditions:

• The specified mean must be positive (otherwise an IllegalArgumentException is thrown.)

Parameters:

mean - Mean of the distribution

Returns:

poisson deviate with the specified mean

nextGaussian

double nextGaussian(double mu,
                    double sigma)

Generates a random value from the Normal (or Gaussian) distribution with the given mean and standard deviation.

Definition: Normal Distribution

Preconditions:

• sigma > 0 (otherwise an IllegalArgumentException is thrown.)

Parameters:

mu - Mean of the distribution

sigma - Standard deviation of the distribution

Returns:

random value from Gaussian distribution with mean = mu, standard deviation = sigma

nextExponential

double nextExponential(double mean)

Generates a random value from the exponential distribution with expected value = mean.

Definition: Exponential Distribution

Preconditions:

• mu >= 0 (otherwise an IllegalArgumentException is thrown.)

Parameters:

mean - Mean of the distribution

Returns:

random value from exponential distribution

nextUniform

double nextUniform(double lower,
                   double upper)

Generates a uniformly distributed random value from the open interval (lower,upper) (i.e., endpoints excluded).

Definition: Uniform Distribution lower and upper - lower are the location and scale parameters, respectively.

Preconditions:

• lower < upper (otherwise an IllegalArgumentException is thrown.)

Parameters:

lower - lower endpoint of the interval of support

upper - upper endpoint of the interval of support

Returns:

uniformly distributed random value between lower and upper (exclusive)

nextPermutation

int[] nextPermutation(int n,
                      int k)

Generates an integer array of length k whose entries are selected randomly, without repetition, from the integers 0 through n-1 (inclusive).

Generated arrays represent permutations of n taken k at a time.

Preconditions:

• k <= n
• n > 0

If the preconditions are not met, an IllegalArgumentException is thrown.

Parameters:

n - domain of the permutation

k - size of the permutation

Returns:

random k-permutation of n

nextSample

Object[] nextSample(Collection<?> c,
                    int k)

Returns an array of k objects selected randomly from the Collection c.

Sampling from c is without replacement; but if c contains identical objects, the sample may include repeats. If all elements of c are distinct, the resulting object array represents a Simple Random Sample of size k from the elements of c.

Preconditions:

• k must be less than or equal to the size of c
• c must not be empty

If the preconditions are not met, an IllegalArgumentException is thrown.

Parameters:

c - collection to be sampled

k - size of the sample

Returns:

random sample of k elements from c