path: root/src/main/java/org/apache/commons/math3/random/RandomData.java

/*
 * 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 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;

import java.util.Collection;

/**
 * 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 {@code len}.
     *
     * <p>The generated string will be random, but not cryptographically secure. To generate
     * cryptographically secure strings, use {@link #nextSecureHexString(int)}.
     *
     * @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 {@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)}.
     *
     * @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 {@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)}.
     *
     * @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.
     *
     * <p>If cryptographic security is not required, use {@link #nextHexString(int)}.
     *
     * @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 {@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><strong>Definition</strong>: <a
     * href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
     * Secure Random Sequence</a>
     *
     * @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 {@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><strong>Definition</strong>: <a
     * href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
     * Secure Random Sequence</a>
     *
     * @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.
     *
     * <p><strong>Definition</strong>: <a
     * href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366j.htm">Poisson
     * Distribution</a>
     *
     * @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.
     *
     * <p><strong>Definition</strong>: <a
     * href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm">Normal
     * Distribution</a>
     *
     * @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.
     *
     * <p><strong>Definition</strong>: <a
     * href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm">Exponential
     * Distribution</a>
     *
     * @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 {@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.
     *
     * @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 {@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.
     *
     * @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 {@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.
     *
     * @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 {@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}.
     *
     * @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;
}