1 /* boost random/variate_generator.hpp header file
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)
8 * See http://www.boost.org for most recent version including documentation.
10 * $Id: variate_generator.hpp 60755 2010-03-22 00:45:06Z steven_watanabe $
14 #ifndef BOOST_RANDOM_RANDOM_GENERATOR_HPP
15 #define BOOST_RANDOM_RANDOM_GENERATOR_HPP
17 #include <boost/config.hpp>
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>
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>
32 #include <boost/random/detail/disable_warnings.hpp>
36 /// \cond hide_private_members
41 template<bool have_int, bool want_int>
44 // for consistency, always have two levels of decorations
46 struct engine_helper<true, true>
48 template<class Engine, class DistInputType>
51 typedef pass_through_engine<Engine> type;
56 struct engine_helper<false, false>
58 template<class Engine, class DistInputType>
61 typedef uniform_01<Engine, DistInputType> type;
66 struct engine_helper<true, false>
68 template<class Engine, class DistInputType>
71 typedef uniform_01<Engine, DistInputType> type;
76 struct engine_helper<false, true>
78 template<class Engine, class DistInputType>
81 typedef uniform_int_float<Engine, unsigned long> type;
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
96 * Instantations of class template @c variate_generator model
97 * a \number_generator.
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).
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&.
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.
113 template<class Engine, class Distribution>
114 class variate_generator
117 typedef random::detail::pass_through_engine<Engine> decorated_engine;
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;
126 * Constructs a @c variate_generator object with the associated
127 * \uniform_random_number_generator eng and the associated
128 * \random_distribution d.
130 * Throws: If and what the copy constructor of Engine or
131 * Distribution throws.
133 variate_generator(Engine e, Distribution d)
134 : _eng(decorated_engine(e)), _dist(d) { }
137 * Returns: distribution()(e)
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.
159 result_type operator()() { return _dist(_eng); }
161 * Returns: distribution()(e, value).
162 * For the semantics of e, see the description of operator()().
165 result_type operator()(T value) { return _dist(_eng, value); }
168 * Returns: A reference to the associated uniform random number generator.
170 engine_value_type& engine() { return _eng.base().base(); }
172 * Returns: A reference to the associated uniform random number generator.
174 const engine_value_type& engine() const { return _eng.base().base(); }
177 * Returns: A reference to the associated random distribution.
179 distribution_type& distribution() { return _dist; }
181 * Returns: A reference to the associated random distribution.
183 const distribution_type& distribution() const { return _dist; }
186 * Precondition: distribution().min() is well-formed
188 * Returns: distribution().min()
190 result_type min BOOST_PREVENT_MACRO_SUBSTITUTION () const { return (distribution().min)(); }
192 * Precondition: distribution().max() is well-formed
194 * Returns: distribution().max()
196 result_type max BOOST_PREVENT_MACRO_SUBSTITUTION () const { return (distribution().max)(); }
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;
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
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;
212 internal_engine_type _eng;
213 distribution_type _dist;
218 #include <boost/random/detail/disable_warnings.hpp>
220 #endif // BOOST_RANDOM_RANDOM_GENERATOR_HPP