boost/random/variate_generator.hpp

   1 /* boost random/variate_generator.hpp header file
   2  *
   3  * Copyright Jens Maurer 2002
   4  * Distributed under the Boost Software License, Version 1.0. (See
   5  * accompanying file LICENSE_1_0.txt or copy at
   6  * http://www.boost.org/LICENSE_1_0.txt)
   7  *
   8  * See http://www.boost.org for most recent version including documentation.
   9  *
  10  * $Id: variate_generator.hpp 60755 2010-03-22 00:45:06Z steven_watanabe $
  11  *
  12  */
  13
  14 #ifndef BOOST_RANDOM_RANDOM_GENERATOR_HPP
  15 #define BOOST_RANDOM_RANDOM_GENERATOR_HPP
  16
  17 #include <boost/config.hpp>
  18
  19 // implementation details
  20 #include <boost/detail/workaround.hpp>
  21 #include <boost/random/uniform_01.hpp>
  22 #include <boost/random/detail/pass_through_engine.hpp>
  23 #include <boost/random/detail/uniform_int_float.hpp>
  24 #include <boost/random/detail/ptr_helper.hpp>
  25
  26 // Borland C++ 5.6.0 has problems using its numeric_limits traits as
  27 // template parameters
  28 #if BOOST_WORKAROUND(__BORLANDC__, <= 0x564)
  29 #include <boost/type_traits/is_integral.hpp>
  30 #endif
  31
  32 #include <boost/random/detail/disable_warnings.hpp>
  33
  34 namespace boost {
  35
  36 /// \cond hide_private_members
  37
  38 namespace random {
  39 namespace detail {
  40
  41 template<bool have_int, bool want_int>
  42 struct engine_helper;
  43
  44 // for consistency, always have two levels of decorations
  45 template<>
  46 struct engine_helper<true, true>
  47 {
  48   template<class Engine, class DistInputType>
  49   struct impl
  50   {
  51     typedef pass_through_engine<Engine> type;
  52   };
  53 };
  54
  55 template<>
  56 struct engine_helper<false, false>
  57 {
  58   template<class Engine, class DistInputType>
  59   struct impl
  60   {
  61     typedef uniform_01<Engine, DistInputType> type;
  62   };
  63 };
  64
  65 template<>
  66 struct engine_helper<true, false>
  67 {
  68   template<class Engine, class DistInputType>
  69   struct impl
  70   {
  71     typedef uniform_01<Engine, DistInputType> type;
  72   };
  73 };
  74
  75 template<>
  76 struct engine_helper<false, true>
  77 {
  78   template<class Engine, class DistInputType>
  79   struct impl
  80   {
  81     typedef uniform_int_float<Engine, unsigned long> type;
  82   };
  83 };
  84
  85 } // namespace detail
  86 } // namespace random
  87
  88 ///\endcond
  89
  90 /**
  91  * A random variate generator is used to join a random number
  92  * generator together with a random number distribution.
  93  * Boost.Random provides a vast choice of \generators as well
  94  * as \distributions.
  95  *
  96  * Instantations of class template @c variate_generator model
  97  * a \number_generator.
  98  *
  99  * The argument for the template parameter Engine shall be of
 100  * the form U, U&, or U*, where U models a
 101  * \uniform_random_number_generator.  Then, the member
 102  * engine_value_type names U (not the pointer or reference to U).
 103  *
 104  * Specializations of @c variate_generator satisfy the
 105  * requirements of CopyConstructible. They also satisfy the
 106  * requirements of Assignable unless the template parameter
 107  * Engine is of the form U&.
 108  *
 109  * The complexity of all functions specified in this section
 110  * is constant. No function described in this section except
 111  * the constructor throws an exception.
 112  */
 113 template<class Engine, class Distribution>
 114 class variate_generator
 115 {
 116 private:
 117   typedef random::detail::pass_through_engine<Engine> decorated_engine;
 118
 119 public:
 120   typedef typename decorated_engine::base_type engine_value_type;
 121   typedef Engine engine_type;
 122   typedef Distribution distribution_type;
 123   typedef typename Distribution::result_type result_type;
 124
 125   /**
 126    * Constructs a @c variate_generator object with the associated
 127    * \uniform_random_number_generator eng and the associated
 128    * \random_distribution d.
 129    *
 130    * Throws: If and what the copy constructor of Engine or
 131    * Distribution throws.
 132    */
 133   variate_generator(Engine e, Distribution d)
 134     : _eng(decorated_engine(e)), _dist(d) { }
 135
 136   /**
 137    * Returns: distribution()(e)
 138    *
 139    * Notes: The sequence of numbers produced by the
 140    * \uniform_random_number_generator e, s<sub>e</sub>, is
 141    * obtained from the sequence of numbers produced by the
 142    * associated \uniform_random_number_generator eng, s<sub>eng</sub>,
 143    * as follows: Consider the values of @c numeric_limits<T>::is_integer
 144    * for @c T both @c Distribution::input_type and
 145    * @c engine_value_type::result_type. If the values for both types are
 146    * true, then se is identical to s<sub>eng</sub>. Otherwise, if the
 147    * values for both types are false, then the numbers in s<sub>eng</sub>
 148    * are divided by engine().max()-engine().min() to obtain the numbers
 149    * in s<sub>e</sub>. Otherwise, if the value for
 150    * @c engine_value_type::result_type is true and the value for
 151    * @c Distribution::input_type is false, then the numbers in s<sub>eng</sub>
 152    * are divided by engine().max()-engine().min()+1 to obtain the numbers in
 153    * s<sub>e</sub>. Otherwise, the mapping from s<sub>eng</sub> to
 154    * s<sub>e</sub> is implementation-defined. In all cases, an
 155    * implicit conversion from @c engine_value_type::result_type to
 156    * @c Distribution::input_type is performed. If such a conversion does
 157    * not exist, the program is ill-formed.
 158    */
 159   result_type operator()() { return _dist(_eng); }
 160   /**
 161    * Returns: distribution()(e, value).
 162    * For the semantics of e, see the description of operator()().
 163    */
 164   template<class T>
 165   result_type operator()(T value) { return _dist(_eng, value); }
 166
 167   /**
 168    * Returns: A reference to the associated uniform random number generator.
 169    */
 170   engine_value_type& engine() { return _eng.base().base(); }
 171   /**
 172    * Returns: A reference to the associated uniform random number generator.
 173    */
 174   const engine_value_type& engine() const { return _eng.base().base(); }
 175
 176   /**
 177    * Returns: A reference to the associated random distribution.
 178    */
 179   distribution_type& distribution() { return _dist; }
 180   /**
 181    * Returns: A reference to the associated random distribution.
 182    */
 183   const distribution_type& distribution() const { return _dist; }
 184
 185   /**
 186    * Precondition: distribution().min() is well-formed
 187    *
 188    * Returns: distribution().min()
 189    */
 190   result_type min BOOST_PREVENT_MACRO_SUBSTITUTION () const { return (distribution().min)(); }
 191   /**
 192    * Precondition: distribution().max() is well-formed
 193    *
 194    * Returns: distribution().max()
 195    */
 196   result_type max BOOST_PREVENT_MACRO_SUBSTITUTION () const { return (distribution().max)(); }
 197
 198 private:
 199 #if BOOST_WORKAROUND(__BORLANDC__, <= 0x564)
 200   typedef typename random::detail::engine_helper<
 201     ::boost::is_integral<typename decorated_engine::result_type>::value,
 202     ::boost::is_integral<typename Distribution::input_type>::value
 203     >::BOOST_NESTED_TEMPLATE impl<decorated_engine, typename Distribution::input_type>::type internal_engine_type;
 204 #else
 205   enum {
 206     have_int = std::numeric_limits<typename decorated_engine::result_type>::is_integer,
 207     want_int = std::numeric_limits<typename Distribution::input_type>::is_integer
 208   };
 209   typedef typename random::detail::engine_helper<have_int, want_int>::BOOST_NESTED_TEMPLATE impl<decorated_engine, typename Distribution::input_type>::type internal_engine_type;
 210 #endif
 211
 212   internal_engine_type _eng;
 213   distribution_type _dist;
 214 };
 215
 216 } // namespace boost
 217
 218 #include <boost/random/detail/disable_warnings.hpp>
 219
 220 #endif // BOOST_RANDOM_RANDOM_GENERATOR_HPP