boost/random/variate_generator.hpp

   1 /* boost random/variate_generator.hpp header file
   2  *
   3  * Copyright Jens Maurer 2002
   4  * Copyright Steven Watanabe 2011
   5  * Distributed under the Boost Software License, Version 1.0. (See
   6  * accompanying file LICENSE_1_0.txt or copy at
   7  * http://www.boost.org/LICENSE_1_0.txt)
   8  *
   9  * See http://www.boost.org for most recent version including documentation.
  10  *
  11  * $Id: variate_generator.hpp 71018 2011-04-05 21:27:52Z steven_watanabe $
  12  *
  13  */
  14
  15 #ifndef BOOST_RANDOM_RANDOM_GENERATOR_HPP
  16 #define BOOST_RANDOM_RANDOM_GENERATOR_HPP
  17
  18 #include <boost/random/detail/ptr_helper.hpp>
  19
  20 #include <boost/random/detail/disable_warnings.hpp>
  21
  22 namespace boost {
  23
  24 /// \cond hide_private_members
  25
  26 namespace random {
  27
  28 ///\endcond
  29
  30 /**
  31  * A random variate generator is used to join a random number
  32  * generator together with a random number distribution.
  33  * Boost.Random provides a vast choice of \generators as well
  34  * as \distributions.
  35  *
  36  * The argument for the template parameter Engine shall be of
  37  * the form U, U&, or U*, where U models a
  38  * \uniform_random_number_generator.  Then, the member
  39  * engine_value_type names U (not the pointer or reference to U).
  40  *
  41  * Specializations of @c variate_generator satisfy the
  42  * requirements of CopyConstructible. They also satisfy the
  43  * requirements of Assignable unless the template parameter
  44  * Engine is of the form U&.
  45  *
  46  * The complexity of all functions specified in this section
  47  * is constant. No function described in this section except
  48  * the constructor throws an exception.
  49  */
  50 template<class Engine, class Distribution>
  51 class variate_generator
  52 {
  53 private:
  54     typedef boost::random::detail::ptr_helper<Engine> helper_type;
  55 public:
  56     typedef typename helper_type::value_type engine_value_type;
  57     typedef Engine engine_type;
  58     typedef Distribution distribution_type;
  59     typedef typename Distribution::result_type result_type;
  60
  61     /**
  62      * Constructs a @c variate_generator object with the associated
  63      * \uniform_random_number_generator eng and the associated
  64      * \random_distribution d.
  65      *
  66      * Throws: If and what the copy constructor of Engine or
  67      * Distribution throws.
  68      */
  69     variate_generator(Engine e, Distribution d)
  70       : _eng(e), _dist(d) { }
  71
  72     /** Returns: distribution()(engine()) */
  73     result_type operator()() { return _dist(engine()); }
  74     /**
  75      * Returns: distribution()(engine(), value).
  76      */
  77     template<class T>
  78     result_type operator()(const T& value) { return _dist(engine(), value); }
  79
  80     /**
  81      * Returns: A reference to the associated uniform random number generator.
  82      */
  83     engine_value_type& engine() { return helper_type::ref(_eng); }
  84     /**
  85      * Returns: A reference to the associated uniform random number generator.
  86      */
  87     const engine_value_type& engine() const { return helper_type::ref(_eng); }
  88
  89     /** Returns: A reference to the associated \random_distribution. */
  90     distribution_type& distribution() { return _dist; }
  91     /**
  92      * Returns: A reference to the associated random distribution.
  93      */
  94     const distribution_type& distribution() const { return _dist; }
  95
  96     /**
  97      * Precondition: distribution().min() is well-formed
  98      *
  99      * Returns: distribution().min()
 100      */
 101     result_type min BOOST_PREVENT_MACRO_SUBSTITUTION () const { return (distribution().min)(); }
 102     /**
 103      * Precondition: distribution().max() is well-formed
 104      *
 105      * Returns: distribution().max()
 106      */
 107     result_type max BOOST_PREVENT_MACRO_SUBSTITUTION () const { return (distribution().max)(); }
 108
 109 private:
 110     Engine _eng;
 111     distribution_type _dist;
 112 };
 113
 114 } // namespace random
 115
 116 using random::variate_generator;
 117
 118 } // namespace boost
 119
 120 #include <boost/random/detail/enable_warnings.hpp>
 121
 122 #endif // BOOST_RANDOM_RANDOM_GENERATOR_HPP