From 8c30753bf49504b5f677b8b410a3787907c86bd0 Mon Sep 17 00:00:00 2001 From: Steven Watanabe Date: Sun, 13 Feb 2011 03:28:59 +0000 Subject: [PATCH] Sync the docs with the current library. [SVN r68822] --- doc/Jamfile.v2 | 41 ++++++---- doc/concepts.qbk | 67 ++++------------- doc/distributions.qbk | 55 +++++++++++--- doc/random.qbk | 74 +++++++++---------- example/die.cpp | 26 +++---- example/password.cpp | 12 ++- example/weighted_die.cpp | 31 ++++---- include/boost/random/additive_combine.hpp | 4 +- .../boost/random/bernoulli_distribution.hpp | 3 - .../boost/random/binomial_distribution.hpp | 2 +- include/boost/random/cauchy_distribution.hpp | 3 - .../boost/random/chi_squared_distribution.hpp | 2 +- include/boost/random/discard_block.hpp | 4 + .../boost/random/discrete_distribution.hpp | 4 +- .../boost/random/exponential_distribution.hpp | 2 - .../boost/random/geometric_distribution.hpp | 6 +- include/boost/random/independent_bits.hpp | 10 +-- .../boost/random/inversive_congruential.hpp | 2 +- include/boost/random/lagged_fibonacci.hpp | 14 ++-- include/boost/random/linear_congruential.hpp | 6 +- .../boost/random/linear_feedback_shift.hpp | 4 +- .../boost/random/lognormal_distribution.hpp | 8 +- include/boost/random/mersenne_twister.hpp | 7 +- .../random/negative_binomial_distribution.hpp | 2 +- include/boost/random/normal_distribution.hpp | 5 -- .../piecewise_constant_distribution.hpp | 11 +-- .../random/piecewise_linear_distribution.hpp | 7 +- include/boost/random/poisson_distribution.hpp | 2 +- include/boost/random/random_device.hpp | 2 +- include/boost/random/seed_seq.hpp | 18 +++++ include/boost/random/shuffle_order.hpp | 12 ++- .../boost/random/student_t_distribution.hpp | 2 +- include/boost/random/subtract_with_carry.hpp | 30 +++++--- .../boost/random/triangle_distribution.hpp | 2 +- include/boost/random/uniform_01.hpp | 5 ++ include/boost/random/uniform_smallint.hpp | 6 +- include/boost/random/variate_generator.hpp | 3 - include/boost/random/xor_combine.hpp | 2 +- 38 files changed, 253 insertions(+), 243 deletions(-) diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 index 1199980..1b0971b 100644 --- a/doc/Jamfile.v2 +++ b/doc/Jamfile.v2 @@ -19,30 +19,40 @@ doxygen_files = bernoulli_distribution binomial_distribution cauchy_distribution + chi_squared_distribution discard_block discrete_distribution exponential_distribution extreme_value_distribution + fisher_f_distribution gamma_distribution geometric_distribution + independent_bits inversive_congruential lagged_fibonacci linear_congruential linear_feedback_shift lognormal_distribution mersenne_twister + negative_binomial_distribution normal_distribution + piecewise_constant_distribution + piecewise_linear_distribution poisson_distribution + random_device random_number_generator ranlux + seed_seq shuffle_order # shuffle_output + student_t_distribution subtract_with_carry + taus88 triangle_distribution uniform_01 - uniform_int + uniform_int_distribution uniform_on_sphere - uniform_real + uniform_real_distribution uniform_smallint variate_generator weibull_distribution @@ -62,7 +72,6 @@ local BOOST_ROOT = [ path.relative-to doxygen reference : $(here)/../../../boost/random/$(doxygen_files).hpp - $(here)/../../../boost/nondet_random.hpp $(here)/../../../boost/random.hpp : EXPAND_ONLY_PREDEF=YES @@ -78,25 +87,25 @@ doxygen reference : pseudo_random_number_generator=\"@xmlonly pseudo-random number generator @endxmlonly\" \\ uniform_random_number_generator=\"@xmlonly uniform random number generator @endxmlonly\" \\ nondeterministic_random_number_generator=\"@xmlonly non-deterministic random number generator @endxmlonly\" \\ - number_generator=\"@xmlonly number generator @endxmlonly\" \\ generators=\"@xmlonly generators @endxmlonly\" \\ distributions=\"@xmlonly distributions @endxmlonly\" \\ - additive_combine=\"@xmlonly additive_combine @endxmlonly\" \\ + additive_combine_engine=\"@xmlonly additive_combine_engine @endxmlonly\" \\ discard_block_engine=\"@xmlonly discard_block_engine @endxmlonly\" \\ - lagged_fibonacci=\"@xmlonlylagged_fibonacci@endxmlonly\" \\ + lagged_fibonacci_engine=\"@xmlonlylagged_fibonacci_engine@endxmlonly\" \\ + subtract_with_carry_01_engine=\"@xmlonlysubtract_with_carry_01_engine@endxmlonly\" \\ linear_congruential_engine=\"@xmlonlylinear_congruential_engine@endxmlonly\" \\ minstd_rand=\"@xmlonly minstd_rand @endxmlonly\" \\ minstd_rand0=\"@xmlonly minstd_rand0 @endxmlonly\" \\ rand48=\"@xmlonly rand48 @endxmlonly\" \\ mt11213b=\"@xmlonly mt11213b @endxmlonly\" \\ mt19937=\"@xmlonly mt19937 @endxmlonly\" \\ - ecuyer1988=\"@xmlonly ecuyer1988 @endxmlonly\" \\ - lagged_fibonacci607=\"@xmlonly lagged_fibonacci607 @endxmlonly\" \\ - lagged_fibonacci44497=\"@xmlonly lagged_fibonacci44497 @endxmlonly\" \\ - bernoulli_distribution=\"@xmlonly bernoulli_distribution @endxmlonly\" \\ - cauchy_distribution=\"@xmlonly cauchy_distribution @endxmlonly\" \\ - uniform_01=\"@xmlonlyuniform_01@endxmlonly\" \\ - random_device=\"@xmlonlyrandom_device@endxmlonly\"" + ecuyer1988=\"@xmlonly ecuyer1988 @endxmlonly\" \\ + lagged_fibonacci607=\"@xmlonly lagged_fibonacci607 @endxmlonly\" \\ + lagged_fibonacci44497=\"@xmlonly lagged_fibonacci44497 @endxmlonly\" \\ + bernoulli_distribution=\"@xmlonly bernoulli_distribution @endxmlonly\" \\ + cauchy_distribution=\"@xmlonly cauchy_distribution @endxmlonly\" \\ + uniform_01=\"@xmlonlyuniform_01@endxmlonly\" \\ + random_device=\"@xmlonlyrandom_device@endxmlonly\"" HIDE_UNDOC_MEMBERS=NO QUIET=YES WARN_IF_UNDOCUMENTED=NO @@ -125,10 +134,16 @@ doxygen reference : \"b_arg=b\" \\ \"c_arg=c\" \\ \"t_arg=t\" \\ + \"m_arg=m\" \\ + \"n_arg=n\" \\ + \"s_arg=s\" \\ + \"k_arg=k\" \\ \"min_arg=min\" \\ \"max_arg=max\" \\ + \"dim_arg=dim\" \\ \"parm=param\" \\ \"aseed=seed\" \\ + \"seed_arg=seed\" \\ \"BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os,T,t)=template friend std::basic_ostream& operator<<(std::basic_ostream& os, const T& t)\" \\ \"BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is,T,t)=template friend std::basic_istream& operator>>(std::basic_istream& is, const T& t)\" \\ \"BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(T,lhs,rhs)=friend bool operator==(const T& lhs, const T& rhs)\" \\ diff --git a/doc/concepts.qbk b/doc/concepts.qbk index 3930171..d001b0e 100644 --- a/doc/concepts.qbk +++ b/doc/concepts.qbk @@ -31,42 +31,21 @@ random number generators are appropriate: * pseudo-random number generator * quasi-random number generator -All variations have some properties in common, these concepts (in the STL -sense) are called __NumberGenerator and __UniformRandomNumberGenerator. Each -concept will be defined in a subsequent section. +All variations have some properties in common, the concepts (in the STL +sense) is called __UniformRandomNumberGenerator. This +concept will be defined in a subsequent section. The goals for this library are the following: -* allow easy integration of third-party random-number generators -* define a validation interface for the generators +* allow easy integration of third-party random-number generators * provide easy-to-use front-end classes which model popular distributions * provide maximum efficiency -* allow control on quantization effects in front-end processing (not yet done) - -[endsect] - -[section Number Generator] - -A number generator is a /function object/ (std:20.3 [lib.function.objects]) that -takes zero arguments. Each call to `operator()` returns a number. In the -following table, X denotes a number generator class returning objects of type -T, and u is a value of X. - -[table NumberGenerator requirements - [[expression] [return type] [pre/post-condition]] - [[`X::result_type`] [`T`] [`std::numeric_limits::is_specialized` is - `true`, `T` is __LessThanComparable]] - [[`u.operator()()`] [`T`] [-]] -] - -[note The NumberGenerator requirements do not impose any restrictions on the -characteristics of the returned numbers.] [endsect] [section Uniform Random Number Generator] -A uniform random number generator is a __NumberGenerator that provides a +A uniform random number generator provides a sequence of random numbers uniformly distributed on a given range. The range can be compile-time fixed or available (only) after run-time construction of the object. @@ -81,18 +60,9 @@ of type T, and v is a const value of X. [table UniformRandomNumberGenerator requirements [[expression] [return type] [pre/post-condition]] - [[`X::has_fixed_range`] [`bool`] [compile-time constant; if `true`, the range - on which the random numbers are uniformly - distributed is known at compile-time and - members `min_value` and `max_value` exist. - Note: This flag may also be `false` due to - compiler limitations]] - [[`X::min_value`] [`T`] [compile-time constant; `min_value` is only defined if - `has_fixed_range` is `true`. If it exists, it is - equal to `v.min()`.]] - [[`X::max_value`] [`T`] [compile-time constant; `max_value` is only defined if - `has_fixed_range` is `true`. If it exists, it is - equal to `v.max()`]] + [[`X::result_type`] [`T`] [`std::numeric_limits::is_specialized` is + `true`, `T` is __LessThanComparable]] + [[`u.operator()()`] [`T`] [-]] [[`v.min()`] [`T`] [tight lower bound on the set of all values returned by `operator()`. The return value of this function shall not change during the lifetime of the object.]] @@ -160,7 +130,7 @@ A pseudo-random number generator is a __UniformRandomNumberGenerator which provides a deterministic sequence of pseudo-random numbers, based on some algorithm and internal state. [classref boost::random::linear_congruential_engine -Linear congruential] and [classref boost::random::inversive_congruential +Linear congruential] and [classref boost::random::inversive_congruential_engine inversive congruential] generators are examples of such [prng pseudo-random number generators]. Often, these generators are very sensitive to their parameters. In order to prevent wrong implementations from being used, an @@ -187,20 +157,13 @@ a const value of `X`. [[`X()`] [-] [creates a generator in some implementation-defined state. Note: Several generators thusly created may possibly produce dependent or identical sequences of random numbers.]] - [[`explicit X(...)`] [-] [creates a generator with user-provided state; the + [[`X(...)`] [-] [creates a generator with user-provided state; the implementation shall specify the constructor argument(s)]] [[`u.seed(...)`] [`void`] [sets the current state according to the argument(s); at least functions with the same signature as the non-default constructor(s) shall be provided.]] - [[`X::validation(x)`] [`bool`] [compares the pre-computed and hardcoded - 10001th element in the generator's random - number sequence with x. The generator must - have been constructed by its default - constructor and seed must not have been - called for the validation to be - meaningful.]] ] [note The seed member function is similar to the assign member function in @@ -220,7 +183,7 @@ assumed that the `locales` used for writing and reading be the same. The pseudo-random number generator with the restored state and the original at the just-written state shall be equivalent. -Classes which model a pseudo-random number generator may also model the +Classes which model a pseudo-random number generator should also model the __CopyConstructible and __Assignable concepts. However, note that the sequences of the original and the copy are strongly correlated (in fact, they are identical), which may make them unsuitable for some problem domains. @@ -248,16 +211,16 @@ type `T`, `u` is a value of `X`, `x` is a (possibly const) value of `X`, and `e` is an lvalue of an arbitrary type that meets the requirements of a __UniformRandomNumberGenerator, returning values of type `U`. -[table Random distribution requirements (in addition to NumberGenerator, CopyConstructible, and Assignable) +[table Random distribution requirements (in addition to CopyConstructible, and Assignable) [[expression] [return type] [pre/post-condition] [complexity]] - [[`X::input_type`] [`U`] [-] [compile-time]] + [[`X::result_type`] [`T`] [-] [compile-time]] [[`u.reset()`] [`void`] [subsequent uses of `u` do not depend on values - produced by `e` prior to invoking `reset`.] + produced by any engine prior to invoking `reset`.] [constant]] [[`u(e)`] [`T`] [the sequence of numbers returned by successive invocations with the same object `e` is randomly distributed with some probability density function `p(x)`] - [amortized constant number of invocations of `e`]] + [amortized constant number of invocations of `e`]] [[`os << x`] [`std::ostream&`] [writes a textual representation for the parameters and additional internal data of the distribution `x` to `os`. diff --git a/doc/distributions.qbk b/doc/distributions.qbk index d81a7ea..e658936 100644 --- a/doc/distributions.qbk +++ b/doc/distributions.qbk @@ -18,24 +18,28 @@ specific implementation. However, implementations which cannot reach certain values of the specified distribution or otherwise do not converge statistically to it are not acceptable. -[table distributions +[table Uniform Distributions [[distribution] [explanation] [example]] [[__uniform_smallint] [discrete uniform distribution on a small set of integers (much smaller than the range of the underlying generator)] [drawing from an urn]] - [[__uniform_int] [discrete uniform distribution on a set of integers; the + [[__uniform_int_distribution] [discrete uniform distribution on a set of integers; the underlying generator may be called several times to gather enough randomness for the output] [drawing from an urn]] [[__uniform_01] [continuous uniform distribution on the range [0,1); important basis for other distributions] [-]] - [[__uniform_real] [continuous uniform distribution on some range [min, max) of + [[__uniform_real_distribution] [continuous uniform distribution on some range [min, max) of real numbers] [for the range [0, 2pi): randomly dropping a stick and measuring its angle in radians (assuming the angle is uniformly distributed)]] +] + +[table Bernoulli Distributions + [[distribution] [explanation] [example]] [[__bernoulli_distribution] [Bernoulli experiment: discrete boolean valued distribution with configurable probability] [tossing a coin (p=0.5)]] @@ -43,21 +47,33 @@ statistically to it are not acceptable. experiments] [tossing a coin 20 times and counting how many front sides are shown]] - [[__cauchy_distribution][cauchy distribution][-]] - [[__discrete_distribution][discrete distribution with specific probabilities][rolling an unfair die]] - [[__gamma_distribution][gamma distribution][-]] - [[__poisson_distribution][poisson distribution] - [counting the number of alpha particles emitted - by radioactive matter in a fixed period of time]] [[__geometric_distribution] [measures distance between outcomes of repeated Bernoulli experiments] [throwing a die several times and counting the number of tries until a "6" appears for the first time]] - [[__triangle_distribution] [triangle distribution] [-]] + [[__negative_binomial_distribution] [Counts the number of failures of repeated + Bernoulli experiments required to get some constant + number of successes.] + [flipping a coin and counting the number of + heads that show up before we get 3 tails]] +] + +[table Poisson Distributions + [[distribution] [explanation] [example]] + [[__poisson_distribution][poisson distribution] + [counting the number of alpha particles emitted + by radioactive matter in a fixed period of time]] [[__exponential_distribution] [exponential distribution] [measuring the inter-arrival time of alpha particles emitted by radioactive matter]] + [[__gamma_distribution][gamma distribution][-]] + [[__weibull_distribution] [weibull distribution] [-]] + [[__extreme_value_distribution] [extreme value distribution] [-]] +] + +[table Normal Distributions + [[distribution] [explanation] [example]] [[__normal_distribution] [counts outcomes of (infinitely) repeated Bernoulli experiments] [tossing a coin 10000 times and counting how many @@ -66,8 +82,23 @@ statistically to it are not acceptable. simulations)] [measuring the job completion time of an assembly line worker]] - [[__weibull_distribution] [weibull distribution] [-]] - [[__extreme_value_distribution] [extreme value distribution] [-]] + [[__chi_squared_distribution][chi-squared distribution][-]] + [[__cauchy_distribution][Cauchy distribution][-]] + [[__fisher_f_distribution][Fisher F distribution][-]] + [[__student_t_distribution][Student t distribution][-]] +] + +[table Sampling Distributions + [[distribution] [explanation] [example]] + [[__discrete_distribution][discrete distribution with specific probabilities][rolling an unfair die]] + [[__piecewise_constant_distribution][-][-]] + [[__piecewise_linear_distribution][-][-]] +] + + +[table Miscellaneous Distributions + [[distribution] [explanation] [example]] + [[__triangle_distribution] [triangle distribution] [-]] [[__uniform_on_sphere] [uniform distribution on a unit sphere of arbitrary dimension] [choosing a random point on Earth (assumed to be a diff --git a/doc/random.qbk b/doc/random.qbk index a99a189..baede60 100644 --- a/doc/random.qbk +++ b/doc/random.qbk @@ -26,30 +26,30 @@ [def __EqualityComparable [@boost:/doc/html/EqualityComparable.html EqualityComparable]] [def __Streamable Streamable] -[def __random_device [classref boost::random_device random_device]] +[def __random_device [classref boost::random::random_device random_device]] [def __random_number_generator [classref boost::random_number_generator random_number_generator]] [def __variate_generator [classref boost::variate_generator variate_generator]] [def __minstd_rand0 [classref boost::random::minstd_rand0 minstd_rand0]] [def __minstd_rand [classref boost::random::minstd_rand minstd_rand]] [def __rand48 [classref boost::random::rand48 rand48]] -[def __ecuyer1988 [classref boost::ecuyer1988 ecuyer1988]] +[def __ecuyer1988 [classref boost::random::ecuyer1988 ecuyer1988]] [def __kreutzer1986 [classref boost::random::kreutzer1986 kreutzer1986]] [def __knuth_b [classref boost::random::knuth_b knuth_b]] -[def __taus88 [classref boost::taus88 taus88]] -[def __hellekalek1995 [classref boost::hellekalek1995 hellekalek1995]] +[def __taus88 [classref boost::random::taus88 taus88]] +[def __hellekalek1995 [classref boost::random::hellekalek1995 hellekalek1995]] [def __mt11213b [classref boost::random::mt11213b mt11213b]] [def __mt19937 [classref boost::random::mt19937 mt19937]] [def __mt19937_64 [classref boost::random::mt19937_64 mt19937_64]] -[def __lagged_fibonacci607 [classref boost::lagged_fibonacci607 lagged_fibonacci607]] -[def __lagged_fibonacci1279 [classref boost::lagged_fibonacci1279 lagged_fibonacci1279]] -[def __lagged_fibonacci2281 [classref boost::lagged_fibonacci2281 lagged_fibonacci2281]] -[def __lagged_fibonacci3217 [classref boost::lagged_fibonacci3217 lagged_fibonacci3217]] -[def __lagged_fibonacci4423 [classref boost::lagged_fibonacci4423 lagged_fibonacci4423]] -[def __lagged_fibonacci9689 [classref boost::lagged_fibonacci9689 lagged_fibonacci9689]] -[def __lagged_fibonacci19937 [classref boost::lagged_fibonacci19937 lagged_fibonacci19937]] -[def __lagged_fibonacci23209 [classref boost::lagged_fibonacci23209 lagged_fibonacci23209]] -[def __lagged_fibonacci44497 [classref boost::lagged_fibonacci44497 lagged_fibonacci44497]] +[def __lagged_fibonacci607 [classref boost::random::lagged_fibonacci607 lagged_fibonacci607]] +[def __lagged_fibonacci1279 [classref boost::random::lagged_fibonacci1279 lagged_fibonacci1279]] +[def __lagged_fibonacci2281 [classref boost::random::lagged_fibonacci2281 lagged_fibonacci2281]] +[def __lagged_fibonacci3217 [classref boost::random::lagged_fibonacci3217 lagged_fibonacci3217]] +[def __lagged_fibonacci4423 [classref boost::random::lagged_fibonacci4423 lagged_fibonacci4423]] +[def __lagged_fibonacci9689 [classref boost::random::lagged_fibonacci9689 lagged_fibonacci9689]] +[def __lagged_fibonacci19937 [classref boost::random::lagged_fibonacci19937 lagged_fibonacci19937]] +[def __lagged_fibonacci23209 [classref boost::random::lagged_fibonacci23209 lagged_fibonacci23209]] +[def __lagged_fibonacci44497 [classref boost::random::lagged_fibonacci44497 lagged_fibonacci44497]] [def __ranlux3 [classref boost::random::ranlux3 ranlux3]] [def __ranlux4 [classref boost::random::ranlux4 ranlux4]] [def __ranlux64_3 [classref boost::random::ranlux64_3 ranlux64_3]] @@ -61,24 +61,30 @@ [def __ranlux24 [classref boost::random::ranlux24 ranlux24]] [def __ranlux48 [classref boost::random::ranlux48 ranlux48]] -[def __uniform_smallint [classref boost::uniform_smallint uniform_smallint]] -[def __uniform_int [classref boost::uniform_int uniform_int]] -[def __uniform_01 [classref boost::uniform_01 uniform_01]] -[def __uniform_real [classref boost::uniform_real uniform_real]] -[def __bernoulli_distribution [classref boost::bernoulli_distribution bernoulli_distribution]] +[def __uniform_smallint [classref boost::random::uniform_smallint uniform_smallint]] +[def __uniform_int_distribution [classref boost::random::uniform_int_distribution uniform_int_distribution]] +[def __uniform_01 [classref boost::random::uniform_01 uniform_01]] +[def __uniform_real_distribution [classref boost::random::uniform_real_distribution uniform_real_distribution]] +[def __bernoulli_distribution [classref boost::random::bernoulli_distribution bernoulli_distribution]] [def __binomial_distribution [classref boost::random::binomial_distribution binomial_distribution]] -[def __cauchy_distribution [classref boost::cauchy_distribution cauchy_distribution]] +[def __cauchy_distribution [classref boost::random::cauchy_distribution cauchy_distribution]] [def __discrete_distribution [classref boost::random::discrete_distribution discrete_distribution]] [def __gamma_distribution [classref boost::random::gamma_distribution gamma_distribution]] [def __poisson_distribution [classref boost::random::poisson_distribution poisson_distribution]] -[def __geometric_distribution [classref boost::geometric_distribution geometric_distribution]] -[def __triangle_distribution [classref boost::triangle_distribution triangle_distribution]] -[def __exponential_distribution [classref boost::exponential_distribution exponential_distribution]] -[def __normal_distribution [classref boost::normal_distribution normal_distribution]] -[def __lognormal_distribution [classref boost::lognormal_distribution lognormal_distribution]] -[def __uniform_on_sphere [classref boost::uniform_on_sphere uniform_on_sphere]] +[def __geometric_distribution [classref boost::random::geometric_distribution geometric_distribution]] +[def __triangle_distribution [classref boost::random::triangle_distribution triangle_distribution]] +[def __exponential_distribution [classref boost::random::exponential_distribution exponential_distribution]] +[def __normal_distribution [classref boost::random::normal_distribution normal_distribution]] +[def __lognormal_distribution [classref boost::random::lognormal_distribution lognormal_distribution]] +[def __uniform_on_sphere [classref boost::random::uniform_on_sphere uniform_on_sphere]] [def __weibull_distribution [classref boost::random::weibull_distribution weibull_distribution]] [def __extreme_value_distribution [classref boost::random::extreme_value_distribution extreme_value_distribution]] +[def __negative_binomial_distribution [classref boost::random::negative_binomial_distribution negative_binomial_distribution]] +[def __student_t_distribution [classref boost::random::student_t_distribution student_t_distribution]] +[def __fisher_f_distribution [classref boost::random::fisher_f_distribution fisher_f_distribution]] +[def __chi_squared_distribution [classref boost::random::chi_squared_distribution chi_squared_distribution]] +[def __piecewise_constant_distribution [classref boost::random::piecewise_constant_distribution piecewise_constant_distribution]] +[def __piecewise_linear_distribution [classref boost::random::piecewise_linear_distribution piecewise_linear_distribution]] [include performance_data.qbk] @@ -97,11 +103,10 @@ For a very quick start, here's an example: ``[classref boost::random::mt19937]`` rng; // produces randomness out of thin air // see pseudo-random number generators - ``[classref boost::uniform_int]<>`` six(1,6); // distribution that maps to 1..6 + ``[classref boost::random::uniform_int_distribution]<>`` six(1,6); + // distribution that maps to 1..6 // see random number distributions - ``[classref boost::variate_generator]``<``[classref boost::random::mt19937]``&, ``[classref boost::uniform_int]``<> > - die(rng, six); // glues randomness with mapping - int x = die(); // simulate rolling a die + int x = six(rng); // simulate rolling a die [endsect] @@ -131,17 +136,6 @@ For a very quick start, here's an example: [include performance.qbk] [endsect] -[section Rationale] - -The methods for generating and evaluating deterministic and non-deterministic -random numbers differ radically. Furthermore, due to the inherent -deterministic design of present-day computers, it is often difficult to -implement non-deterministic random number generation facilities. Thus, the -random number library is split into separate header files, mirroring the two -different application domains. - -[endsect] - [section History and Acknowledgements] In November 1999, Jeet Sukumaran proposed a framework based on virtual diff --git a/example/die.cpp b/example/die.cpp index 1321890..8ed0b8f 100644 --- a/example/die.cpp +++ b/example/die.cpp @@ -12,11 +12,10 @@ For the source of this example see [@boost://libs/random/example/die.cpp die.cpp]. First we include the headers we need for __mt19937 - and __uniform_int. + and __uniform_int_distribution. */ #include -#include -#include +#include /*` We use __mt19937 with the default seed as a source of @@ -38,24 +37,17 @@ boost::random::mt19937 gen; int roll_die() { /*<< __mt19937 produces integers in the range [0, 2[sup 32]-1]. However, we want numbers in the range [1, 6]. The distribution - __uniform_int performs this transformation. - [warning Contrary to common C++ usage __uniform_int + __uniform_int_distribution performs this transformation. + [warning Contrary to common C++ usage __uniform_int_distribution does not take a /half-open range/. Instead it takes a /closed range/. - Given the parameters 1 and 6, __uniform_int can + Given the parameters 1 and 6, __uniform_int_distribution can can produce any of the values 1, 2, 3, 4, 5, or 6.] >>*/ - boost::uniform_int<> dist(1, 6); - /*<< __variate_generator combines a generator with a distribution. - [important We pass [classref boost::random::mt19937 boost::mt19937&] to - __variate_generator instead of just [classref boost::random::mt19937] - (note the reference). Without the reference, __variate_generator - would make a copy of the generator and would leave the global - `gen` unchanged. Consequently, `roll_die` would produce *the same value* - every time it was called.] + boost::random::uniform_int_distribution<> dist(1, 6); + /*<< A distribution is a function object. We generate a random + number by calling `dist` with the generator. >>*/ - boost::variate_generator > die(gen, dist); - /*<< A __variate_generator is a function object. >>*/ - return die(); + return dist(gen); } //] diff --git a/example/password.cpp b/example/password.cpp index 6bc15f2..19ab308 100644 --- a/example/password.cpp +++ b/example/password.cpp @@ -17,9 +17,8 @@ */ -#include -#include -#include +#include +#include int main() { /*<< We first define the characters that we're going @@ -35,14 +34,13 @@ int main() { /*<< We use __random_device as a source of entropy, since we want passwords that are not predictable. >>*/ - boost::random_device rng; + boost::random::random_device rng; /*<< Finally we select 8 random characters from the string and print them to cout. >>*/ - boost::variate_generator > - gen(rng, boost::uniform_int<>(0, chars.size())); + boost::random::uniform_int_distribution<> index_dist(0, chars.size() - 1); for(int i = 0; i < 8; ++i) { - std::cout << chars[gen()]; + std::cout << chars[index_dist(rng)]; } std::cout << std::endl; } diff --git a/example/weighted_die.cpp b/example/weighted_die.cpp index 368e29c..8dd9c2a 100644 --- a/example/weighted_die.cpp +++ b/example/weighted_die.cpp @@ -13,12 +13,7 @@ [@boost://libs/random/example/weighted_die.cpp weighted_die.cpp]. */ #include -#include -#include -#include -#include -#include -#include +#include boost::mt19937 gen; @@ -26,27 +21,27 @@ boost::mt19937 gen; This time, instead of a fair die, the probability of rolling a 1 is 50% (!). The other five faces are all equally likely. + + __discrete_distribution works nicely here by allowing + us to assign weights to each of the possible outcomes. + + [tip If your compiler supports `std::initializer_list`, + you can initialize __discrete_distribution directly with + the weights.] */ -static const double probabilities[] = { +double probabilities[] = { 0.5, 0.1, 0.1, 0.1, 0.1, 0.1 }; +boost::random::discrete_distribution<> dist(probabilities); /*` Now define a function that simulates rolling this die. - Note that the C++0x library contains a `discrete_distribution` - class which would be a better way to do this. */ int roll_weighted_die() { - std::vector cumulative; - std::partial_sum(&probabilities[0], &probabilities[0] + 6, - std::back_inserter(cumulative)); - boost::uniform_real<> dist(0, cumulative.back()); - boost::variate_generator > die(gen, dist); - /*<< Find the position within the sequence and add 1 - (to make sure that the result is in the range [1,6] - instead of [0,5]) + /*<< Add 1 to make sure that the result is in the range [1,6] + instead of [0,5]. >>*/ - return (std::lower_bound(cumulative.begin(), cumulative.end(), die()) - cumulative.begin()) + 1; + return dist(gen) + 1; } //] diff --git a/include/boost/random/additive_combine.hpp b/include/boost/random/additive_combine.hpp index 5fc2011..2d492cc 100644 --- a/include/boost/random/additive_combine.hpp +++ b/include/boost/random/additive_combine.hpp @@ -247,7 +247,8 @@ template const bool additive_combine_engine::has_fixed_range; #endif -/// \cond +/// \cond show_deprecated + /** Provided for backwards compatibility. */ template class additive_combine : public additive_combine_engine @@ -263,6 +264,7 @@ public: template additive_combine(It& first, It last) : base_t(first, last) {} }; + /// \endcond /** diff --git a/include/boost/random/bernoulli_distribution.hpp b/include/boost/random/bernoulli_distribution.hpp index 0c451e3..d66bae4 100644 --- a/include/boost/random/bernoulli_distribution.hpp +++ b/include/boost/random/bernoulli_distribution.hpp @@ -185,10 +185,7 @@ public: BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(bernoulli_distribution) private: - - /// \cond RealType _p; - /// \endcond }; } // namespace random diff --git a/include/boost/random/binomial_distribution.hpp b/include/boost/random/binomial_distribution.hpp index 3c50834..2d4874d 100644 --- a/include/boost/random/binomial_distribution.hpp +++ b/include/boost/random/binomial_distribution.hpp @@ -236,7 +236,7 @@ public: private: - /// @cond + /// @cond show_private template void read(std::basic_istream& is) { diff --git a/include/boost/random/cauchy_distribution.hpp b/include/boost/random/cauchy_distribution.hpp index 8e7dbc2..998e523 100644 --- a/include/boost/random/cauchy_distribution.hpp +++ b/include/boost/random/cauchy_distribution.hpp @@ -201,11 +201,8 @@ public: BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(cauchy_distribution) private: - - /// \cond RealType _median; RealType _sigma; - /// \endcond }; } // namespace random diff --git a/include/boost/random/chi_squared_distribution.hpp b/include/boost/random/chi_squared_distribution.hpp index 631d838..ce63584 100644 --- a/include/boost/random/chi_squared_distribution.hpp +++ b/include/boost/random/chi_squared_distribution.hpp @@ -187,7 +187,7 @@ public: private: - /// @cond + /// @cond show_private template void read(std::basic_istream& is) { diff --git a/include/boost/random/discard_block.hpp b/include/boost/random/discard_block.hpp index 6b7d87c..8474a99 100644 --- a/include/boost/random/discard_block.hpp +++ b/include/boost/random/discard_block.hpp @@ -202,6 +202,8 @@ template const std::size_t discard_block_engine::used_block; #endif +/// \cond \show_deprecated + template class discard_block : public discard_block_engine { @@ -221,6 +223,8 @@ public: { return (this->base().max)(); } }; +/// \endcond + } // namespace random } // namespace boost diff --git a/include/boost/random/discrete_distribution.hpp b/include/boost/random/discrete_distribution.hpp index 573d970..ec58624 100644 --- a/include/boost/random/discrete_distribution.hpp +++ b/include/boost/random/discrete_distribution.hpp @@ -146,7 +146,7 @@ public: /** Returns true if the two sets of parameters are different. */ BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(param_type) private: - /// @cond + /// @cond show_private friend class discrete_distribution; explicit param_type(const discrete_distribution& dist) : _probabilities(dist.probabilities()) @@ -374,7 +374,7 @@ public: private: - /// @cond + /// @cond show_private template void init(Iter first, Iter last, std::input_iterator_tag) diff --git a/include/boost/random/exponential_distribution.hpp b/include/boost/random/exponential_distribution.hpp index 5456fe8..53eaa93 100644 --- a/include/boost/random/exponential_distribution.hpp +++ b/include/boost/random/exponential_distribution.hpp @@ -170,9 +170,7 @@ public: BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(exponential_distribution) private: - /// \cond result_type _lambda; - /// \endcond }; } // namespace random diff --git a/include/boost/random/geometric_distribution.hpp b/include/boost/random/geometric_distribution.hpp index f4ed10d..6342ac7 100644 --- a/include/boost/random/geometric_distribution.hpp +++ b/include/boost/random/geometric_distribution.hpp @@ -199,7 +199,7 @@ public: private: - /// \cond + /// \cond show_private void init() { @@ -215,6 +215,8 @@ private: } // namespace random +/// \cond show_deprecated + /** * Provided for backwards compatibility. This class is * deprecated. It provides the old behavior of geometric_distribution @@ -258,6 +260,8 @@ private: impl_type _impl; }; +/// \endcond + } // namespace boost #endif // BOOST_RANDOM_GEOMETRIC_DISTRIBUTION_HPP diff --git a/include/boost/random/independent_bits.hpp b/include/boost/random/independent_bits.hpp index 666d529..38ebefd 100644 --- a/include/boost/random/independent_bits.hpp +++ b/include/boost/random/independent_bits.hpp @@ -84,14 +84,10 @@ public: // Required by old Boost.Random concept BOOST_STATIC_CONSTANT(bool, has_fixed_range = false); - /** - * Returns the smallest value that the generator can produce - */ + /** Returns the smallest value that the generator can produce. */ static result_type min BOOST_PREVENT_MACRO_SUBSTITUTION () { return 0; } - /** - * Returns the largest value that the generator can produce - */ + /** Returns the largest value that the generator can produce. */ static result_type max BOOST_PREVENT_MACRO_SUBSTITUTION () { return boost::low_bits_mask_t::sig_bits; } @@ -265,7 +261,7 @@ public: private: - /// \cond + /// \cond show_private typedef typename base_type::result_type base_result; typedef typename make_unsigned::type base_unsigned; diff --git a/include/boost/random/inversive_congruential.hpp b/include/boost/random/inversive_congruential.hpp index 6bacfb3..b64a931 100644 --- a/include/boost/random/inversive_congruential.hpp +++ b/include/boost/random/inversive_congruential.hpp @@ -235,7 +235,7 @@ template const typename inversive_congruential_engine::result_type inversive_congruential_engine::default_seed; #endif -/// \cond +/// \cond show_deprecated // provided for backwards compatibility template diff --git a/include/boost/random/lagged_fibonacci.hpp b/include/boost/random/lagged_fibonacci.hpp index 9135672..dc6980f 100644 --- a/include/boost/random/lagged_fibonacci.hpp +++ b/include/boost/random/lagged_fibonacci.hpp @@ -35,7 +35,7 @@ namespace boost { namespace random { /** - * Instantiations of class template \lagged_fibonacci model a + * Instantiations of class template \lagged_fibonacci_engine model a * \pseudo_random_number_generator. It uses a lagged Fibonacci * algorithm with two lags @c p and @c q: * x(i) = x(i-p) + x(i-q) (mod 2w) with p > q. @@ -184,7 +184,7 @@ public: BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(lagged_fibonacci_engine) private: - /// \cond hide_private_members + /// \cond show_private void fill(); /// \endcond @@ -202,7 +202,7 @@ template const unsigned int lagged_fibonacci_engine::short_lag; #endif -/// \cond +/// \cond show_private template void lagged_fibonacci_engine::fill() @@ -219,7 +219,7 @@ void lagged_fibonacci_engine::fill() /// \endcond -/// \cond +/// \cond show_deprecated // provided for backwards compatibility template @@ -432,7 +432,7 @@ public: BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(lagged_fibonacci_01_engine) private: - /// \cond + /// \cond show_private void fill(); static RealType modulus() { @@ -457,7 +457,7 @@ const int lagged_fibonacci_01_engine::word_size; #endif -/// \cond +/// \cond show_private template void lagged_fibonacci_01_engine::fill() { @@ -480,7 +480,7 @@ void lagged_fibonacci_01_engine::fill() } /// \endcond -/// \cond +/// \cond show_deprecated // provided for backwards compatibility template diff --git a/include/boost/random/linear_congruential.hpp b/include/boost/random/linear_congruential.hpp index 13bae2a..91f6be7 100644 --- a/include/boost/random/linear_congruential.hpp +++ b/include/boost/random/linear_congruential.hpp @@ -234,7 +234,7 @@ public: private: - /// \cond + /// \cond show_private template void read(std::basic_istream& is) { @@ -267,7 +267,7 @@ template const IntType linear_congruential_engine::default_seed; #endif -/// \cond +/// \cond show_deprecated // provided for backwards compatibility template @@ -421,7 +421,7 @@ public: friend bool operator!=(const rand48& x, const rand48& y) { return !(x == y); } private: - /// \cond + /// \cond show_private typedef random::linear_congruential_engine::sig_bits; } /// \endcond UIntType value; @@ -192,7 +192,7 @@ template const UIntType linear_feedback_shift_engine::default_seed; #endif -/// \cond +/// \cond show_deprecated /** Provided for backwards compatibility. */ template diff --git a/include/boost/random/lognormal_distribution.hpp b/include/boost/random/lognormal_distribution.hpp index afbf51e..7ed1e13 100644 --- a/include/boost/random/lognormal_distribution.hpp +++ b/include/boost/random/lognormal_distribution.hpp @@ -188,12 +188,14 @@ private: } // namespace random +/// \cond show_deprecated + /** * Provided for backwards compatibility. This class is * deprecated. It provides the old behavior of lognormal_distribution with * \f$\displaystyle p(x) = \frac{1}{x \sigma_N \sqrt{2\pi}} e^{\frac{-\left(\log(x)-\mu_N\right)^2}{2\sigma_N^2}}\f$ * for x > 0, where \f$\displaystyle \mu_N = \log\left(\frac{\mu^2}{\sqrt{\sigma^2 + \mu^2}}\right)\f$ and - * \f$\displaystyle \sigma_N = \sqrt{\log\left(1 + \frac{\sigma^2}{\mu^2}\right)}. + * \f$\displaystyle \sigma_N = \sqrt{\log\left(1 + \frac{\sigma^2}{\mu^2}\right)}\f$. */ template class lognormal_distribution @@ -229,7 +231,7 @@ public: return is; } private: - /// \cond + /// \cond show_private void init() { using std::log; @@ -245,6 +247,8 @@ private: /// \endcond }; +/// \endcond + } // namespace boost #endif // BOOST_RANDOM_LOGNORMAL_DISTRIBUTION_HPP diff --git a/include/boost/random/mersenne_twister.hpp b/include/boost/random/mersenne_twister.hpp index ccbf939..c41a07c 100644 --- a/include/boost/random/mersenne_twister.hpp +++ b/include/boost/random/mersenne_twister.hpp @@ -262,7 +262,7 @@ public: { return !(x == y); } private: - /// \cond hide_private_members + /// \cond show_private void twist(); @@ -361,7 +361,7 @@ private: std::size_t i; }; -/// \cond +/// \cond show_private #ifndef BOOST_NO_INCLASS_MEMBER_INITIALIZATION // A definition is required even for integral static constants @@ -498,8 +498,7 @@ typedef mersenne_twister_engine mt19937_64; #endif - -/// \cond +/// \cond show_deprecated template void read(std::basic_istream& is) { diff --git a/include/boost/random/normal_distribution.hpp b/include/boost/random/normal_distribution.hpp index 53e14cc..4d0c07e 100644 --- a/include/boost/random/normal_distribution.hpp +++ b/include/boost/random/normal_distribution.hpp @@ -208,15 +208,10 @@ public: BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(normal_distribution) private: - - /// @cond - RealType _mean, _sigma; RealType _r1, _r2, _cached_rho; bool _valid; - /// @endcond - }; } // namespace random diff --git a/include/boost/random/piecewise_constant_distribution.hpp b/include/boost/random/piecewise_constant_distribution.hpp index a0e46f9..3582483 100644 --- a/include/boost/random/piecewise_constant_distribution.hpp +++ b/include/boost/random/piecewise_constant_distribution.hpp @@ -211,19 +211,15 @@ public: private: - /// @cond - friend class piecewise_constant_distribution; std::vector _intervals; std::vector _weights; - - /// @endcond }; /** * Creates a new @c piecewise_constant_distribution with - * a single interval, [0, 1)$. + * a single interval, [0, 1). */ piecewise_constant_distribution() { @@ -460,13 +456,8 @@ public: BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(piecewise_constant_distribution) private: - - /// @cond - discrete_distribution _bins; std::vector _intervals; - - /// @endcond }; } diff --git a/include/boost/random/piecewise_linear_distribution.hpp b/include/boost/random/piecewise_linear_distribution.hpp index a6e4fdc..a8b04ca 100644 --- a/include/boost/random/piecewise_linear_distribution.hpp +++ b/include/boost/random/piecewise_linear_distribution.hpp @@ -225,15 +225,10 @@ public: BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(param_type) private: - - /// @cond - friend class piecewise_linear_distribution; std::vector _intervals; std::vector _weights; - - /// @endcond }; /** @@ -487,7 +482,7 @@ public: private: - /// @cond + /// @cond \show_private void init(const std::vector& intervals_arg, const std::vector& weights_arg) diff --git a/include/boost/random/poisson_distribution.hpp b/include/boost/random/poisson_distribution.hpp index db36c16..f0c58c2 100644 --- a/include/boost/random/poisson_distribution.hpp +++ b/include/boost/random/poisson_distribution.hpp @@ -225,7 +225,7 @@ public: private: - /// @cond + /// @cond show_private template void read(std::basic_istream& is) { diff --git a/include/boost/random/random_device.hpp b/include/boost/random/random_device.hpp index fc9f425..377aa07 100644 --- a/include/boost/random/random_device.hpp +++ b/include/boost/random/random_device.hpp @@ -77,7 +77,7 @@ namespace random { * * * - * + * *
classtime per invocation [usec]
@xmlonly random_device @endxmlonly 92.0
\random_device 92.0
* * The measurement error is estimated at +/- 1 usec. diff --git a/include/boost/random/seed_seq.hpp b/include/boost/random/seed_seq.hpp index cadfb93..a541a53 100644 --- a/include/boost/random/seed_seq.hpp +++ b/include/boost/random/seed_seq.hpp @@ -30,21 +30,37 @@ namespace boost { namespace random { +/** + * The class @c seed_seq stores a sequence of 32-bit words + * for seeding a \pseudo_random_number_generator. These + * words will be combined to fill the entire state of the + * generator. + */ class seed_seq { public: typedef boost::uint_least32_t result_type; + /** Initializes a seed_seq to hold an empty sequence. */ seed_seq() {} #ifndef BOOST_NO_INITIALIZER_LISTS + /** Initializes the sequence from an initializer_list. */ template seed_seq(const std::initializer_list& il) : v(il.begin(), il.end()) {} #endif + /** Initializes the sequence from an iterator range. */ template seed_seq(Iter first, Iter last) : v(first, last) {} + /** Initializes the sequence from Boost.Range range. */ template explicit seed_seq(const Range& range) : v(boost::begin(range), boost::end(range)) {} + /** + * Fills a range with 32-bit values based on the stored sequence. + * + * Requires: Iter must be a Random Access Iterator whose value type + * is an unsigned integral type at least 32 bits wide. + */ template void generate(Iter first, Iter last) const { @@ -87,7 +103,9 @@ public: *(first + k%n) = r4; } } + /** Returns the size of the sequence. */ std::size_t size() const { return v.size(); } + /** Writes the stored sequence to iter. */ template void param(Iter out) { std::copy(v.begin(), v.end(), out); } private: diff --git a/include/boost/random/shuffle_order.hpp b/include/boost/random/shuffle_order.hpp index bbe4ead..a18ea9d 100644 --- a/include/boost/random/shuffle_order.hpp +++ b/include/boost/random/shuffle_order.hpp @@ -233,7 +233,7 @@ public: private: - /// \cond + /// \cond show_private void init() { @@ -260,7 +260,6 @@ template const std::size_t shuffle_order_engine::buffer_size; #endif -// validation by experiment from Harry Erwin's generator.h (private e-mail) /** * According to Harry Erwin (private e-mail), the specialization * @c kreutzer1986 was suggested in: @@ -274,6 +273,15 @@ typedef shuffle_order_engine< linear_congruential_engine, 97> kreutzer1986; +/** + * The specialization @c knuth_b is specified by the C++ standard. + * It is described in + * + * @blockquote + * "The Art of Computer Programming, Second Edition, Volume 2, + * Seminumerical Algorithms", Donald Knuth, Addison-Wesley, 1981. + * @endblockquote + */ typedef shuffle_order_engine knuth_b; } // namespace random diff --git a/include/boost/random/student_t_distribution.hpp b/include/boost/random/student_t_distribution.hpp index 4d0469a..e28b0e3 100644 --- a/include/boost/random/student_t_distribution.hpp +++ b/include/boost/random/student_t_distribution.hpp @@ -31,7 +31,7 @@ namespace random { * It has \f$\displaystyle p(x) = * \frac{1}{\sqrt{n\pi}} * \frac{\Gamma((n+1)/2)}{\Gamma(n/2)} - * \left(1}\frac{x^2}{n}\right)^{-(n+1)/2} + * \left(1+\frac{x^2}{n}\right)^{-(n+1)/2} * \f$. */ template diff --git a/include/boost/random/subtract_with_carry.hpp b/include/boost/random/subtract_with_carry.hpp index a5e082e..76a37e8 100644 --- a/include/boost/random/subtract_with_carry.hpp +++ b/include/boost/random/subtract_with_carry.hpp @@ -225,7 +225,7 @@ public: BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(subtract_with_carry_engine) private: - /// \cond + /// \cond show_private // returns x(i-r+index), where index is in 0..r-1 IntType compute(unsigned int index) const { @@ -270,7 +270,17 @@ const uint32_t subtract_with_carry_engine::default_seed; // use a floating-point representation to produce values in [0..1) -/** @copydoc boost::random::subtract_with_carry_engine */ +/** + * Instantiations of \subtract_with_carry_01_engine model a + * \pseudo_random_number_generator. The algorithm is + * described in + * + * @blockquote + * "A New Class of Random Number Generators", George + * Marsaglia and Arif Zaman, Annals of Applied Probability, + * Volume 1, Number 3 (1991), 462-480. + * @endblockquote + */ template class subtract_with_carry_01_engine { @@ -284,21 +294,21 @@ public: BOOST_STATIC_ASSERT(!std::numeric_limits::is_integer); - /** Creates a new subtract_with_carry_01_engine using the default seed. */ + /** Creates a new \subtract_with_carry_01_engine using the default seed. */ subtract_with_carry_01_engine() { init_modulus(); seed(); } /** Creates a new subtract_with_carry_01_engine and seeds it with value. */ BOOST_RANDOM_DETAIL_ARITHMETIC_CONSTRUCTOR(subtract_with_carry_01_engine, uint32_t, value) { init_modulus(); seed(value); } /** - * Creates a new subtract_with_carry_01_engine and seeds with with values + * Creates a new \subtract_with_carry_01_engine and seeds with with values * produced by seq.generate(). */ BOOST_RANDOM_DETAIL_SEED_SEQ_CONSTRUCTOR(subtract_with_carry_01_engine, SeedSeq, seq) { init_modulus(); seed(seq); } /** - * Creates a new subtract_with_carry_01_engine and seeds it with values + * Creates a new \subtract_with_carry_01_engine and seeds it with values * from a range. Advances first to point one past the last consumed * value. If the range does not contain enough elements to fill the * entire state, throws @c std::invalid_argument. @@ -307,7 +317,7 @@ public: { init_modulus(); seed(first,last); } private: - /// \cond + /// \cond show_private void init_modulus() { #ifndef BOOST_NO_STDC_NAMESPACE @@ -433,7 +443,7 @@ public: } } - /** Writes a subtract_with_carry_01_engine to a @c std::ostream. */ + /** Writes a \subtract_with_carry_01_engine to a @c std::ostream. */ BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, subtract_with_carry_01_engine, f) { std::ios_base::fmtflags oldflags = @@ -445,7 +455,7 @@ public: return os; } - /** Reads a subtract_with_carry_01_engine from a @c std::istream. */ + /** Reads a \subtract_with_carry_01_engine from a @c std::istream. */ BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, subtract_with_carry_01_engine, f) { RealType value; @@ -472,7 +482,7 @@ public: BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(subtract_with_carry_01_engine) private: - /// \cond + /// \cond show_private RealType compute(unsigned int index) const { return x[(k+index) % long_lag]; @@ -499,7 +509,7 @@ const uint32_t subtract_with_carry_01_engine::default_seed; #endif -/// \cond +/// \cond show_deprecated template class subtract_with_carry : diff --git a/include/boost/random/triangle_distribution.hpp b/include/boost/random/triangle_distribution.hpp index bc71c26..5ac6604 100644 --- a/include/boost/random/triangle_distribution.hpp +++ b/include/boost/random/triangle_distribution.hpp @@ -207,7 +207,7 @@ public: BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(triangle_distribution) private: - /// \cond + /// \cond show_private void init() { using std::sqrt; diff --git a/include/boost/random/uniform_01.hpp b/include/boost/random/uniform_01.hpp index ec1accc..ec74a3d 100644 --- a/include/boost/random/uniform_01.hpp +++ b/include/boost/random/uniform_01.hpp @@ -26,6 +26,7 @@ #include namespace boost { +namespace random { #ifdef BOOST_RANDOM_DOXYGEN @@ -266,6 +267,10 @@ public: #endif +} // namespace random + +using random::uniform_01; + } // namespace boost #include diff --git a/include/boost/random/uniform_smallint.hpp b/include/boost/random/uniform_smallint.hpp index c4732fd..4f5f437 100644 --- a/include/boost/random/uniform_smallint.hpp +++ b/include/boost/random/uniform_smallint.hpp @@ -63,7 +63,8 @@ namespace random { * * The template parameter IntType shall denote an integer-like value type. * - * Note: The property above is the square sum of the relative differences + * @xmlnote + * The property above is the square sum of the relative differences * in probabilities between the desired uniform distribution * \f$p_{\mathtt{out}}(i)\f$ and the generated distribution * \f$p_{\mathtt{out\_s}}(i)\f$. @@ -85,6 +86,7 @@ namespace random { * {r_{\mathtt{out}}}\right\rfloor/r_{\mathtt{base}}\f$ otherwise. * Substituting this in the * above sum formula leads to the desired result. + * @endxmlnote * * Note: The upper bound for * \f$(r_{\mathtt{base}} \mbox{ mod } r_{\mathtt{out}}) @@ -228,7 +230,7 @@ public: private: - // \cond + // \cond show_private template result_type generate(Engine& eng, boost::mpl::true_) const { diff --git a/include/boost/random/variate_generator.hpp b/include/boost/random/variate_generator.hpp index ac74797..1aea5c1 100644 --- a/include/boost/random/variate_generator.hpp +++ b/include/boost/random/variate_generator.hpp @@ -33,9 +33,6 @@ namespace random { * Boost.Random provides a vast choice of \generators as well * as \distributions. * - * Instantations of class template @c variate_generator model - * a \number_generator. - * * The argument for the template parameter Engine shall be of * the form U, U&, or U*, where U models a * \uniform_random_number_generator. Then, the member diff --git a/include/boost/random/xor_combine.hpp b/include/boost/random/xor_combine.hpp index ca40f66..ee5032e 100644 --- a/include/boost/random/xor_combine.hpp +++ b/include/boost/random/xor_combine.hpp @@ -176,7 +176,7 @@ template const int xor_combine_engine::shift2; #endif -/// \cond +/// \cond show_private /** Provided for backwards compatibility. */ template