procyberian/gcc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

libstdc++: Improve doxygen docs for <random>

Browse source 
Add @headerfile and @since tags. Add gamma_distribution to the correct
group (poisson distributions). Add a group for the sampling
distributions and add the missing definitions of their probability
functions. Add uniform_int_distribution back to the uniform
distributions group.

libstdc++-v3/ChangeLog:

	* include/bits/random.h (gamma_distribution): Add to the right
	doxygen group.
	(discrete_distribution, piecewise_constant_distribution)
	(piecewise_linear_distribution): Create a new doxygen group and
	fix the incomplete doxygen comments.
	* include/bits/uniform_int_dist.h (uniform_int_distribution):
	Add to doxygen group.
This commit is contained in:
Jonathan Wakely 2023-04-28 12:01:58 +01:00
parent 30f6aace7f
commit d711f8f81f
2 changed files with 132 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

127
libstdc++-v3/include/bits/random.h
View file

@ -256,6 +256,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* parameters @p __a and @p __c must be less than @p __m.
*
* The size of the state is @f$1@f$.
*
* @headerfile random
* @since C++11
*/
template<typename _UIntType, _UIntType __a, _UIntType __c, _UIntType __m>
class linear_congruential_engine
@ -471,6 +474,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @tparam __c The second left-shift tempering matrix mask.
* @tparam __l The second right-shift tempering matrix parameter.
* @tparam __f Initialization multiplier.
*
* @headerfile random
* @since C++11
*/
template<typename _UIntType, size_t __w,
size_t __n, size_t __m, size_t __r,
@ -697,6 +703,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*
* The size of the state is @f$r@f$
* and the maximum period of the generator is @f$(m^r - m^s - 1)@f$.
*
* @headerfile random
* @since C++11
*/
template<typename _UIntType, size_t __w, size_t __s, size_t __r>
class subtract_with_carry_engine
@ -890,7 +899,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* Produces random numbers from some base engine by discarding blocks of
* data.
*
* 0 <= @p __r <= @p __p
* @pre @f$ 0 \leq r \leq p @f$
*
* @headerfile random
* @since C++11
*/
template<typename _RandomNumberEngine, size_t __p, size_t __r>
class discard_block_engine
@ -1114,6 +1126,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* Produces random numbers by combining random numbers from some base
* engine to produce random numbers with a specified number of bits @p __w.
*
* @headerfile random
* @since C++11
*/
template<typename _RandomNumberEngine, size_t __w, typename _UIntType>
class independent_bits_engine
@ -1338,6 +1353,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*
* The values from the base engine are stored in a sequence of size @p __k
* and shuffled by an algorithm that depends on those values.
*
* @headerfile random
* @since C++11
*/
template<typename _RandomNumberEngine, size_t __k>
class shuffle_order_engine
@ -1625,6 +1643,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* A standard interface to a platform-specific non-deterministic
* random number generator (if any are available).
*
* @headerfile random
* @since C++11
*/
class random_device
{
@ -1750,6 +1771,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* A continuous random distribution on the range [min, max) with equal
* probability throughout the range. The URNG should be real-valued and
* deliver number in the range [0, 1).
*
* @headerfile random
* @since C++11
*/
template<typename _RealType = double>
class uniform_real_distribution
@ -1984,6 +2008,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* p(x|\mu,\sigma) = \frac{1}{\sigma \sqrt{2 \pi}}
* e^{- \frac{{x - \mu}^ {2}}{2 \sigma ^ {2}} }
* @f]
*
* @headerfile random
* @since C++11
*/
template<typename _RealType = double>
class normal_distribution
@ -2208,6 +2235,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* p(x|m,s) = \frac{1}{sx\sqrt{2\pi}}
* \exp{-\frac{(\ln{x} - m)^2}{2s^2}}
* @f]
*
* @headerfile random
* @since C++11
*/
template<typename _RealType = double>
class lognormal_distribution
@ -2414,6 +2444,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ return !(__d1 == __d2); }
#endif
/// @} group random_distributions_normal
/**
* @addtogroup random_distributions_poisson Poisson Distributions
* @ingroup random_distributions
* @{
*/
/**
* @brief A gamma continuous distribution for random numbers.
*
@ -2422,6 +2460,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* p(x|\alpha,\beta) = \frac{1}{\beta\Gamma(\alpha)}
* (x/\beta)^{\alpha - 1} e^{-x/\beta}
* @f]
*
* @headerfile random
* @since C++11
*/
template<typename _RealType = double>
class gamma_distribution
@ -2645,14 +2686,25 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
inline bool
operator!=(const std::gamma_distribution<_RealType>& __d1,
const std::gamma_distribution<_RealType>& __d2)
{ return !(__d1 == __d2); }
{ return !(__d1 == __d2); }
#endif
/// @} group random_distributions_poisson
/**
* @addtogroup random_distributions_normal Normal Distributions
* @ingroup random_distributions
* @{
*/
/**
* @brief A chi_squared_distribution random number distribution.
*
* The formula for the normal probability mass function is
* @f$p(x|n) = \frac{x^{(n/2) - 1}e^{-x/2}}{\Gamma(n/2) 2^{n/2}}@f$
*
* @headerfile random
* @since C++11
*/
template<typename _RealType = double>
class chi_squared_distribution
@ -2880,6 +2932,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*
* The formula for the normal probability mass function is
* @f$p(x|a,b) = (\pi b (1 + (\frac{x-a}{b})^2))^{-1}@f$
*
* @headerfile random
* @since C++11
*/
template<typename _RealType = double>
class cauchy_distribution
@ -3092,6 +3147,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* (\frac{m}{n})^{m/2} x^{(m/2)-1}
* (1 + \frac{mx}{n})^{-(m+n)/2}
* @f]
*
* @headerfile random
* @since C++11
*/
template<typename _RealType = double>
class fisher_f_distribution
@ -3328,6 +3386,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* p(x|n) = \frac{1}{\sqrt(n\pi)} \frac{\Gamma((n+1)/2)}{\Gamma(n/2)}
* (1 + \frac{x^2}{n}) ^{-(n+1)/2}
* @f]
*
* @headerfile random
* @since C++11
*/
template<typename _RealType = double>
class student_t_distribution
@ -3559,6 +3620,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*
* Generates a sequence of true and false values with likelihood @f$p@f$
* that true will come up and @f$(1 - p)@f$ that false will appear.
*
* @headerfile random
* @since C++11
*/
class bernoulli_distribution
{
@ -3779,6 +3843,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* The formula for the binomial probability density function is
* @f$p(i|t,p) = \binom{t}{i} p^i (1 - p)^{t - i}@f$ where @f$t@f$
* and @f$p@f$ are the parameters of the distribution.
*
* @headerfile random
* @since C++11
*/
template<typename _IntType = int>
class binomial_distribution
@ -4022,6 +4089,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* The formula for the geometric probability density function is
* @f$p(i|p) = p(1 - p)^{i}@f$ where @f$p@f$ is the parameter of the
* distribution.
*
* @headerfile random
* @since C++11
*/
template<typename _IntType = int>
class geometric_distribution
@ -4236,6 +4306,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* The formula for the negative binomial probability mass function is
* @f$p(i) = \binom{n}{i} p^i (1 - p)^{t - i}@f$ where @f$t@f$
* and @f$p@f$ are the parameters of the distribution.
*
* @headerfile random
* @since C++11
*/
template<typename _IntType = int>
class negative_binomial_distribution
@ -4470,6 +4543,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* The formula for the Poisson probability density function is
* @f$p(i|\mu) = \frac{\mu^i}{i!} e^{-\mu}@f$ where @f$\mu@f$ is the
* parameter of the distribution.
*
* @headerfile random
* @since C++11
*/
template<typename _IntType = int>
class poisson_distribution
@ -4699,6 +4775,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* <tr><td>Range</td><td>@f$[0, \infty]@f$</td></tr>
* <tr><td>Standard Deviation</td><td>@f$\frac{1}{\lambda}@f$</td></tr>
* </table>
*
* @headerfile random
* @since C++11
*/
template<typename _RealType = double>
class exponential_distribution
@ -4918,6 +4997,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* p(x|\alpha,\beta) = \frac{\alpha}{\beta} (\frac{x}{\beta})^{\alpha-1}
* \exp{(-(\frac{x}{\beta})^\alpha)}
* @f]
*
* @headerfile random
* @since C++11
*/
template<typename _RealType = double>
class weibull_distribution
@ -5132,6 +5214,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* p(x|a,b) = \frac{1}{b}
* \exp( \frac{a-x}{b} - \exp(\frac{a-x}{b}))
* @f]
*
* @headerfile random
* @since C++11
*/
template<typename _RealType = double>
class extreme_value_distribution
@ -5337,12 +5422,23 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
operator>>(std::basic_istream<_CharT, _Traits>& __is,
std::extreme_value_distribution<_RealType>& __x);
/// @} group random_distributions_poisson
/**
* @addtogroup random_distributions_sampling Sampling Distributions
* @ingroup random_distributions
* @{
*/
/**
* @brief A discrete_distribution random number distribution.
*
* The formula for the discrete probability mass function is
* This distribution produces random numbers @f$ i, 0 \leq i < n @f$,
* distributed according to the probability mass function
* @f$ p(i | p_0, ..., p_{n-1}) = p_i @f$.
*
* @headerfile random
* @since C++11
*/
template<typename _IntType = int>
class discrete_distribution
@ -5579,8 +5675,18 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief A piecewise_constant_distribution random number distribution.
*
* The formula for the piecewise constant probability mass function is
* This distribution produces random numbers @f$ x, b_0 \leq x < b_n @f$,
* uniformly distributed over each subinterval @f$ [b_i, b_{i+1}) @f$
* according to the probability mass function
* @f[
* p(x | b_0, ..., b_n, \rho_0, ..., \rho_{n-1})
* = \rho_i \cdot \frac{b_{i+1} - x}{b_{i+1} - b_i}
* + \rho_{i+1} \cdot \frac{ x - b_i}{b_{i+1} - b_i}
* @f]
* for @f$ b_i \leq x < b_{i+1} @f$.
*
* @headerfile random
* @since C++11
*/
template<typename _RealType = double>
class piecewise_constant_distribution
@ -5853,8 +5959,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief A piecewise_linear_distribution random number distribution.
*
* The formula for the piecewise linear probability mass function is
* This distribution produces random numbers @f$ x, b_0 \leq x < b_n @f$,
* distributed over each subinterval @f$ [b_i, b_{i+1}) @f$
* according to the probability mass function
* @f$ p(x | b_0, ..., b_n, \rho_0, ..., \rho_n) = \rho_i @f$,
* for @f$ b_i \leq x < b_{i+1} @f$.
*
* @headerfile random
* @since C++11
*/
template<typename _RealType = double>
class piecewise_linear_distribution
@ -6126,7 +6238,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ return !(__d1 == __d2); }
#endif
/// @} group random_distributions_poisson
/// @} group random_distributions_sampling
/// @} *group random_distributions
@ -6139,6 +6251,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief The seed_seq class generates sequences of seeds for random
* number generators.
*
* @headerfile random
* @since C++11
*/
class seed_seq
{

11
libstdc++-v3/include/bits/uniform_int_dist.h
View file

@ -44,6 +44,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#ifdef __cpp_lib_concepts
/// Requirements for a uniform random bit generator.
/**
* @ingroup random_distributions_uniform
* @headerfile random
* @since C++20
*/
template<typename _Gen>
concept uniform_random_bit_generator
= invocable<_Gen&> && unsigned_integral<invoke_result_t<_Gen&>>
@ -55,6 +60,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
};
#endif
/// @cond undocumented
namespace __detail
{
// Determine whether number is a power of two.
@ -67,11 +73,16 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return ((__x - 1) & __x) == 0;
}
}
/// @endcond
/**
* @brief Uniform discrete distribution for random numbers.
* A discrete random distribution on the range @f$[min, max]@f$ with equal
* probability throughout the range.
*
* @ingroup random_distributions_uniform
* @headerfile random
* @since C++11
*/
template<typename _IntType = int>
class uniform_int_distribution