Changeset 2 in Project Repository


Ignore:
Timestamp:
08/14/2012 11:04:35 AM (8 years ago)
Author:
pchapin
Message:

Reformatted the comments in the existing source files.

Location:
src
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • src/random.cpp

    r1 r2  
    11/**************************************************************************** 
    2 FILE          : random.cpp 
    3 LAST REVISION : 2005-11-21 
    4 SUBJECT       : Implementation of random number abstract class. 
    5 PROGRAMMER    : (C) Copyright 2005 by Peter C. Chapin 
     2FILE      : random.cpp 
     3SUBJECT   : Implementation of random number abstract class. 
     4PROGRAMMER: (C) Copyright 2012 by Peter C. Chapin 
    65 
    7 This file contains the implementation of the non-inline member functions of 
    8 the various random number classes. 
    9  
    10 Please send comments or bug reports to 
    11  
    12      Peter C. Chapin 
    13      Electrical and Computer Engineering Technology 
    14      Vermont Technical College 
    15      Randolph Center, VT 05061 
    16      pchapin@ecet.vtc.edu 
    176****************************************************************************/ 
    187 
     
    2312namespace rnd { 
    2413 
    25   // This method will return non-random results if the underlying 
    26   // generator has a maximum value that is not near a power of two. 
    27   // Ideally it should be a power of two minus 1. Otherwise when the 
    28   // mask reaches the most significant bit, it will see an excessive 
    29   // number of zero bits there. 
     14  // This method will return non-random results if the underlying generator has a maximum value 
     15  // that is not near a power of two. Ideally it should be a power of two minus 1. Otherwise 
     16  // when the mask reaches the most significant bit, it will see an excessive number of zero 
     17  // bits there. 
    3018  // 
    3119  unsigned bit_random::next() 
     
    4230    bit = (current & mask) ? 1 : 0; 
    4331 
    44     // Advance the mask, taking care not to overflow unsigned or go off 
    45     // the end of the values coming back from the underlying generator. 
     32    // Advance the mask, taking care not to overflow unsigned or go off the end of the values 
     33    // coming back from the underlying generator. 
    4634    // 
    4735    if (mask > (std::numeric_limits<unsigned>().max() >> 1)) { 
     
    5644 
    5745 
    58   // This implementation uses the output of std::time to seed the random 
    59   // number generator. There are numerous problems with doing this, but 
    60   // some applications are not concerned by them. 
     46  // This implementation uses the output of std::time to seed the random number generator. There 
     47  // are numerous problems with doing this, but some applications are not concerned by them. 
    6148  // 
    6249  void seeded_random::time_seed() 
  • src/random.h

    r1 r2  
    11/**************************************************************************** 
    2 FILE          : random.h 
    3 LAST REVISION : 2005-11-21 
    4 SUBJECT       : Interface to random number abstract class. 
    5 PROGRAMMER    : (C) Copyright 2005 by Peter C. Chapin 
     2FILE      : random.h 
     3SUBJECT   : Interface to random number abstract class. 
     4PROGRAMMER: (C) Copyright 2012 by Peter C. Chapin 
    65 
    7 This file contains the interface to a random number generating class. For 
    8 brevity it also contains the definitions of two implementation classes (it 
    9 would be more typical for each implementation class to have a header of 
    10 its own). 
     6This file contains the interface to a random number generating class. For brevity it also 
     7contains the definitions of two implementation classes (it would be more typical for each 
     8implementation class to have a header of its own). 
    119 
    12 Please send comments or bug reports to 
    13  
    14      Peter C. Chapin 
    15      Electrical and Computer Engineering Technology 
    16      Vermont Technical College 
    17      Randolph Center, VT 05061 
    18      pchapin@ecet.vtc.edu 
    1910****************************************************************************/ 
    2011 
     
    2920  //! Abstract base class for random number generators. 
    3021  /*! 
    31    * This class is intended to provide an abstract interface to all 
    32    * random number generator objects that return natural numbers in the 
    33    * range 0 to some maximum value. 
     22   * This class is intended to provide an abstract interface to all random number generator 
     23   * objects that return natural numbers in the range 0 to some maximum value. 
    3424   * 
    35    * \todo It might make sense to use a type such as uint32_t for the 
    36    * random numbers rather than unsigned int as is currently the case. 
    37    * This would promote portability to 16 bit (or smaller) platforms. 
     25   * \todo It might make sense to use a type such as uint32_t for the random numbers rather than 
     26   * unsigned int as is currently the case. This would promote portability to 16 bit (or 
     27   * smaller) platforms. 
    3828   */ 
    3929  class random { 
     
    5040    //! Returns a random number in the range [L .. H] from the object. 
    5141    /*! 
    52      * This method uses the underlying generator to compute a random 
    53      * natural number in the given range. Each call on this method 
    54      * invokes exactly one call to the underlying next() method. This 
    55      * method for convenience. 
     42     * This method uses the underlying generator to compute a random natural number in the given 
     43     * range. Each call on this method invokes exactly one call to the underlying next() method. 
     44     * This method for convenience. 
    5645     * 
    5746     * \param L The lower limit of the output range. 
    5847     * \param H The upper limit of the output range. 
    59      * \return A number in the specified range. H and L are included in 
    60      * the range. 
     48     * \return A number in the specified range. H and L are included in the range. 
    6149     */ 
    6250    unsigned next(unsigned L, unsigned H) 
     
    6755  //! Random bit generator wrapper class (scanner). 
    6856  /*! 
    69    * This class is a wrapper around class random that returns individual 
    70    * bits. It works by scanning down the numbers returned by the 
    71    * underlying generator and returning the bits it finds there, one at 
    72    * a time. 
     57   * This class is a wrapper around class random that returns individual bits. It works by 
     58   * scanning down the numbers returned by the underlying generator and returning the bits it 
     59   * finds there, one at a time. 
    7360   * 
    74    * \warning If the underlying generator has a maximum value that is 
    75    * not a power of two, the output of this generator will have bias. 
    76    * This is because the most significant bit of the output of the 
    77    * underlying generator will not be occuring with frequency 0.5. 
     61   * \warning If the underlying generator has a maximum value that is not a power of two, the 
     62   * output of this generator will have bias. This is because the most significant bit of the 
     63   * output of the underlying generator will not be occuring with frequency 0.5. 
    7864   */ 
    7965  class bit_random : public random { 
     
    8571  public: 
    8672    /*! 
    87      * \param g A reference to a random number generator that is used as 
    88      * the source of random natural numbers. 
     73     * \param g A reference to a random number generator that is used as the source of random 
     74     * natural numbers. 
    8975     */ 
    9076    bit_random(random &g) : generator(g) { mask = 0; } 
     
    9884  //! Random bit generator wrapper class (LSB). 
    9985  /*! 
    100    * This class is a wrapper around class random that returns individual 
    101    * bits. It works by returning the least significant bit of each 
    102    * number returned by the underlying generator. 
     86   * This class is a wrapper around class random that returns individual bits. It works by 
     87   * returning the least significant bit of each number returned by the underlying generator. 
    10388   * 
    104    * \warning Many PRNGs are not good at randomizing the least 
    105    * significant bits of each output number. 
     89   * \warning Many PRNGs are not good at randomizing the least significant bits of each output 
     90   * number. 
    10691   */ 
    10792  class lsbbit_random : public random { 
     
    11196  public: 
    11297    /*! 
    113      * \param g A reference to a random number generator that is used as 
    114      * the source of random natural numbers. 
     98     * \param g A reference to a random number generator that is used as the source of random 
     99     * natural numbers. 
    115100     */ 
    116101    lsbbit_random(random &g) : generator(g) { } 
     
    131116    //! Provide a seed value to the random number generator. 
    132117    /*! 
    133      * Random number generators that require a seed value include all 
    134      * PRNGs. The seed is used as the starting point of the pseudo 
    135      * random sequence. A particular sequence can be repeated by 
    136      * providing the same seed. 
     118     * Random number generators that require a seed value include all PRNGs. The seed is used as 
     119     * the starting point of the pseudo random sequence. A particular sequence can be repeated 
     120     * by providing the same seed. 
    137121     * 
    138      * \param s The seed value. This value is usually required to be in 
    139      * the same range as the generator's output, but that does not need 
    140      * to be the case in general. 
     122     * \param s The seed value. This value is usually required to be in the same range as the 
     123     * generator's output, but that does not need to be the case in general. 
    141124     * 
    142      * \warning If an attacker can guess the seed value used, the 
    143      * attacker can compute the pseudo random sequence generated. Thus 
    144      * in security sensitive applications, seed values must be choosen 
    145      * in an unguessable way. 
     125     * \warning If an attacker can guess the seed value used, the attacker can compute the 
     126     * pseudo random sequence generated. Thus in security sensitive applications, seed values 
     127     * must be choosen in an unguessable way. 
    146128     */ 
    147129    virtual void seed(unsigned s) = 0; 
     
    149131    //! Uses the current time of day to generate a seed. 
    150132    /*! 
    151      * \warning Be careful creating too many objects that are seeded 
    152      * this way. If you seed them all quickly enough they may get the 
    153      * same seed. Even if you seed them slowly, there may be resonances 
    154      * between your program and the system clock. 
     133     * \warning Be careful creating too many objects that are seeded this way. If you seed them 
     134     * all quickly enough they may get the same seed. Even if you seed them slowly, there may be 
     135     * resonances between your program and the system clock. 
    155136     * 
    156      * \warning The current time is too guessable for use in security 
    157      * sensitive applications. 
     137     * \warning The current time is too guessable for use in security sensitive applications. 
    158138     */ 
    159139    void time_seed(); 
     
    163143  //! Wrapper around the standard C library's PRNG. 
    164144  /*! 
    165    * \warning Because the standard random number generator keeps its 
    166    * seed in a static object in the library, all objects of type 
    167    * standard_random are interrelated. Be careful using this class! 
     145   * \warning Because the standard random number generator keeps its seed in a static object in 
     146   * the library, all objects of type standard_random are interrelated. Be careful using this 
     147   * class! 
    168148   */ 
    169149  class standard_random : public seeded_random { 
     
    184164  //! Linear congruential PRNG. 
    185165  /*! 
    186    * This generator has a period of 1771875 states. All objects from this 
    187    * class are independent and have different internal states. 
     166   * This generator has a period of 1771875 states. All objects from this class are independent 
     167   * and have different internal states. 
    188168   * 
    189    * \warning Like all linear congruential generators, this generator is 
    190    * not suitable for use in security sensitive applications. 
     169   * \warning Like all linear congruential generators, this generator is not suitable for use in 
     170   * security sensitive applications. 
    191171   * 
    192    * \todo Generalize this class so that the user can provide the 
    193    * constants used in the linear congruential computations. It might 
    194    * also be nice to provide several "defaults" (selectable with a 
    195    * method call perhaps) so that users can use the generator without 
    196    * much fuss. 
     172   * \todo Generalize this class so that the user can provide the constants used in the linear 
     173   * congruential computations. It might also be nice to provide several "defaults" (selectable 
     174   * with a method call perhaps) so that users can use the generator without much fuss. 
    197175   */ 
    198176  class linear_congruential : public seeded_random { 
     
    203181    virtual ~linear_congruential() { } 
    204182 
    205     // The constants below ensure maximum period and their values take 
    206     // advantage of the range on a 32 bit unsigned quantity. 
     183    // The constants below ensure maximum period and their values take advantage of the range 
     184    // on a 32 bit unsigned quantity. 
    207185    // 
    208186    virtual unsigned next() 
  • src/random_test.cpp

    r1 r2  
    11/**************************************************************************** 
    2 FILE          : random_test.c 
    3 LAST REVISION : 2005-11-21 
    4 SUBJECT       : Random number generator test program. 
    5 PROGRAMMER    : (C) Copyright 2005 by Peter C. Chapin 
     2FILE      : random_test.c 
     3SUBJECT   : Random number generator test program. 
     4PROGRAMMER: (C) Copyright 2012 by Peter C. Chapin 
    65 
    7 Although there are RNG test suites out there, I thought it would be 
    8 instructive to write a few tests "manually". 
     6Although there are RNG test suites out there, I thought it would be instructive to write a few 
     7tests "manually". 
    98 
    10 Please send comments or bug reports to 
    11  
    12      Peter C. Chapin 
    13      Electrical and Computer Engineering Technology 
    14      Vermont Technical College 
    15      Randolph Center, VT 05061 
    16      pchapin@ecet.vtc.edu 
    179****************************************************************************/ 
    1810 
Note: See TracChangeset for help on using the changeset viewer.