Changeset 2245:f09b1ea5c249 in lemon-0.x

Timestamp:

10/17/06 12:40:28 (18 years ago)

Author:

Balazs Dezso

Branch:

default

Phase:

public

Convert:

svn:c9d7d8f5-90d6-0310-b91f-818b3a526b0e/lemon/trunk@2995

Message:

Little modification on interface and documentation

File:

• lemon/random.h (modified) (8 diffs)

lemon/random.h

@@ -423 +423 @@
   /// 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
@@ -449 +459 @@
   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;
@@ -487 +494 @@
     ///
     /// 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);
@@ -495 +504 @@
     ///
     /// 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) {
@@ -505 +516 @@
     /// \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.
-    template <typename Number>
-    Number operator()() {
+    /// It returns a random real number from the range [0, 1). The
+    /// default Number type is double.
+    template <typename Number>
+    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>();
     }
 
@@ -521 +555 @@
     template <typename Number>
     Number operator()(Number b) { 
-      return operator()<Number>() * b; 
+      return real<Number>() * b; 
     }
 
@@ -529 +563 @@
     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, ..., bound - 1}.
-    template <typename Number>
-    Number operator[](const Number& bound) {
-      return _random_bits::Mapping<Number, Word>::map(core, bound);
+    /// 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 {a, a + 1, ..., b - 1}.
+    template <typename Number>
+    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);
     }
 
@@ -587 +637 @@
 
 
-  /// \brief Global random number generator instance
-  ///
-  /// A global mersenne twister random number generator instance
   extern Random rnd;