Coverage Report - org.apache.commons.math.random.RandomData

Classes in this File Line Coverage Branch Coverage Complexity
RandomData
N/A 
N/A 
1

 1  
 /*
 2  
  * Copyright 2003-2004 The Apache Software Foundation.
 3  
  *
 4  
  * Licensed under the Apache License, Version 2.0 (the "License");
 5  
  * you may not use this file except in compliance with the License.
 6  
  * You may obtain a copy of the License at
 7  
  *
 8  
  *      http://www.apache.org/licenses/LICENSE-2.0
 9  
  *
 10  
  * Unless required by applicable law or agreed to in writing, software
 11  
  * distributed under the License is distributed on an "AS IS" BASIS,
 12  
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 13  
  * See the License for the specific language governing permissions and
 14  
  * limitations under the License.
 15  
  */
 16  
 
 17  
 package org.apache.commons.math.random;
 18  
 import java.util.Collection;
 19  
 
 20  
 /**
 21  
  * Random data generation utilities
 22  
  * @version $Revision$ $Date: 2005-02-26 05:11:52 -0800 (Sat, 26 Feb 2005) $
 23  
  */
 24  
 public interface RandomData {
 25  
     /**
 26  
      * Generates a random string of hex characters of length
 27  
      * <code>len</code>.
 28  
      * <p>
 29  
      * The generated string will be random, but not cryptographically
 30  
      * secure. To generate cryptographically secure strings, use
 31  
      * <code>nextSecureHexString</code>
 32  
      * <p>
 33  
      * <strong>Preconditions</strong>:<ul>
 34  
      * <li><code>len > 0</code> (otherwise an IllegalArgumentException
 35  
      *     is thrown.)</li>
 36  
      * </ul>
 37  
      *
 38  
      * @param len the length of the string to be generated
 39  
      * @return random string of hex characters of length <code>len</code>
 40  
      */
 41  
     String nextHexString(int len);
 42  
 
 43  
     /**
 44  
      * Generates a uniformly distributed random integer between
 45  
      * <code>lower</code> and <code>upper</code> (endpoints included).
 46  
      * <p>
 47  
      * The generated integer will be random, but not cryptographically secure.
 48  
      * To generate cryptographically secure integer sequences, use
 49  
      * <code>nextSecureInt</code>.
 50  
      * <p>
 51  
      * <strong>Preconditions</strong>:<ul>
 52  
      * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
 53  
      *     is thrown.)</li>
 54  
      * </ul>
 55  
      *
 56  
      * @param lower lower bound for generated integer
 57  
      * @param upper upper bound for generated integer
 58  
      * @return a random integer greater than or equal to <code>lower</code>
 59  
      * and less than or equal to <code>upper</code>.
 60  
      */
 61  
     int nextInt(int lower, int upper);
 62  
 
 63  
     /**
 64  
      * Generates a uniformly distributed random long integer between
 65  
      * <code>lower</code> and <code>upper</code> (endpoints included).
 66  
      * <p>
 67  
      * The generated long integer values will be random, but not
 68  
      * cryptographically secure.
 69  
      * To generate cryptographically secure sequences of longs, use
 70  
      * <code>nextSecureLong</code>
 71  
      * <p>
 72  
      * <strong>Preconditions</strong>:<ul>
 73  
      * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
 74  
      *     is thrown.)</li>
 75  
      * </ul>
 76  
      *
 77  
      * @param lower lower bound for generated integer
 78  
      * @param upper upper bound for generated integer
 79  
      * @return a random integer greater than or equal to <code>lower</code>
 80  
      * and less than or equal to <code>upper</code>.
 81  
      */
 82  
     long nextLong(long lower, long upper);
 83  
 
 84  
     /**
 85  
      * Generates a random string of hex characters from a secure random
 86  
      * sequence.
 87  
      * <p>
 88  
      * If cryptographic security is not required,
 89  
      * use <code>nextHexString()</code>.
 90  
      * <p>
 91  
      * <strong>Preconditions</strong>:<ul>
 92  
      * <li><code>len > 0</code> (otherwise an IllegalArgumentException
 93  
      *     is thrown.)</li>
 94  
      * </ul>
 95  
      * @param len length of return string
 96  
      * @return the random hex string
 97  
      */
 98  
     String nextSecureHexString(int len);
 99  
 
 100  
     /**
 101  
      * Generates a uniformly distributed random integer between
 102  
      * <code>lower</code> and <code>upper</code> (endpoints included)
 103  
      * from a secure random sequence.
 104  
      * <p>
 105  
      * Sequences of integers generated using this method will be
 106  
      * cryptographically secure. If cryptographic security is not required,
 107  
      * <code>nextInt</code> should be used instead of this method.
 108  
      * <p>
 109  
      * <strong>Definition</strong>:
 110  
      * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
 111  
      * Secure Random Sequence</a>
 112  
      * <p>
 113  
      * <strong>Preconditions</strong>:<ul>
 114  
      * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
 115  
      *     is thrown.)</li>
 116  
      * </ul>
 117  
      *
 118  
      * @param lower lower bound for generated integer
 119  
      * @param upper upper bound for generated integer
 120  
      * @return a random integer greater than or equal to <code>lower</code>
 121  
      * and less than or equal to <code>upper</code>.
 122  
      */
 123  
     int nextSecureInt(int lower, int upper);
 124  
 
 125  
     /**
 126  
      * Generates a random long integer between <code>lower</code>
 127  
      * and <code>upper</code> (endpoints included).<p>
 128  
      * Sequences of long values generated using this method will be
 129  
      * cryptographically secure. If cryptographic security is not required,
 130  
      * <code>nextLong</code> should be used instead of this method.
 131  
      * <p>
 132  
      * <strong>Definition</strong>:
 133  
      * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
 134  
      * Secure Random Sequence</a>
 135  
      * <p>
 136  
      * <strong>Preconditions</strong>:<ul>
 137  
      * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
 138  
      *     is thrown.)</li>
 139  
      * </ul>
 140  
      *
 141  
      * @param lower lower bound for generated integer
 142  
      * @param upper upper bound for generated integer
 143  
      * @return a long integer greater than or equal to <code>lower</code>
 144  
      * and less than or equal to <code>upper</code>.
 145  
      */
 146  
     long nextSecureLong(long lower, long upper);
 147  
 
 148  
     /**
 149  
      * Generates a random value from the Poisson distribution with
 150  
      * the given mean.
 151  
      * <p>
 152  
      * <strong>Definition</strong>:
 153  
      * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366j.htm">
 154  
      * Poisson Distribution</a>
 155  
      * <p>
 156  
      * <strong>Preconditions</strong>: <ul>
 157  
      * <li>The specified mean <i>must</i> be positive (otherwise an
 158  
      *     IllegalArgumentException is thrown.)</li>
 159  
      * </ul>
 160  
      * @param mean Mean of the distribution
 161  
      * @return poisson deviate with the specified mean
 162  
      */
 163  
     long nextPoisson(double mean);
 164  
 
 165  
     /**
 166  
      * Generates a random value from the
 167  
      * Normal (or Gaussian) distribution with the given mean
 168  
      * and standard deviation.
 169  
      * <p>
 170  
      * <strong>Definition</strong>:
 171  
      * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm">
 172  
      * Normal Distribution</a>
 173  
      * <p>
 174  
      * <strong>Preconditions</strong>: <ul>
 175  
      * <li><code>sigma > 0</code> (otherwise an IllegalArgumentException
 176  
      *     is thrown.)</li>
 177  
      * </ul>
 178  
      * @param mu Mean of the distribution
 179  
      * @param sigma Standard deviation of the distribution
 180  
      * @return random value from Gaussian distribution with mean = mu,
 181  
      * standard deviation = sigma
 182  
      */
 183  
     double nextGaussian(double mu, double sigma);
 184  
 
 185  
     /**
 186  
      * Generates a random value from the exponential distribution
 187  
      * with expected value = <code>mean</code>.
 188  
      * <p>
 189  
      * <strong>Definition</strong>:
 190  
      * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm">
 191  
      * Exponential Distribution</a>
 192  
      * <p>
 193  
      * <strong>Preconditions</strong>: <ul>
 194  
      * <li><code>mu >= 0</code> (otherwise an IllegalArgumentException
 195  
      *     is thrown.)</li>
 196  
      * </ul>
 197  
      * @param mean Mean of the distribution
 198  
      * @return random value from exponential distribution
 199  
      */
 200  
     double nextExponential(double mean);
 201  
 
 202  
     /**
 203  
      * Generates a uniformly distributed random value from the open interval
 204  
      * (<code>lower</code>,<code>upper</code>) (i.e., endpoints excluded).
 205  
      * <p>
 206  
      * <strong>Definition</strong>:
 207  
      * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm">
 208  
      * Uniform Distribution</a> <code>lower</code> and
 209  
      * <code>upper - lower</code> are the
 210  
      * <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm">
 211  
      * location and scale parameters</a>, respectively.
 212  
      * <p>
 213  
      * <strong>Preconditions</strong>:<ul>
 214  
      * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
 215  
      *     is thrown.)</li>
 216  
      * </ul>
 217  
      *
 218  
      * @param lower lower endpoint of the interval of support
 219  
      * @param upper upper endpoint of the interval of support
 220  
      * @return uniformly distributed random value between lower
 221  
      * and upper (exclusive)
 222  
      */
 223  
     double nextUniform(double lower, double upper);
 224  
 
 225  
     /**
 226  
      * Generates an integer array of length <code>k</code> whose entries
 227  
      * are selected randomly, without repetition, from the integers <code>
 228  
      * 0 through n-1</code> (inclusive).
 229  
      * <p>
 230  
      * Generated arrays represent permutations
 231  
      * of <code>n</code> taken <code>k</code> at a time.
 232  
      * <p>
 233  
      * <strong>Preconditions:</strong><ul>
 234  
      * <li> <code>k <= n</code></li>
 235  
      * <li> <code>n > 0</code> </li>
 236  
      * </ul>
 237  
      * If the preconditions are not met, an IllegalArgumentException is
 238  
      * thrown.
 239  
      *
 240  
      * @param n domain of the permutation
 241  
      * @param k size of the permutation
 242  
      * @return random k-permutation of n
 243  
      */
 244  
     int[] nextPermutation(int n, int k);
 245  
 
 246  
     /**
 247  
      * Returns an array of <code>k</code> objects selected randomly
 248  
      * from the Collection <code>c</code>.
 249  
      * <p>
 250  
      * Sampling from <code>c</code>
 251  
      * is without replacement; but if <code>c</code> contains identical
 252  
      * objects, the sample may include repeats.  If all elements of <code>
 253  
      * c</code> are distinct, the resulting object array represents a
 254  
      * <a href="http://rkb.home.cern.ch/rkb/AN16pp/node250.html#SECTION0002500000000000000000">
 255  
      * Simple Random Sample</a> of size
 256  
      * <code>k</code> from the elements of <code>c</code>.
 257  
      * <p>
 258  
      * <strong>Preconditions:</strong><ul>
 259  
      * <li> k must be less than or equal to the size of c </li>
 260  
      * <li> c must not be empty </li>
 261  
      * </ul>
 262  
      * If the preconditions are not met, an IllegalArgumentException is
 263  
      * thrown.
 264  
      *
 265  
      * @param c collection to be sampled
 266  
      * @param k size of the sample
 267  
      * @return random sample of k elements from c
 268  
      */
 269  
     Object[] nextSample(Collection c, int k);
 270  
 }