/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.commons.math3.random;
import java.util.Collection;

import org.apache.commons.math3.exception.NotANumberException;
import org.apache.commons.math3.exception.NotFiniteNumberException;
import org.apache.commons.math3.exception.NotStrictlyPositiveException;
import org.apache.commons.math3.exception.NumberIsTooLargeException;

Random data generation utilities.
Deprecated:
to be removed in 4.0. Use RandomDataGenerator directly/**
 * Random data generation utilities.
 * @deprecated to be removed in 4.0.  Use {@link RandomDataGenerator} directly
 */
@Deprecated
public interface RandomData {
    
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(int). 
Params:
len – the length of the string to be generated
Throws:
NotStrictlyPositiveException –  if len <= 0
Returns:
a random string of hex characters of length len/**
     * Generates a random string of hex characters of length {@code len}.
     * <p>
     * The generated string will be random, but not cryptographically
     * secure. To generate cryptographically secure strings, use
     * {@link #nextSecureHexString(int)}.
     * </p>
     *
     * @param len the length of the string to be generated
     * @return a random string of hex characters of length {@code len}
     * @throws NotStrictlyPositiveException
     * if {@code len <= 0}
     */
    String nextHexString(int len) throws NotStrictlyPositiveException;

    
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(int, int). 
Params:
lower – lower bound for generated integer
upper – upper bound for generated integer
Throws:
NumberIsTooLargeException – if lower >= upper
Returns:
a random integer greater than or equal to lower and less than or equal to upper/**
     * Generates a uniformly distributed random integer between {@code lower}
     * and {@code upper} (endpoints included).
     * <p>
     * The generated integer will be random, but not cryptographically secure.
     * To generate cryptographically secure integer sequences, use
     * {@link #nextSecureInt(int, int)}.
     * </p>
     *
     * @param lower lower bound for generated integer
     * @param upper upper bound for generated integer
     * @return a random integer greater than or equal to {@code lower}
     * and less than or equal to {@code upper}
     * @throws NumberIsTooLargeException if {@code lower >= upper}
     */
    int nextInt(int lower, int upper) throws NumberIsTooLargeException;

    
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(long, long). 
Params:
lower – lower bound for generated long integer
upper – upper bound for generated long integer
Throws:
NumberIsTooLargeException – if lower >= upper
Returns:
a random long integer greater than or equal to lower and less than or equal to upper/**
     * Generates a uniformly distributed random long integer between
     * {@code lower} and {@code upper} (endpoints included).
     * <p>
     * The generated long integer values will be random, but not
     * cryptographically secure. To generate cryptographically secure sequences
     * of longs, use {@link #nextSecureLong(long, long)}.
     * </p>
     *
     * @param lower lower bound for generated long integer
     * @param upper upper bound for generated long integer
     * @return a random long integer greater than or equal to {@code lower} and
     * less than or equal to {@code upper}
     * @throws NumberIsTooLargeException if {@code lower >= upper}
     */
    long nextLong(long lower, long upper) throws NumberIsTooLargeException;

    
Generates a random string of hex characters from a secure random
sequence.
 If cryptographic security is not required, use nextHexString(int). 
Params:
len – the length of the string to be generated
Throws:
NotStrictlyPositiveException – if len <= 0
Returns:
a random string of hex characters of length len/**
     * Generates a random string of hex characters from a secure random
     * sequence.
     * <p>
     * If cryptographic security is not required, use
     * {@link #nextHexString(int)}.
     * </p>
     *
     * @param len the length of the string to be generated
     * @return a random string of hex characters of length {@code len}
     * @throws NotStrictlyPositiveException if {@code len <= 0}
     */
    String nextSecureHexString(int len) throws NotStrictlyPositiveException;

    
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(int, int) should be used instead of this method.

Definition:

Secure Random Sequence
Params:
lower – lower bound for generated integer
upper – upper bound for generated integer
Throws:
NumberIsTooLargeException – if lower >= upper.
Returns:
a random integer greater than or equal to lower and less than or equal to upper./**
     * Generates a uniformly distributed random integer between {@code lower}
     * and {@code upper} (endpoints included) from a secure random sequence.
     * <p>
     * Sequences of integers generated using this method will be
     * cryptographically secure. If cryptographic security is not required,
     * {@link #nextInt(int, int)} should be used instead of this method.</p>
     * <p>
     * <strong>Definition</strong>:
     * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
     * Secure Random Sequence</a></p>
     *
     * @param lower lower bound for generated integer
     * @param upper upper bound for generated integer
     * @return a random integer greater than or equal to {@code lower} and less
     * than or equal to {@code upper}.
     * @throws NumberIsTooLargeException if {@code lower >= upper}.
     */
    int nextSecureInt(int lower, int upper) throws NumberIsTooLargeException;

    
Generates a uniformly distributed random long integer between lower and upper (endpoints included) from a secure random sequence. 
 Sequences of long values generated using this method will be cryptographically secure. If cryptographic security is not required, nextLong(long, long) should be used instead of this method.

Definition:

Secure Random Sequence
Params:
lower – lower bound for generated integer
upper – upper bound for generated integer
Throws:
NumberIsTooLargeException – if lower >= upper.
Returns:
a random long integer greater than or equal to lower and less than or equal to upper./**
     * Generates a uniformly distributed random long integer between
     * {@code lower} and {@code upper} (endpoints included) from a secure random
     * sequence.
     * <p>
     * Sequences of long values generated using this method will be
     * cryptographically secure. If cryptographic security is not required,
     * {@link #nextLong(long, long)} should be used instead of this method.</p>
     * <p>
     * <strong>Definition</strong>:
     * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
     * Secure Random Sequence</a></p>
     *
     * @param lower lower bound for generated integer
     * @param upper upper bound for generated integer
     * @return a random long integer greater than or equal to {@code lower} and
     * less than or equal to {@code upper}.
     * @throws NumberIsTooLargeException if {@code lower >= upper}.
     */
    long nextSecureLong(long lower, long upper) throws NumberIsTooLargeException;

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

Definition:

Poisson Distribution
Params:
mean – the mean of the Poisson distribution
Throws:
NotStrictlyPositiveException – if mean <= 0.
Returns:
a random value following the specified Poisson distribution/**
     * Generates a random value from the Poisson distribution with the given
     * mean.
     * <p>
     * <strong>Definition</strong>:
     * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366j.htm">
     * Poisson Distribution</a></p>
     *
     * @param mean the mean of the Poisson distribution
     * @return a random value following the specified Poisson distribution
     * @throws NotStrictlyPositiveException if {@code mean <= 0}.
     */
    long nextPoisson(double mean) throws NotStrictlyPositiveException;

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

Definition:

Normal Distribution
Params:
mu – the mean of the distribution
sigma – the standard deviation of the distribution
Throws:
NotStrictlyPositiveException – if sigma <= 0.
Returns:
a random value following the specified Gaussian distribution/**
     * Generates a random value from the Normal (or Gaussian) distribution with
     * specified mean and standard deviation.
     * <p>
     * <strong>Definition</strong>:
     * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm">
     * Normal Distribution</a></p>
     *
     * @param mu the mean of the distribution
     * @param sigma the standard deviation of the distribution
     * @return a random value following the specified Gaussian distribution
     * @throws NotStrictlyPositiveException if {@code sigma <= 0}.
     */
    double nextGaussian(double mu, double sigma) throws NotStrictlyPositiveException;

    
Generates a random value from the exponential distribution
with specified mean.

Definition:

Exponential Distribution
Params:
mean – the mean of the distribution
Throws:
NotStrictlyPositiveException – if mean <= 0.
Returns:
a random value following the specified exponential distribution/**
     * Generates a random value from the exponential distribution
     * with specified mean.
     * <p>
     * <strong>Definition</strong>:
     * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm">
     * Exponential Distribution</a></p>
     *
     * @param mean the mean of the distribution
     * @return a random value following the specified exponential distribution
     * @throws NotStrictlyPositiveException if {@code mean <= 0}.
     */
    double nextExponential(double mean) throws NotStrictlyPositiveException;

    
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.
Params:
lower – the exclusive lower bound of the support
upper – the exclusive upper bound of the support
Throws:
NumberIsTooLargeException – if lower >= upper
NotFiniteNumberException – if one of the bounds is infinite
NotANumberException – if one of the bounds is NaN
Returns:
a uniformly distributed random value between lower and upper
(exclusive)/**
     * Generates a uniformly distributed random value from the open interval
     * {@code (lower, upper)} (i.e., endpoints excluded).
     * <p>
     * <strong>Definition</strong>:
     * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm">
     * Uniform Distribution</a> {@code lower} and {@code upper - lower} are the
     * <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm">
     * location and scale parameters</a>, respectively.</p>
     *
     * @param lower the exclusive lower bound of the support
     * @param upper the exclusive upper bound of the support
     * @return a uniformly distributed random value between lower and upper
     * (exclusive)
     * @throws NumberIsTooLargeException if {@code lower >= upper}
     * @throws NotFiniteNumberException if one of the bounds is infinite
     * @throws NotANumberException if one of the bounds is NaN
     */
    double nextUniform(double lower, double upper)
        throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException;

    
Generates a uniformly distributed random value from the interval (lower, upper) or the interval [lower, upper). The lower bound is thus optionally included, while the upper bound is always excluded. 

Definition:

Uniform Distribution lower and upper - lower are the 
location and scale parameters, respectively.
Params:
lower – the lower bound of the support
upper – the exclusive upper bound of the support
lowerInclusive – true if the lower bound is inclusive
Throws:
NumberIsTooLargeException – if lower >= upper
NotFiniteNumberException – if one of the bounds is infinite
NotANumberException – if one of the bounds is NaN
Returns:
uniformly distributed random value in the (lower, upper) interval, if lowerInclusive is false, or in the [lower, upper) interval, if lowerInclusive is true/**
     * Generates a uniformly distributed random value from the interval
     * {@code (lower, upper)} or the interval {@code [lower, upper)}. The lower
     * bound is thus optionally included, while the upper bound is always
     * excluded.
     * <p>
     * <strong>Definition</strong>:
     * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm">
     * Uniform Distribution</a> {@code lower} and {@code upper - lower} are the
     * <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm">
     * location and scale parameters</a>, respectively.</p>
     *
     * @param lower the lower bound of the support
     * @param upper the exclusive upper bound of the support
     * @param lowerInclusive {@code true} if the lower bound is inclusive
     * @return uniformly distributed random value in the {@code (lower, upper)}
     * interval, if {@code lowerInclusive} is {@code false}, or in the
     * {@code [lower, upper)} interval, if {@code lowerInclusive} is
     * {@code true}
     * @throws NumberIsTooLargeException if {@code lower >= upper}
     * @throws NotFiniteNumberException if one of the bounds is infinite
     * @throws NotANumberException if one of the bounds is NaN
     */
    double nextUniform(double lower, double upper, boolean lowerInclusive)
        throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException;

    
Generates an integer array of length k whose entries are selected randomly, without repetition, from the integers 0, ..., n - 1 (inclusive). 
 Generated arrays represent permutations of n taken k at a time.
Params:
n – the domain of the permutation
k – the size of the permutation
Throws:
NumberIsTooLargeException – if k > n.
NotStrictlyPositiveException – if k <= 0.
Returns:
a random k-permutation of n, as an array of integers/**
     * Generates an integer array of length {@code k} whose entries are selected
     * randomly, without repetition, from the integers {@code 0, ..., n - 1}
     * (inclusive).
     * <p>
     * Generated arrays represent permutations of {@code n} taken {@code k} at a
     * time.</p>
     *
     * @param n the domain of the permutation
     * @param k the size of the permutation
     * @return a random {@code k}-permutation of {@code n}, as an array of
     * integers
     * @throws NumberIsTooLargeException if {@code k > n}.
     * @throws NotStrictlyPositiveException if {@code k <= 0}.
     */
    int[] nextPermutation(int n, int k)
        throws NumberIsTooLargeException, NotStrictlyPositiveException;

    
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.
Params:
c – the collection to be sampled
k – the size of the sample
Throws:
NumberIsTooLargeException – if k > c.size().
NotStrictlyPositiveException – if k <= 0.
Returns:
a random sample of k elements from c/**
     * Returns an array of {@code k} objects selected randomly from the
     * Collection {@code c}.
     * <p>
     * Sampling from {@code c} is without replacement; but if {@code c} contains
     * identical objects, the sample may include repeats.  If all elements of
     * {@code c} are distinct, the resulting object array represents a
     * <a href="http://rkb.home.cern.ch/rkb/AN16pp/node250.html#SECTION0002500000000000000000">
     * Simple Random Sample</a> of size {@code k} from the elements of
     * {@code c}.</p>
     *
     * @param c the collection to be sampled
     * @param k the size of the sample
     * @return a random sample of {@code k} elements from {@code c}
     * @throws NumberIsTooLargeException if {@code k > c.size()}.
     * @throws NotStrictlyPositiveException if {@code k <= 0}.
     */
    Object[] nextSample(Collection<?> c, int k)
        throws NumberIsTooLargeException, NotStrictlyPositiveException;

}