[Lemon-commits] [lemon_svn] deba: r2995 - hugo/trunk/lemon

[Lemon SVN]

Author: deba
Date: Tue Oct 17 12:40:28 2006
New Revision: 2995

Modified:
   hugo/trunk/lemon/random.h

Log:
Little modification on interface and documentation



Modified: hugo/trunk/lemon/random.h
==============================================================================
--- hugo/trunk/lemon/random.h	(original)
+++ hugo/trunk/lemon/random.h	Tue Oct 17 12:40:28 2006
@@ -422,37 +422,44 @@
   ///
   /// The generator gives back random numbers of serveral types. To
   /// get a random number from a range of a floating point type you
-  /// can use one form of the \c operator(). If you want to get random
-  /// number from a the {0, 1, ..., n-1} integer range use the \c
-  /// operator[]. And to get random number from the whole range of an
-  /// integer type you can use the \c integer() or \c uinteger()
-  /// functions. After all you can get random bool with equal chance
-  /// or given probability with the \c boolean() member function.
+  /// can use one form of the \c operator() or the \c real() member
+  /// function. If you want to get random number from the {0, 1, ...,
+  /// n-1} integer range use the \c operator[] or the \c integer()
+  /// method. And to get random number from the whole range of an
+  /// integer type you can use the argumentless \c integer() or \c
+  /// uinteger() functions. After all you can get random bool with
+  /// equal chance of true and false or given probability of true
+  /// result with the \c boolean() member functions.
   ///
   ///\code
-  /// int a = rnd[100000];                  // 0..99999
+  /// // The commented code is identical to the other
+  /// double a = rnd();                     // [0.0, 1.0)
+  /// // double a = rnd.real();             // [0.0, 1.0)
+  /// double b = rnd(100.0);                // [0.0, 100.0)
+  /// // double b = rnd.real(100.0);        // [0.0, 100.0)
+  /// double c = rnd(1.0, 2.0);             // [1.0, 2.0)
+  /// // double c = rnd.real(1.0, 2.0);     // [1.0, 2.0)
+  /// int d = rnd[100000];                  // 0..99999
+  /// // int d = rnd.integer(100000);       // 0..99999
+  /// int e = rnd[6] + 1;                   // 1..6
+  /// // int e = rnd.integer(1, 1 + 6);     // 1..6
   /// int b = rnd.uinteger<int>();          // 0 .. 2^31 - 1
   /// int c = rnd.integer<int>();           // - 2^31 .. 2^31 - 1
-  /// double d = rnd();                     // [0.0, 1.0)
-  /// double e = rnd(100.0);                // [0.0, 100.0)
-  /// double f = rnd(1.0, 2.0);             // [1.0, 2.0)
   /// bool g = rnd.boolean();               // P(g = true) = 0.5
   /// bool h = rnd.boolean(0.8);            // P(h = true) = 0.8
   ///\endcode
   ///
-  /// The lemon provides a global instance of the random number generator
-  /// which name is \c rnd. Usually it is a good programming convenience
-  /// to use this global generator to get random numbers.
+  /// The lemon provides a global instance of the random number
+  /// generator which name is \ref lemon::rnd "rnd". Usually it is a
+  /// good programming convenience to use this global generator to get
+  /// random numbers.
   ///
   /// \author Balazs Dezso
   class Random {
   private:
 
-#if WORD_BIT == 32
-    typedef unsigned int Word;
-#elif WORD_BIT == 64
+    // architecture word
     typedef unsigned long Word;
-#endif
     
     _random_bits::RandomCore<Word> core;
 
@@ -486,7 +493,9 @@
     /// \brief Copy constructor
     ///
     /// Copy constructor. The generated sequence will be identical to
-    /// the other sequence.
+    /// the other sequence. It can be used to save the current state
+    /// of the generator and later use it to generate the same
+    /// sequence.
     Random(const Random& other) {
       core.copyState(other.core);
     }
@@ -494,7 +503,9 @@
     /// \brief Assign operator
     ///
     /// Assign operator. The generated sequence will be identical to
-    /// the other sequence.
+    /// the other sequence. It can be used to save the current state
+    /// of the generator and later use it to generate the same
+    /// sequence.
     Random& operator=(const Random& other) {
       if (&other != this) {
         core.copyState(other.core);
@@ -504,15 +515,38 @@
 
     /// \brief Returns a random real number
     ///
-    /// It returns a random real number from the range [0, 1). The default
-    /// result type of this function is double.
+    /// It returns a random real number from the range [0, 1). The
+    /// default Number type is double.
     template <typename Number>
-    Number operator()() {
+    Number real() {
       return _random_bits::RealConversion<Number, Word>::convert(core);
     }
 
+    double real() {
+      return real<double>();
+    }
+
+    /// \brief Returns a random real number
+    ///
+    /// It returns a random real number from the range [0, b).
+    template <typename Number>
+    Number real(Number b) { 
+      return real<Number>() * b; 
+    }
+
+    /// \brief Returns a random real number
+    ///
+    /// It returns a random real number from the range [a, b).
+    template <typename Number>
+    Number real(Number a, Number b) { 
+      return real<Number>() * (b - a) + a; 
+    }
+
+    /// \brief Returns a random real number
+    ///
+    /// It returns a random double from the range [0, 1).
     double operator()() {
-      return operator()<double>();
+      return real<double>();
     }
 
     /// \brief Returns a random real number
@@ -520,7 +554,7 @@
     /// It returns a random real number from the range [0, b).
     template <typename Number>
     Number operator()(Number b) { 
-      return operator()<Number>() * b; 
+      return real<Number>() * b; 
     }
 
     /// \brief Returns a random real number
@@ -528,15 +562,31 @@
     /// It returns a random real number from the range [a, b).
     template <typename Number>
     Number operator()(Number a, Number b) { 
-      return operator()<Number>() * (b - a) + a; 
+      return real<Number>() * (b - a) + a; 
+    }
+
+    /// \brief Returns a random integer from a range
+    ///
+    /// It returns a random integer from the range {0, 1, ..., b - 1}.
+    template <typename Number>
+    Number integer(Number b) {
+      return _random_bits::Mapping<Number, Word>::map(core, b);
     }
 
     /// \brief Returns a random integer from a range
     ///
-    /// It returns a random integer from the range {0, 1, ..., bound - 1}.
+    /// It returns a random integer from the range {a, a + 1, ..., b - 1}.
     template <typename Number>
-    Number operator[](const Number& bound) {
-      return _random_bits::Mapping<Number, Word>::map(core, bound);
+    Number integer(Number a, Number b) {
+      return _random_bits::Mapping<Number, Word>::map(core, b - a) + a;
+    }
+
+    /// \brief Returns a random integer from a range
+    ///
+    /// It returns a random integer from the range {0, 1, ..., b - 1}.
+    template <typename Number>
+    Number operator[](Number b) {
+      return _random_bits::Mapping<Number, Word>::map(core, b);
     }
 
     /// \brief Returns a random non-negative integer
@@ -586,9 +636,6 @@
   };
 
 
-  /// \brief Global random number generator instance
-  ///
-  /// A global mersenne twister random number generator instance
   extern Random rnd;
 
 }