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
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `java.lang.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.
    `java.lang.Object[]` | `nextSample(java.util.Collection<?> c, int k)` Returns an array of `k` objects selected randomly from the Collection `c`.
    `java.lang.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

          java.lang.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

          java.lang.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

          java.lang.Object[] nextSample(java.util.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

Copyright (c) 2003-2013 Apache Software Foundation