boost/random/variate_generator.hpp

0001 /* boost random/variate_generator.hpp header file
0002  *
0003  * Copyright Jens Maurer 2002
0004  * Copyright Steven Watanabe 2011
0005  * Distributed under the Boost Software License, Version 1.0. (See
0006  * accompanying file LICENSE_1_0.txt or copy at
0007  * http://www.boost.org/LICENSE_1_0.txt)
0008  *
0009  * See http://www.boost.org for most recent version including documentation.
0010  *
0011  * $Id$
0012  *
0013  */
0014
0015 #ifndef BOOST_RANDOM_RANDOM_GENERATOR_HPP
0016 #define BOOST_RANDOM_RANDOM_GENERATOR_HPP
0017
0018 #include <boost/random/detail/ptr_helper.hpp>
0019
0020 #include <boost/random/detail/disable_warnings.hpp>
0021
0022 namespace boost {
0023
0024 /// \cond hide_private_members
0025
0026 namespace random {
0027
0028 ///\endcond
0029
0030 /**
0031  * A random variate generator is used to join a random number
0032  * generator together with a random number distribution.
0033  * Boost.Random provides a vast choice of \generators as well
0034  * as \distributions.
0035  *
0036  * The argument for the template parameter Engine shall be of
0037  * the form U, U&, or U*, where U models a
0038  * \uniform_random_number_generator.  Then, the member
0039  * engine_value_type names U (not the pointer or reference to U).
0040  *
0041  * Specializations of @c variate_generator satisfy the
0042  * requirements of CopyConstructible. They also satisfy the
0043  * requirements of Assignable unless the template parameter
0044  * Engine is of the form U&.
0045  *
0046  * The complexity of all functions specified in this section
0047  * is constant. No function described in this section except
0048  * the constructor throws an exception.
0049  */
0050 template<class Engine, class Distribution>
0051 class variate_generator
0052 {
0053 private:
0054     typedef boost::random::detail::ptr_helper<Engine> helper_type;
0055 public:
0056     typedef typename helper_type::value_type engine_value_type;
0057     typedef Engine engine_type;
0058     typedef Distribution distribution_type;
0059     typedef typename Distribution::result_type result_type;
0060
0061     /**
0062      * Constructs a @c variate_generator object with the associated
0063      * \uniform_random_number_generator eng and the associated
0064      * \random_distribution d.
0065      *
0066      * Throws: If and what the copy constructor of Engine or
0067      * Distribution throws.
0068      */
0069     variate_generator(Engine e, Distribution d)
0070       : _eng(e), _dist(d) { }
0071
0072     /** Returns: distribution()(engine()) */
0073     result_type operator()() { return _dist(engine()); }
0074     /**
0075      * Returns: distribution()(engine(), value).
0076      */
0077     template<class T>
0078     result_type operator()(const T& value) { return _dist(engine(), value); }
0079
0080     /**
0081      * Returns: A reference to the associated uniform random number generator.
0082      */
0083     engine_value_type& engine() { return helper_type::ref(_eng); }
0084     /**
0085      * Returns: A reference to the associated uniform random number generator.
0086      */
0087     const engine_value_type& engine() const { return helper_type::ref(_eng); }
0088
0089     /** Returns: A reference to the associated \random_distribution. */
0090     distribution_type& distribution() { return _dist; }
0091     /**
0092      * Returns: A reference to the associated random distribution.
0093      */
0094     const distribution_type& distribution() const { return _dist; }
0095
0096     /**
0097      * Precondition: distribution().min() is well-formed
0098      *
0099      * Returns: distribution().min()
0100      */
0101     result_type min BOOST_PREVENT_MACRO_SUBSTITUTION () const { return (distribution().min)(); }
0102     /**
0103      * Precondition: distribution().max() is well-formed
0104      *
0105      * Returns: distribution().max()
0106      */
0107     result_type max BOOST_PREVENT_MACRO_SUBSTITUTION () const { return (distribution().max)(); }
0108
0109 private:
0110     Engine _eng;
0111     distribution_type _dist;
0112 };
0113
0114 } // namespace random
0115
0116 using random::variate_generator;
0117
0118 } // namespace boost
0119
0120 #include <boost/random/detail/enable_warnings.hpp>
0121
0122 #endif // BOOST_RANDOM_RANDOM_GENERATOR_HPP