org.apache.commons.math.random.RandomData Maven / Gradle / Ivy
/*
* 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.math.random;
import java.util.Collection;
/**
* Random data generation utilities.
* @version $Revision: 780975 $ $Date: 2009-06-02 11:05:37 +0200 (mar. 02 juin 2009) $
*/
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
*
* Preconditions:
* len > 0 (otherwise an IllegalArgumentException
* is thrown.)
*
* @param len the length of the string to be generated
* @return random string of hex characters of length len
*/
String nextHexString(int len);
/**
* 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.)
*
* @param lower lower bound for generated integer
* @param upper upper bound for generated integer
* @return a random integer greater than or equal to lower
* and less than or equal to upper.
*/
int nextInt(int lower, int 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.)
*
* @param lower lower bound for generated integer
* @param upper upper bound for generated integer
* @return a random integer greater than or equal to lower
* and less than or equal to upper.
*/
long nextLong(long lower, long upper);
/**
* 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.)
* @param len length of return string
* @return the random hex string
*/
String nextSecureHexString(int len);
/**
* 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.)
*
* @param lower lower bound for generated integer
* @param upper upper bound for generated integer
* @return a random integer greater than or equal to lower
* and less than or equal to upper.
*/
int nextSecureInt(int lower, int 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.)
*
* @param lower lower bound for generated integer
* @param upper upper bound for generated integer
* @return a long integer greater than or equal to lower
* and less than or equal to upper.
*/
long nextSecureLong(long lower, long upper);
/**
* 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.)
*
* @param mean Mean of the distribution
* @return poisson deviate with the specified mean
*/
long nextPoisson(double mean);
/**
* 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.)
* @param mu Mean of the distribution
* @param sigma Standard deviation of the distribution
* @return random value from Gaussian distribution with mean = mu,
* standard deviation = sigma
*/
double nextGaussian(double mu, double sigma);
/**
* Generates a random value from the exponential distribution
* with expected value = mean.
*
* Definition:
*
* Exponential Distribution
*
* Preconditions:
* mu >= 0 (otherwise an IllegalArgumentException
* is thrown.)
* @param mean Mean of the distribution
* @return random value from exponential distribution
*/
double nextExponential(double mean);
/**
* 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.)
*
* @param lower lower endpoint of the interval of support
* @param upper upper endpoint of the interval of support
* @return uniformly distributed random value between lower
* and upper (exclusive)
*/
double nextUniform(double lower, double upper);
/**
* 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.
*
* @param n domain of the permutation
* @param k size of the permutation
* @return random k-permutation of n
*/
int[] nextPermutation(int n, 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.
*
* @param c collection to be sampled
* @param k size of the sample
* @return random sample of k elements from c
*/
Object[] nextSample(Collection c, int k);
}