Apache
/
commons-math
mirror of https://github.com/apache/commons-math.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Javadoc 

Made sure that exceptions are documented in both javadoc and method signatures.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1230906 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Sebastien Brisard 2012-01-13 07:04:10 +00:00
parent d61dba0cf6
commit ffbb85d329
2 changed files with 162 additions and 289 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

264
src/main/java/org/apache/commons/math/random/RandomData.java
View File

@ -18,188 +18,161 @@
package org.apache.commons.math.random;
import java.util.Collection;
import org.apache.commons.math.exception.NotStrictlyPositiveException;
import org.apache.commons.math.exception.NumberIsTooLargeException;
/**
* Random data generation utilities.
* @version $Id$
*/
public interface RandomData {
/**
* Generates a random string of hex characters of length
* <code>len</code>.
* 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
* <code>nextSecureHexString</code></p>
* <p>
* <strong>Preconditions</strong>:<ul>
* <li><code>len > 0</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul></p>
* {@link #nextSecureHexString(int)}.
* </p>
*
* @param len the length of the string to be generated
* @return random string of hex characters of length <code>len</code>
* @return a random string of hex characters of length {@code len}
* @throws NotStrictlyPositiveException if {@code len <= 0}
*/
String nextHexString(int len);
String nextHexString(int len) throws NotStrictlyPositiveException;
/**
* Generates a uniformly distributed random integer between
* <code>lower</code> and <code>upper</code> (endpoints included).
* 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
* <code>nextSecureInt</code>.</p>
* <p>
* <strong>Preconditions</strong>:<ul>
* <li><code>lower < upper</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul></p>
* {@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</code>
* and less than or equal to <code>upper</code>.
* @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);
int nextInt(int lower, int upper) throws NumberIsTooLargeException;
/**
* Generates a uniformly distributed random long integer between
* <code>lower</code> and <code>upper</code> (endpoints included).
* {@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
* <code>nextSecureLong</code></p>
* <p>
* <strong>Preconditions</strong>:<ul>
* <li><code>lower < upper</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul></p>
* cryptographically secure. To generate cryptographically secure sequences
* of longs, use {@link #nextSecureLong(long, long)}.
* </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</code>
* and less than or equal to <code>upper</code>.
* @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);
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 <code>nextHexString()</code>.</p>
* <p>
* <strong>Preconditions</strong>:<ul>
* <li><code>len > 0</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul></p>
* @param len length of return string
* @return the random hex string
* 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);
String nextSecureHexString(int len) throws NotStrictlyPositiveException;
/**
* Generates a uniformly distributed random integer between
* <code>lower</code> and <code>upper</code> (endpoints included)
* from a secure random sequence.
* 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,
* <code>nextInt</code> should be used instead of this method.</p>
* {@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>
* <p>
* <strong>Preconditions</strong>:<ul>
* <li><code>lower < upper</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul></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</code>
* and less than or equal to <code>upper</code>.
* @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);
int nextSecureInt(int lower, int upper) throws NumberIsTooLargeException;
/**
* Generates a random long integer between <code>lower</code>
* and <code>upper</code> (endpoints included).
* 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,
* <code>nextLong</code> should be used instead of this method.</p>
* {@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>
* <p>
* <strong>Preconditions</strong>:<ul>
* <li><code>lower < upper</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul></p>
*
* @param lower lower bound for generated integer
* @param upper upper bound for generated integer
* @return a long integer greater than or equal to <code>lower</code>
* and less than or equal to <code>upper</code>.
* @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);
long nextSecureLong(long lower, long upper)
throws NumberIsTooLargeException;
/**
* Generates a random value from the Poisson distribution with
* the given mean.
* 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>
* <p>
* <strong>Preconditions</strong>: <ul>
* <li>The specified mean <i>must</i> be positive (otherwise an
* IllegalArgumentException is thrown.)</li>
* </ul></p>
* @param mean Mean of the distribution
* @return poisson deviate with the specified mean
*
* @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);
long nextPoisson(double mean) throws NotStrictlyPositiveException;
/**
* Generates a random value from the
* Normal (or Gaussian) distribution with the given mean
* and standard deviation.
* 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>
* <p>
* <strong>Preconditions</strong>: <ul>
* <li><code>sigma > 0</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul></p>
* @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
*
* @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);
double nextGaussian(double mu, double sigma)
throws NotStrictlyPositiveException;
/**
* Generates a random value from the exponential distribution
* with expected value = <code>mean</code>.
* with specified mean.
* <p>
* <strong>Definition</strong>:
* <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm">
* Exponential Distribution</a></p>
* <p>
* <strong>Preconditions</strong>: <ul>
* <li><code>mu >= 0</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul></p>
* @param mean Mean of the distribution
* @return random value from exponential distribution
*
* @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);
double nextExponential(double mean) throws NotStrictlyPositiveException;
/**
* Generates a uniformly distributed random value from the open interval
@ -207,17 +180,18 @@ public interface RandomData {
* <p>
* <strong>Definition</strong>:
* <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm">
* Uniform Distribution</a> <code>lower</code> and
* <code>upper - lower</code> are the
* 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 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)
* @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}
*/
double nextUniform(double lower, double upper);
double nextUniform(double lower, double upper)
throws NumberIsTooLargeException;
/**
* Generates a uniformly distributed random value from the interval
@ -227,64 +201,56 @@ public interface RandomData {
* <p>
* <strong>Definition</strong>:
* <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm">
* Uniform Distribution</a> <code>lower</code> and
* <code>upper - lower</code> are the
* 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 lower endpoint of the interval of support
* @param upper upper endpoint of the interval of support
* @param lowerInclusive {@code true} if the lower bound is included in the
* interval
* @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}
*/
double nextUniform(double lower, double upper, boolean lowerInclusive);
double nextUniform(double lower, double upper, boolean lowerInclusive)
throws NumberIsTooLargeException;
/**
* Generates an integer array of length <code>k</code> whose entries
* are selected randomly, without repetition, from the integers <code>
* 0 through n-1</code> (inclusive).
* 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</code> taken <code>k</code> at a time.</p>
* <p>
* <strong>Preconditions:</strong><ul>
* <li> <code>k <= n</code></li>
* <li> <code>n > 0</code> </li>
* </ul>
* If the preconditions are not met, an IllegalArgumentException is
* thrown.</p>
* Generated arrays represent permutations of {@code n} taken {@code k} at a
* time.</p>
*
* @param n domain of the permutation
* @param k size of the permutation
* @return random k-permutation of n
* @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);
int[] nextPermutation(int n, int k)
throws NumberIsTooLargeException, NotStrictlyPositiveException;
/**
* Returns an array of <code>k</code> objects selected randomly
* from the Collection <code>c</code>.
* Returns an array of {@code k} objects selected randomly from the
* Collection {@code c}.
* <p>
* Sampling from <code>c</code>
* is without replacement; but if <code>c</code> contains identical
* objects, the sample may include repeats. If all elements of <code>
* c</code> are distinct, the resulting object array represents a
* 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</code> from the elements of <code>c</code>.</p>
* <p>
* <strong>Preconditions:</strong><ul>
* <li> k must be less than or equal to the size of c </li>
* <li> c must not be empty </li>
* </ul>
* If the preconditions are not met, an IllegalArgumentException is
* thrown.</p>
* Simple Random Sample</a> of size {@code k} from the elements of
* {@code c}.</p>
*
* @param c collection to be sampled
* @param k size of the sample
* @return random sample of k elements from 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);
Object[] nextSample(Collection<?> c, int k)
throws NumberIsTooLargeException, NotStrictlyPositiveException;
}

187
src/main/java/org/apache/commons/math/random/RandomDataImpl.java
View File

@ -187,19 +187,17 @@ public class RandomDataImpl implements RandomData, Serializable {
* <strong>Algorithm Description:</strong> hex strings are generated using a
* 2-step process.
* <ol>
* <li>
* len/2+1 binary bytes are generated using the underlying Random</li>
* <li>
* Each binary byte is translated into 2 hex digits</li>
* <li>{@code len / 2 + 1} binary bytes are generated using the underlying
* Random</li>
* <li>Each binary byte is translated into 2 hex digits</li>
* </ol>
* </p>
*
* @param len
* the desired string length.
* @param len the desired string length.
* @return the random string.
* @throws NotStrictlyPositiveException if {@code len <= 0}.
*/
public String nextHexString(int len) {
public String nextHexString(int len) throws NotStrictlyPositiveException {
if (len <= 0) {
throw new NotStrictlyPositiveException(LocalizedFormats.LENGTH, len);
}
@ -234,38 +232,18 @@ public class RandomDataImpl implements RandomData, Serializable {
return outBuffer.toString().substring(0, len);
}
/**
* Generate a random int value uniformly distributed between
* <code>lower</code> and <code>upper</code>, inclusive.
*
* @param lower
* the lower bound.
* @param upper
* the upper bound.
* @return the random integer.
* @throws NumberIsTooLargeException if {@code lower >= upper}.
*/
public int nextInt(int lower, int upper) {
/** {@inheritDoc} */
public int nextInt(int lower, int upper) throws NumberIsTooLargeException {
if (lower >= upper) {
throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND,
lower, upper, false);
}
double r = getRan().nextDouble();
double scaled = r * upper + (1.0 - r) * lower + r;
return (int)FastMath.floor(scaled);
return (int) FastMath.floor(scaled);
}
/**
* Generate a random long value uniformly distributed between
* <code>lower</code> and <code>upper</code>, inclusive.
*
* @param lower
* the lower bound.
* @param upper
* the upper bound.
* @return the random integer.
* @throws NumberIsTooLargeException if {@code lower >= upper}.
*/
/** {@inheritDoc} */
public long nextLong(long lower, long upper) {
if (lower >= upper) {
throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND,
@ -291,13 +269,8 @@ public class RandomDataImpl implements RandomData, Serializable {
* Each byte of the binary digest is converted to 2 hex digits.</li>
* </ol>
* </p>
*
* @param len
* the length of the generated string
* @return the random string
* @throws NotStrictlyPositiveException if {@code len <= 0}.
*/
public String nextSecureHexString(int len) {
public String nextSecureHexString(int len) throws NotStrictlyPositiveException {
if (len <= 0) {
throw new NotStrictlyPositiveException(LocalizedFormats.LENGTH, len);
}
@ -323,7 +296,7 @@ public class RandomDataImpl implements RandomData, Serializable {
alg.update(randomBytes);
// Compute hash -- will create 20-byte binary hash
byte hash[] = alg.digest();
byte[] hash = alg.digest();
// Loop over the hash, converting each byte to 2 hex digits
for (int i = 0; i < hash.length; i++) {
@ -346,18 +319,7 @@ public class RandomDataImpl implements RandomData, Serializable {
return outBuffer.toString().substring(0, len);
}
/**
* Generate a random int value uniformly distributed between
* <code>lower</code> and <code>upper</code>, inclusive. This algorithm uses
* a secure random number generator.
*
* @param lower
* the lower bound.
* @param upper
* the upper bound.
* @return the random integer.
* @throws NumberIsTooLargeException if {@code lower >= upper}.
*/
/** {@inheritDoc} */
public int nextSecureInt(int lower, int upper) {
if (lower >= upper) {
throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND,
@ -369,19 +331,10 @@ public class RandomDataImpl implements RandomData, Serializable {
return (int)FastMath.floor(scaled);
}
/**
* Generate a random long value uniformly distributed between
* <code>lower</code> and <code>upper</code>, inclusive. This algorithm uses
* a secure random number generator.
*
* @param lower
* the lower bound.
* @param upper
* the upper bound.
* @return the random integer.
* @throws NumberIsTooLargeException if {@code lower >= upper}.
*/
public long nextSecureLong(long lower, long upper) {
/** {@inheritDoc} */
public long nextSecureLong(long lower, long upper)
throws NumberIsTooLargeException {
if (lower >= upper) {
throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND,
lower, upper, false);
@ -404,12 +357,8 @@ public class RandomDataImpl implements RandomData, Serializable {
* <li> For large means, uses the rejection algorithm described in <br/>
* Devroye, Luc. (1981).<i>The Computer Generation of Poisson Random Variables</i>
* <strong>Computing</strong> vol. 26 pp. 197-207.</li></ul></p>
*
* @param mean mean of the Poisson distribution.
* @return the random Poisson value.
* @throws NotStrictlyPositiveException if {@code mean <= 0}.
*/
public long nextPoisson(double mean) {
public long nextPoisson(double mean) throws NotStrictlyPositiveException {
if (mean <= 0) {
throw new NotStrictlyPositiveException(LocalizedFormats.MEAN, mean);
}
@ -500,19 +449,10 @@ public class RandomDataImpl implements RandomData, Serializable {
}
}
/**
* Generate a random value from a Normal (a.k.a. Gaussian) distribution with
* the given mean, <code>mu</code> and the given standard deviation,
* <code>sigma</code>.
*
* @param mu
* the mean of the distribution
* @param sigma
* the standard deviation of the distribution
* @return the random Normal value
* @throws NotStrictlyPositiveException if {@code sigma <= 0}.
*/
public double nextGaussian(double mu, double sigma) {
/** {@inheritDoc} */
public double nextGaussian(double mu, double sigma)
throws NotStrictlyPositiveException {
if (sigma <= 0) {
throw new NotStrictlyPositiveException(LocalizedFormats.STANDARD_DEVIATION, sigma);
}
@ -520,8 +460,8 @@ public class RandomDataImpl implements RandomData, Serializable {
}
/**
* Returns a random value from an Exponential distribution with the given
* mean.
* {@inheritDoc}
*
* <p>
* <strong>Algorithm Description</strong>: Uses the Algorithm SA (Ahrens)
* from p. 876 in:
@ -529,12 +469,10 @@ public class RandomDataImpl implements RandomData, Serializable {
* sampling from the exponential and normal distributions.
* Communications of the ACM, 15, 873-882.
* </p>
*
* @param mean the mean of the distribution
* @return the random Exponential value
* @throws NotStrictlyPositiveException if {@code mean <= 0}.
*/
public double nextExponential(double mean) {
public double nextExponential(double mean)
throws NotStrictlyPositiveException {
if (mean <= 0.0) {
throw new NotStrictlyPositiveException(LocalizedFormats.MEAN, mean);
}
@ -579,6 +517,7 @@ public class RandomDataImpl implements RandomData, Serializable {
/**
* {@inheritDoc}
*
* <p>
* <strong>Algorithm Description</strong>: scales the output of
* Random.nextDouble(), but rejects 0 values (i.e., will generate another
@ -586,20 +525,18 @@ public class RandomDataImpl implements RandomData, Serializable {
* provide a symmetric output interval (both endpoints excluded).
* </p>
*
* @param lower the lower bound.
* @param upper the upper bound.
* @return a uniformly distributed random value from the interval (lower, upper)
* @throws NumberIsTooLargeException if {@code lower >= upper}
* @throws MathIllegalArgumentException if one of the bounds is infinite or
* {@code NaN}
* or either bound is infinite or NaN
* {@code NaN} or either bound is infinite or NaN
*/
public double nextUniform(double lower, double upper) {
public double nextUniform(double lower, double upper)
throws NumberIsTooLargeException, MathIllegalArgumentException {
return nextUniform(lower, upper, false);
}
/**
* {@inheritDoc}
*
* <p>
* <strong>Algorithm Description</strong>: if the lower bound is excluded,
* scales the output of Random.nextDouble(), but rejects 0 values (i.e.,
@ -608,20 +545,14 @@ public class RandomDataImpl implements RandomData, Serializable {
* endpoints excluded).
* </p>
*
* @param lower
* the lower bound.
* @param upper
* the upper bound.
* @param lowerInclusive
* whether the lower bound is included in the interval
* @return a uniformly distributed random value from the interval (lower,
* upper)
* @throws NumberIsTooLargeException if {@code lower >= upper}
* @throws MathIllegalArgumentException if one of the bounds is infinite or
* {@code NaN}
* @since 3.0
*/
public double nextUniform(double lower, double upper, boolean lowerInclusive) {
public double nextUniform(double lower, double upper,
boolean lowerInclusive)
throws NumberIsTooLargeException, MathIllegalArgumentException {
if (lower >= upper) {
throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND,
lower, upper, false);
@ -997,41 +928,20 @@ public class RandomDataImpl implements RandomData, Serializable {
}
/**
* Generates an integer array of length <code>k</code> whose entries are
* selected randomly, without repetition, from the integers
* <code>0 through n-1</code> (inclusive).
* <p>
* Generated arrays represent permutations of <code>n</code> taken
* <code>k</code> at a time.
* </p>
* <p>
* <strong>Preconditions:</strong>
* <ul>
* <li> <code>k <= n</code></li>
* <li> <code>n > 0</code></li>
* </ul>
* If the preconditions are not met, an IllegalArgumentException is thrown.
* </p>
* {@inheritDoc}
*
* <p>
* Uses a 2-cycle permutation shuffle. The shuffling process is described <a
* href="http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node83.html">
* here</a>.
* </p>
*
* @param n
* domain of the permutation (must be positive)
* @param k
* size of the permutation (must satisfy 0 < k <= n).
* @return the random permutation as an int array
* @throws NumberIsTooLargeException if {@code k > n}.
* @throws NotStrictlyPositiveException if {@code k <= 0}.
*/
public int[] nextPermutation(int n, int k) {
if (k > n) {
throw new NumberIsTooLargeException(LocalizedFormats.PERMUTATION_EXCEEDS_N,
k, n, true);
}
if (k == 0) {
if (k <= 0) {
throw new NotStrictlyPositiveException(LocalizedFormats.PERMUTATION_SIZE,
k);
}
@ -1047,24 +957,21 @@ public class RandomDataImpl implements RandomData, Serializable {
}
/**
* Uses a 2-cycle permutation shuffle to generate a random permutation.
* {@inheritDoc}
*
* <p>
* <strong>Algorithm Description</strong>: Uses a 2-cycle permutation
* shuffle to generate a random permutation of <code>c.size()</code> and
* then returns the elements whose indexes correspond to the elements of the
* generated permutation. This technique is described, and proven to
* generate random samples, <a
* generate random samples <a
* href="http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node83.html">
* here</a>
*
* @param c
* Collection to sample from.
* @param k
* sample size.
* @return the random sample.
* @throws NumberIsTooLargeException if {@code k > c.size()}.
* @throws NotStrictlyPositiveException if {@code k <= 0}.
* </p>
*/
public Object[] nextSample(Collection<?> c, int k) {
public Object[] nextSample(Collection<?> c, int k)
throws NumberIsTooLargeException, NotStrictlyPositiveException {
int len = c.size();
if (k > len) {
throw new NumberIsTooLargeException(LocalizedFormats.SAMPLE_SIZE_EXCEEDS_COLLECTION_SIZE,