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

Methods
`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