| 1 | <html> |
|---|
| 2 | |
|---|
| 3 | <head> |
|---|
| 4 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
|---|
| 5 | |
|---|
| 6 | <title>Boost Random Number Library Variate Generator</title> |
|---|
| 7 | </head> |
|---|
| 8 | |
|---|
| 9 | <body bgcolor="#FFFFFF" text="#000000"> |
|---|
| 10 | |
|---|
| 11 | <h1>Boost Random Number Library Variate Generator</h1> |
|---|
| 12 | |
|---|
| 13 | A random variate generator is used to join a random number generator |
|---|
| 14 | together with a random number distribution. |
|---|
| 15 | Boost.Random provides a vast choice of |
|---|
| 16 | <a href="random-generators.html">generators</a> |
|---|
| 17 | as well as |
|---|
| 18 | <a href="random-distributions.html">distributions</a> |
|---|
| 19 | . |
|---|
| 20 | |
|---|
| 21 | |
|---|
| 22 | <h2><a name="variate_generator">Class template <code>variate_generator</code></h2> |
|---|
| 23 | |
|---|
| 24 | <h3>Synopsis</h3> |
|---|
| 25 | <pre> |
|---|
| 26 | #include <<a href="../../boost/random/variate_generator.hpp">boost/random/variate_generator.hpp</a>> |
|---|
| 27 | |
|---|
| 28 | template<class Engine, class Distribution> |
|---|
| 29 | class variate_generator |
|---|
| 30 | { |
|---|
| 31 | public: |
|---|
| 32 | typedef Engine engine_type; |
|---|
| 33 | typedef Distribution distribution_type; |
|---|
| 34 | typedef typename Distribution::result_type result_type; |
|---|
| 35 | |
|---|
| 36 | variate_generator(Engine e, Distribution d); |
|---|
| 37 | |
|---|
| 38 | result_type operator()(); |
|---|
| 39 | template<class T> |
|---|
| 40 | result_type operator()(T value); |
|---|
| 41 | |
|---|
| 42 | engine_value_type& engine(); |
|---|
| 43 | const engine_value_type& engine() const; |
|---|
| 44 | |
|---|
| 45 | result_type min() const; |
|---|
| 46 | result_type max() const; |
|---|
| 47 | }; |
|---|
| 48 | </pre> |
|---|
| 49 | |
|---|
| 50 | <h3>Description</h3> |
|---|
| 51 | |
|---|
| 52 | Instantations of class template <code>variate_generator</code> model a |
|---|
| 53 | <a href="random-concepts.html#number_generator">number generator</a>. |
|---|
| 54 | <p> |
|---|
| 55 | The argument for the template parameter <code>Engine</code> shall be |
|---|
| 56 | of the form U, U&, or U*, where U models a uniform random number |
|---|
| 57 | generator. Then, the member <code>engine_value_type</code> names U |
|---|
| 58 | (not the pointer or reference to U). |
|---|
| 59 | <p> |
|---|
| 60 | |
|---|
| 61 | Specializations of <code>variate_generator</code> satisfy the |
|---|
| 62 | requirements of CopyConstructible. They also satisfy the requirements |
|---|
| 63 | of Assignable unless the template parameter Engine is of the form U&. |
|---|
| 64 | <p> |
|---|
| 65 | |
|---|
| 66 | The complexity of all functions specified in this section is |
|---|
| 67 | constant. No function described in this section except the constructor |
|---|
| 68 | throws an exception. |
|---|
| 69 | |
|---|
| 70 | <pre> variate_generator(engine_type eng, distribution_type d)</pre> |
|---|
| 71 | <strong>Effects:</strong> Constructs a <code>variate_generator</code> |
|---|
| 72 | object with the associated uniform random number generator |
|---|
| 73 | <code>eng</code> and the associated random distribution |
|---|
| 74 | <code>d</code>. |
|---|
| 75 | <br> |
|---|
| 76 | <strong>Throws:</strong> If and what the copy constructor of Engine or |
|---|
| 77 | Distribution throws. |
|---|
| 78 | |
|---|
| 79 | <pre> result_type operator()()</pre> |
|---|
| 80 | <strong>Returns:</strong> <code>distribution()(e)</code> |
|---|
| 81 | <br> |
|---|
| 82 | <strong>Notes:</strong> The sequence of numbers produced by the |
|---|
| 83 | uniform random number generator <code>e</code>, s<sub>e</sub>, is |
|---|
| 84 | obtained from the sequence of numbers produced by the associated |
|---|
| 85 | uniform random number generator <code>eng</code>, s<sub>eng</sub>, as |
|---|
| 86 | follows: Consider the values of |
|---|
| 87 | <code>numeric_limits<<em>T</em>>::is_integer</code> for |
|---|
| 88 | <code><em>T</em></code> both <code>Distribution::input_type</code> and |
|---|
| 89 | <code>engine_value_type::result_type</code>. If the values for both |
|---|
| 90 | types are <code>true</code>, then s<sub>e</sub> is identical to |
|---|
| 91 | s<sub>eng</sub>. Otherwise, if the values for both types are |
|---|
| 92 | <code>false</code>, then the numbers in s<sub>eng</sub> are divided by |
|---|
| 93 | <code>engine().max()-engine().min()</code> to obtain the |
|---|
| 94 | numbers in s<sub>e</sub>. Otherwise, if the value for |
|---|
| 95 | <code>engine_value_type::result_type</code> is <code>true</code> and |
|---|
| 96 | the value for <code>Distribution::input_type</code> is |
|---|
| 97 | <code>false</code>, then the numbers in s<sub>eng</sub> are divided by |
|---|
| 98 | <code>engine().max()-engine().min()+1</code> to obtain the |
|---|
| 99 | numbers in s<sub>e</sub>. Otherwise, the mapping from s<sub>eng</sub> |
|---|
| 100 | to s<sub>e</sub> is implementation-defined. In all cases, an implicit |
|---|
| 101 | conversion from <code>engine_value_type::result_type</code> to |
|---|
| 102 | <code>Distribution::input_type</code> is performed. If such a |
|---|
| 103 | conversion does not exist, the program is ill-formed. |
|---|
| 104 | |
|---|
| 105 | <pre> template<class T> result_type operator()(T value)</pre> |
|---|
| 106 | <strong>Returns:</strong> <code>distribution()(e, value)</code>. For |
|---|
| 107 | the semantics of <code>e</code>, see the description of |
|---|
| 108 | <code>operator()()</code>. |
|---|
| 109 | |
|---|
| 110 | <pre> engine_value_type& engine()</pre> |
|---|
| 111 | <strong>Returns:</strong> A reference to the associated uniform random |
|---|
| 112 | number generator. |
|---|
| 113 | |
|---|
| 114 | <pre> const engine_value_type& engine() const</pre> |
|---|
| 115 | <strong>Returns:</strong> A reference to the associated uniform random |
|---|
| 116 | number generator. |
|---|
| 117 | |
|---|
| 118 | <pre> distribution_type& distribution()</pre> |
|---|
| 119 | <strong>Returns:</strong> A reference to the associated random |
|---|
| 120 | distribution. |
|---|
| 121 | |
|---|
| 122 | <pre> const distribution_type& distribution() const</pre> |
|---|
| 123 | <strong>Returns:</strong> A reference to the associated random |
|---|
| 124 | distribution. |
|---|
| 125 | |
|---|
| 126 | <pre> result_type min() const</pre> |
|---|
| 127 | <strong>Precondition:</strong> <code>distribution().min()</code> is |
|---|
| 128 | well-formed |
|---|
| 129 | <br> |
|---|
| 130 | <strong>Returns:</strong> <code>distribution().min()</code> |
|---|
| 131 | |
|---|
| 132 | <pre> result_type max() const</pre> |
|---|
| 133 | <strong>Precondition:</strong> <code>distribution().max()</code> is |
|---|
| 134 | well-formed |
|---|
| 135 | <br> |
|---|
| 136 | <strong>Returns:</strong> <code>distribution().max()</code> |
|---|
| 137 | |
|---|
| 138 | <p> |
|---|
| 139 | <hr> |
|---|
| 140 | <a href="../../people/jens_maurer.htm">Jens Maurer</a>, |
|---|
| 141 | 2003-10-25 |
|---|
| 142 | |
|---|
| 143 | </body> |
|---|
| 144 | </html> |
|---|
