26 Numerics library [numerics]

26.1 General [numerics.general]

This Clause describes components that C++ programs may use to perform seminumerical operations.
The following subclauses describe components for complex number types, random number generation, numeric (n-at-a-time) arrays, generalized numeric algorithms, and mathematical constants and functions for floating-point types, as summarized in Table 92.
Table 92: Numerics library summary [tab:numerics.summary]
Subclause
Header
Requirements
Floating-point environment
<cfenv>
Complex numbers
<complex>
Bit manipulation
<bit>
Random number generation
<random>
Numeric arrays
<valarray>
Mathematical functions for floating-point types
<cmath>, <cstdlib>
Numbers
<numbers>

26.2 Numeric type requirements [numeric.requirements]

The complex and valarray components are parameterized by the type of information they contain and manipulate.
A C++ program shall instantiate these components only with a numeric type.
A numeric type is a cv-unqualified object type T that meets the Cpp17DefaultConstructible, Cpp17CopyConstructible, Cpp17CopyAssignable, and Cpp17Destructible requirements ([utility.arg.requirements]).246
If any operation on T throws an exception the effects are undefined.
In addition, many member and related functions of valarray<T> can be successfully instantiated and will exhibit well-defined behavior if and only if T meets additional requirements specified for each such member or related function.
[Example 1:
It is valid to instantiate valarray<complex>, but operator>() will not be successfully instantiated for valarray<complex> operands, since complex does not have any ordering operators.
— end example]
In other words, value types.
These include arithmetic types, pointers, the library class complex, and instantiations of valarray for value types.
 

26.3 The floating-point environment [cfenv]

26.3.1 Header <cfenv> synopsis [cfenv.syn]

#define FE_ALL_EXCEPT see below #define FE_DIVBYZERO see below // optional #define FE_INEXACT see below // optional #define FE_INVALID see below // optional #define FE_OVERFLOW see below // optional #define FE_UNDERFLOW see below // optional #define FE_DOWNWARD see below // optional #define FE_TONEAREST see below // optional #define FE_TOWARDZERO see below // optional #define FE_UPWARD see below // optional #define FE_DFL_ENV see below namespace std { // types using fenv_t = object type; using fexcept_t = integer type; // functions int feclearexcept(int except); int fegetexceptflag(fexcept_t* pflag, int except); int feraiseexcept(int except); int fesetexceptflag(const fexcept_t* pflag, int except); int fetestexcept(int except); int fegetround(); int fesetround(int mode); int fegetenv(fenv_t* penv); int feholdexcept(fenv_t* penv); int fesetenv(const fenv_t* penv); int feupdateenv(const fenv_t* penv); }
The contents and meaning of the header <cfenv> are the same as the C standard library header <fenv.h>.
[Note 1:
This document does not require an implementation to support the FENV_­ACCESS pragma; it is implementation-defined ([cpp.pragma]) whether the pragma is supported.
As a consequence, it is implementation-defined whether these functions can be used to test floating-point status flags, set floating-point control modes, or run under non-default mode settings.
If the pragma is used to enable control over the floating-point environment, this document does not specify the effect on floating-point evaluation in constant expressions.
— end note]
See also: ISO C 7.6

26.3.2 Threads [cfenv.thread]

The floating-point environment has thread storage duration.
The initial state for a thread's floating-point environment is the state of the floating-point environment of the thread that constructs the corresponding thread object ([thread.thread.class]) or jthread object ([thread.jthread.class]) at the time it constructed the object.
[Note 1:
That is, the child thread gets the floating-point state of the parent thread at the time of the child's creation.
— end note]
A separate floating-point environment is maintained for each thread.
Each function accesses the environment corresponding to its calling thread.

26.4 Complex numbers [complex.numbers]

26.4.1 General [complex.numbers.general]

The header <complex> defines a class template, and numerous functions for representing and manipulating complex numbers.
The effect of instantiating the template complex for any type other than float, double, or long double is unspecified.
The specializations complex<float>, complex<double>, and complex<long double> are literal types.
If the result of a function is not mathematically defined or not in the range of representable values for its type, the behavior is undefined.
If z is an lvalue of type cv complex<T> then:
  • the expression reinterpret_­cast<cv T(&)[2]>(z) is well-formed,
  • reinterpret_­cast<cv T(&)[2]>(z)[0] designates the real part of z, and
  • reinterpret_­cast<cv T(&)[2]>(z)[1] designates the imaginary part of z.
Moreover, if a is an expression of type cv complex<T>* and the expression a[i] is well-defined for an integer expression i, then:
  • reinterpret_­cast<cv T*>(a)[2*i] designates the real part of a[i], and
  • reinterpret_­cast<cv T*>(a)[2*i + 1] designates the imaginary part of a[i].

26.4.2 Header <complex> synopsis [complex.syn]

namespace std { // [complex], class template complex template<class T> class complex; // [complex.special], specializations template<> class complex<float>; template<> class complex<double>; template<> class complex<long double>; // [complex.ops], operators template<class T> constexpr complex<T> operator+(const complex<T>&, const complex<T>&); template<class T> constexpr complex<T> operator+(const complex<T>&, const T&); template<class T> constexpr complex<T> operator+(const T&, const complex<T>&); template<class T> constexpr complex<T> operator-(const complex<T>&, const complex<T>&); template<class T> constexpr complex<T> operator-(const complex<T>&, const T&); template<class T> constexpr complex<T> operator-(const T&, const complex<T>&); template<class T> constexpr complex<T> operator*(const complex<T>&, const complex<T>&); template<class T> constexpr complex<T> operator*(const complex<T>&, const T&); template<class T> constexpr complex<T> operator*(const T&, const complex<T>&); template<class T> constexpr complex<T> operator/(const complex<T>&, const complex<T>&); template<class T> constexpr complex<T> operator/(const complex<T>&, const T&); template<class T> constexpr complex<T> operator/(const T&, const complex<T>&); template<class T> constexpr complex<T> operator+(const complex<T>&); template<class T> constexpr complex<T> operator-(const complex<T>&); template<class T> constexpr bool operator==(const complex<T>&, const complex<T>&); template<class T> constexpr bool operator==(const complex<T>&, const T&); template<class T, class charT, class traits> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&, complex<T>&); template<class T, class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const complex<T>&); // [complex.value.ops], values template<class T> constexpr T real(const complex<T>&); template<class T> constexpr T imag(const complex<T>&); template<class T> T abs(const complex<T>&); template<class T> T arg(const complex<T>&); template<class T> constexpr T norm(const complex<T>&); template<class T> constexpr complex<T> conj(const complex<T>&); template<class T> complex<T> proj(const complex<T>&); template<class T> complex<T> polar(const T&, const T& = T()); // [complex.transcendentals], transcendentals template<class T> complex<T> acos(const complex<T>&); template<class T> complex<T> asin(const complex<T>&); template<class T> complex<T> atan(const complex<T>&); template<class T> complex<T> acosh(const complex<T>&); template<class T> complex<T> asinh(const complex<T>&); template<class T> complex<T> atanh(const complex<T>&); template<class T> complex<T> cos (const complex<T>&); template<class T> complex<T> cosh (const complex<T>&); template<class T> complex<T> exp (const complex<T>&); template<class T> complex<T> log (const complex<T>&); template<class T> complex<T> log10(const complex<T>&); template<class T> complex<T> pow (const complex<T>&, const T&); template<class T> complex<T> pow (const complex<T>&, const complex<T>&); template<class T> complex<T> pow (const T&, const complex<T>&); template<class T> complex<T> sin (const complex<T>&); template<class T> complex<T> sinh (const complex<T>&); template<class T> complex<T> sqrt (const complex<T>&); template<class T> complex<T> tan (const complex<T>&); template<class T> complex<T> tanh (const complex<T>&); // [complex.literals], complex literals inline namespace literals { inline namespace complex_literals { constexpr complex<long double> operator""il(long double); constexpr complex<long double> operator""il(unsigned long long); constexpr complex<double> operator""i(long double); constexpr complex<double> operator""i(unsigned long long); constexpr complex<float> operator""if(long double); constexpr complex<float> operator""if(unsigned long long); } } }

26.4.3 Class template complex [complex]

namespace std { template<class T> class complex { public: using value_type = T; constexpr complex(const T& re = T(), const T& im = T()); constexpr complex(const complex&); template<class X> constexpr complex(const complex<X>&); constexpr T real() const; constexpr void real(T); constexpr T imag() const; constexpr void imag(T); constexpr complex& operator= (const T&); constexpr complex& operator+=(const T&); constexpr complex& operator-=(const T&); constexpr complex& operator*=(const T&); constexpr complex& operator/=(const T&); constexpr complex& operator=(const complex&); template<class X> constexpr complex& operator= (const complex<X>&); template<class X> constexpr complex& operator+=(const complex<X>&); template<class X> constexpr complex& operator-=(const complex<X>&); template<class X> constexpr complex& operator*=(const complex<X>&); template<class X> constexpr complex& operator/=(const complex<X>&); }; }
The class complex describes an object that can store the Cartesian components, real() and imag(), of a complex number.

26.4.4 Specializations [complex.special]

namespace std { template<> class complex<float> { public: using value_type = float; constexpr complex(float re = 0.0f, float im = 0.0f); constexpr complex(const complex<float>&) = default; constexpr explicit complex(const complex<double>&); constexpr explicit complex(const complex<long double>&); constexpr float real() const; constexpr void real(float); constexpr float imag() const; constexpr void imag(float); constexpr complex& operator= (float); constexpr complex& operator+=(float); constexpr complex& operator-=(float); constexpr complex& operator*=(float); constexpr complex& operator/=(float); constexpr complex& operator=(const complex&); template<class X> constexpr complex& operator= (const complex<X>&); template<class X> constexpr complex& operator+=(const complex<X>&); template<class X> constexpr complex& operator-=(const complex<X>&); template<class X> constexpr complex& operator*=(const complex<X>&); template<class X> constexpr complex& operator/=(const complex<X>&); }; template<> class complex<double> { public: using value_type = double; constexpr complex(double re = 0.0, double im = 0.0); constexpr complex(const complex<float>&); constexpr complex(const complex<double>&) = default; constexpr explicit complex(const complex<long double>&); constexpr double real() const; constexpr void real(double); constexpr double imag() const; constexpr void imag(double); constexpr complex& operator= (double); constexpr complex& operator+=(double); constexpr complex& operator-=(double); constexpr complex& operator*=(double); constexpr complex& operator/=(double); constexpr complex& operator=(const complex&); template<class X> constexpr complex& operator= (const complex<X>&); template<class X> constexpr complex& operator+=(const complex<X>&); template<class X> constexpr complex& operator-=(const complex<X>&); template<class X> constexpr complex& operator*=(const complex<X>&); template<class X> constexpr complex& operator/=(const complex<X>&); }; template<> class complex<long double> { public: using value_type = long double; constexpr complex(long double re = 0.0L, long double im = 0.0L); constexpr complex(const complex<float>&); constexpr complex(const complex<double>&); constexpr complex(const complex<long double>&) = default; constexpr long double real() const; constexpr void real(long double); constexpr long double imag() const; constexpr void imag(long double); constexpr complex& operator= (long double); constexpr complex& operator+=(long double); constexpr complex& operator-=(long double); constexpr complex& operator*=(long double); constexpr complex& operator/=(long double); constexpr complex& operator=(const complex&); template<class X> constexpr complex& operator= (const complex<X>&); template<class X> constexpr complex& operator+=(const complex<X>&); template<class X> constexpr complex& operator-=(const complex<X>&); template<class X> constexpr complex& operator*=(const complex<X>&); template<class X> constexpr complex& operator/=(const complex<X>&); }; }

26.4.5 Member functions [complex.members]

template<class T> constexpr complex(const T& re = T(), const T& im = T());
Postconditions: real() == re && imag() == im is true.
constexpr T real() const;
Returns: The value of the real component.
constexpr void real(T val);
Effects: Assigns val to the real component.
constexpr T imag() const;
Returns: The value of the imaginary component.
constexpr void imag(T val);
Effects: Assigns val to the imaginary component.

26.4.6 Member operators [complex.member.ops]

constexpr complex& operator+=(const T& rhs);
Effects: Adds the scalar value rhs to the real part of the complex value *this and stores the result in the real part of *this, leaving the imaginary part unchanged.
Returns: *this.
constexpr complex& operator-=(const T& rhs);
Effects: Subtracts the scalar value rhs from the real part of the complex value *this and stores the result in the real part of *this, leaving the imaginary part unchanged.
Returns: *this.
constexpr complex& operator*=(const T& rhs);
Effects: Multiplies the scalar value rhs by the complex value *this and stores the result in *this.
Returns: *this.
constexpr complex& operator/=(const T& rhs);
Effects: Divides the scalar value rhs into the complex value *this and stores the result in *this.
Returns: *this.
template<class X> constexpr complex& operator+=(const complex<X>& rhs);
Effects: Adds the complex value rhs to the complex value *this and stores the sum in *this.
Returns: *this.
template<class X> constexpr complex& operator-=(const complex<X>& rhs);
Effects: Subtracts the complex value rhs from the complex value *this and stores the difference in *this.
Returns: *this.
template<class X> constexpr complex& operator*=(const complex<X>& rhs);
Effects: Multiplies the complex value rhs by the complex value *this and stores the product in *this.
Returns: *this.
template<class X> constexpr complex& operator/=(const complex<X>& rhs);
Effects: Divides the complex value rhs into the complex value *this and stores the quotient in *this.
Returns: *this.

26.4.7 Non-member operations [complex.ops]

template<class T> constexpr complex<T> operator+(const complex<T>& lhs);
Returns: complex<T>(lhs).
template<class T> constexpr complex<T> operator+(const complex<T>& lhs, const complex<T>& rhs); template<class T> constexpr complex<T> operator+(const complex<T>& lhs, const T& rhs); template<class T> constexpr complex<T> operator+(const T& lhs, const complex<T>& rhs);
Returns: complex<T>(lhs) += rhs.
template<class T> constexpr complex<T> operator-(const complex<T>& lhs);
Returns: complex<T>(-lhs.real(),-lhs.imag()).
template<class T> constexpr complex<T> operator-(const complex<T>& lhs, const complex<T>& rhs); template<class T> constexpr complex<T> operator-(const complex<T>& lhs, const T& rhs); template<class T> constexpr complex<T> operator-(const T& lhs, const complex<T>& rhs);
Returns: complex<T>(lhs) -= rhs.
template<class T> constexpr complex<T> operator*(const complex<T>& lhs, const complex<T>& rhs); template<class T> constexpr complex<T> operator*(const complex<T>& lhs, const T& rhs); template<class T> constexpr complex<T> operator*(const T& lhs, const complex<T>& rhs);
Returns: complex<T>(lhs) *= rhs.
template<class T> constexpr complex<T> operator/(const complex<T>& lhs, const complex<T>& rhs); template<class T> constexpr complex<T> operator/(const complex<T>& lhs, const T& rhs); template<class T> constexpr complex<T> operator/(const T& lhs, const complex<T>& rhs);
Returns: complex<T>(lhs) /= rhs.
template<class T> constexpr bool operator==(const complex<T>& lhs, const complex<T>& rhs); template<class T> constexpr bool operator==(const complex<T>& lhs, const T& rhs);
Returns: lhs.real() == rhs.real() && lhs.imag() == rhs.imag().
Remarks: The imaginary part is assumed to be T(), or 0.0, for the T arguments.
template<class T, class charT, class traits> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, complex<T>& x);
Preconditions: The input values are convertible to T.
Effects: Extracts a complex number x of the form: u, (u), or (u,v), where u is the real part and v is the imaginary part ([istream.formatted]).
If bad input is encountered, calls is.setstate(ios_­base​::​failbit) (which may throw ios_­base​::​​failure ([iostate.flags])).
Returns: is.
Remarks: This extraction is performed as a series of simpler extractions.
Therefore, the skipping of whitespace is specified to be the same for each of the simpler extractions.
template<class T, class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& o, const complex<T>& x);
Effects: Inserts the complex number x onto the stream o as if it were implemented as follows: basic_ostringstream<charT, traits> s; s.flags(o.flags()); s.imbue(o.getloc()); s.precision(o.precision()); s << '(' << x.real() << "," << x.imag() << ')'; return o << s.str();
[Note 1:
In a locale in which comma is used as a decimal point character, the use of comma as a field separator can be ambiguous.
Inserting showpoint into the output stream forces all outputs to show an explicit decimal point character; as a result, all inserted sequences of complex numbers can be extracted unambiguously.
— end note]

26.4.8 Value operations [complex.value.ops]

template<class T> constexpr T real(const complex<T>& x);
Returns: x.real().
template<class T> constexpr T imag(const complex<T>& x);
Returns: x.imag().
template<class T> T abs(const complex<T>& x);
Returns: The magnitude of x.
template<class T> T arg(const complex<T>& x);
Returns: The phase angle of x, or atan2(imag(x), real(x)).
template<class T> constexpr T norm(const complex<T>& x);
Returns: The squared magnitude of x.
template<class T> constexpr complex<T> conj(const complex<T>& x);
Returns: The complex conjugate of x.
template<class T> complex<T> proj(const complex<T>& x);
Returns: The projection of x onto the Riemann sphere.
Remarks: Behaves the same as the C function cproj.
See also: ISO C 7.3.9.5
template<class T> complex<T> polar(const T& rho, const T& theta = T());
Preconditions: rho is non-negative and non-NaN.
theta is finite.
Returns: The complex value corresponding to a complex number whose magnitude is rho and whose phase angle is theta.

26.4.9 Transcendentals [complex.transcendentals]

template<class T> complex<T> acos(const complex<T>& x);
Returns: The complex arc cosine of x.
Remarks: Behaves the same as the C function cacos.
See also: ISO C 7.3.5.1
template<class T> complex<T> asin(const complex<T>& x);
Returns: The complex arc sine of x.
Remarks: Behaves the same as the C function casin.
See also: ISO C 7.3.5.2
template<class T> complex<T> atan(const complex<T>& x);
Returns: The complex arc tangent of x.
Remarks: Behaves the same as the C function catan.
See also: ISO C 7.3.5.3
template<class T> complex<T> acosh(const complex<T>& x);
Returns: The complex arc hyperbolic cosine of x.
Remarks: Behaves the same as the C function cacosh.
See also: ISO C 7.3.6.1
template<class T> complex<T> asinh(const complex<T>& x);
Returns: The complex arc hyperbolic sine of x.
Remarks: Behaves the same as the C function casinh.
See also: ISO C 7.3.6.2
template<class T> complex<T> atanh(const complex<T>& x);
Returns: The complex arc hyperbolic tangent of x.
Remarks: Behaves the same as the C function catanh.
See also: ISO C 7.3.6.3
template<class T> complex<T> cos(const complex<T>& x);
Returns: The complex cosine of x.
template<class T> complex<T> cosh(const complex<T>& x);
Returns: The complex hyperbolic cosine of x.
template<class T> complex<T> exp(const complex<T>& x);
Returns: The complex base-e exponential of x.
template<class T> complex<T> log(const complex<T>& x);
Returns: The complex natural (base-e) logarithm of x.
For all x, imag(log(x)) lies in the interval [, π].
[Note 1:
The semantics of this function are intended to be the same in C++ as they are for clog in C.
— end note]
Remarks: The branch cuts are along the negative real axis.
template<class T> complex<T> log10(const complex<T>& x);
Returns: The complex common (base-10) logarithm of x, defined as log(x) / log(10).
Remarks: The branch cuts are along the negative real axis.
template<class T> complex<T> pow(const complex<T>& x, const complex<T>& y); template<class T> complex<T> pow(const complex<T>& x, const T& y); template<class T> complex<T> pow(const T& x, const complex<T>& y);
Returns: The complex power of base x raised to the power, defined as exp(y * log(x)).
The value returned for pow(0, 0) is implementation-defined.
Remarks: The branch cuts are along the negative real axis.
template<class T> complex<T> sin(const complex<T>& x);
Returns: The complex sine of x.
template<class T> complex<T> sinh(const complex<T>& x);
Returns: The complex hyperbolic sine of x.
template<class T> complex<T> sqrt(const complex<T>& x);
Returns: The complex square root of x, in the range of the right half-plane.
[Note 2:
The semantics of this function are intended to be the same in C++ as they are for csqrt in C.
— end note]
Remarks: The branch cuts are along the negative real axis.
template<class T> complex<T> tan(const complex<T>& x);
Returns: The complex tangent of x.
template<class T> complex<T> tanh(const complex<T>& x);
Returns: The complex hyperbolic tangent of x.

26.4.10 Additional overloads [cmplx.over]

The following function templates shall have additional overloads: arg norm conj proj imag real where norm, conj, imag, and real are constexpr overloads.
The additional overloads shall be sufficient to ensure:
  • If the argument has type long double, then it is effectively cast to complex<long double>.
  • Otherwise, if the argument has type double or an integer type, then it is effectively cast to complex<double>.
  • Otherwise, if the argument has type float, then it is effectively cast to complex<float>.
Function template pow shall have additional overloads sufficient to ensure, for a call with at least one argument of type complex<T>:
  • If either argument has type complex<long double> or type long double, then both arguments are effectively cast to complex<long double>.
  • Otherwise, if either argument has type complex<double>, double, or an integer type, then both arguments are effectively cast to complex<double>.
  • Otherwise, if either argument has type complex<float> or float, then both arguments are effectively cast to complex<float>.

26.4.11 Suffixes for complex number literals [complex.literals]

This subclause describes literal suffixes for constructing complex number literals.
The suffixes i, il, and if create complex numbers of the types complex<double>, complex<long double>, and complex<float> respectively, with their imaginary part denoted by the given literal number and the real part being zero.
constexpr complex<long double> operator""il(long double d); constexpr complex<long double> operator""il(unsigned long long d);
Returns: complex<long double>{0.0L, static_­cast<long double>(d)}.
constexpr complex<double> operator""i(long double d); constexpr complex<double> operator""i(unsigned long long d);
Returns: complex<double>{0.0, static_­cast<double>(d)}.
constexpr complex<float> operator""if(long double d); constexpr complex<float> operator""if(unsigned long long d);
Returns: complex<float>{0.0f, static_­cast<float>(d)}.

26.5 Bit manipulation [bit]

26.5.1 General [bit.general]

The header <bit> provides components to access, manipulate and process both individual bits and bit sequences.

26.5.2 Header <bit> synopsis [bit.syn]

namespace std { // [bit.cast], bit_­cast template<class To, class From> constexpr To bit_cast(const From& from) noexcept; // [bit.pow.two], integral powers of 2 template<class T> constexpr bool has_single_bit(T x) noexcept; template<class T> constexpr T bit_ceil(T x); template<class T> constexpr T bit_floor(T x) noexcept; template<class T> constexpr T bit_width(T x) noexcept; // [bit.rotate], rotating template<class T> [[nodiscard]] constexpr T rotl(T x, int s) noexcept; template<class T> [[nodiscard]] constexpr T rotr(T x, int s) noexcept; // [bit.count], counting template<class T> constexpr int countl_zero(T x) noexcept; template<class T> constexpr int countl_one(T x) noexcept; template<class T> constexpr int countr_zero(T x) noexcept; template<class T> constexpr int countr_one(T x) noexcept; template<class T> constexpr int popcount(T x) noexcept; // [bit.endian], endian enum class endian { little = see below, big = see below, native = see below }; }

26.5.3 Function template bit_­cast [bit.cast]

template<class To, class From> constexpr To bit_cast(const From& from) noexcept;
Constraints:
  • sizeof(To) == sizeof(From) is true;
  • is_­trivially_­copyable_­v<To> is true; and
  • is_­trivially_­copyable_­v<From> is true.
Returns: An object of type To.
Implicitly creates objects nested within the result ([intro.object]).
Each bit of the value representation of the result is equal to the corresponding bit in the object representation of from.
Padding bits of the result are unspecified.
For the result and each object created within it, if there is no value of the object's type corresponding to the value representation produced, the behavior is undefined.
If there are multiple such values, which value is produced is unspecified.
Remarks: This function is constexpr if and only if To, From, and the types of all subobjects of To and From are types T such that:
  • is_­union_­v<T> is false;
  • is_­pointer_­v<T> is false;
  • is_­member_­pointer_­v<T> is false;
  • is_­volatile_­v<T> is false; and
  • T has no non-static data members of reference type.

26.5.4 Integral powers of 2 [bit.pow.two]

template<class T> constexpr bool has_single_bit(T x) noexcept;
Constraints: T is an unsigned integer type ([basic.fundamental]).
Returns: true if x is an integral power of two; false otherwise.
template<class T> constexpr T bit_ceil(T x);
Let N be the smallest power of 2 greater than or equal to x.
Constraints: T is an unsigned integer type ([basic.fundamental]).
Preconditions: N is representable as a value of type T.
Returns: N.
Throws: Nothing.
Remarks: A function call expression that violates the precondition in the Preconditions: element is not a core constant expression ([expr.const]).
template<class T> constexpr T bit_floor(T x) noexcept;
Constraints: T is an unsigned integer type ([basic.fundamental]).
Returns: If x == 0, 0; otherwise the maximal value y such that has_­single_­bit(y) is true and y <= x.
template<class T> constexpr T bit_width(T x) noexcept;
Constraints: T is an unsigned integer type ([basic.fundamental]).
Returns: If x == 0, 0; otherwise one plus the base-2 logarithm of x, with any fractional part discarded.

26.5.5 Rotating [bit.rotate]

In the following descriptions, let N denote numeric_­limits<T>​::​digits.
template<class T> [[nodiscard]] constexpr T rotl(T x, int s) noexcept;
Constraints: T is an unsigned integer type ([basic.fundamental]).
Let r be s % N.
Returns: If r is 0, x; if r is positive, (x << r) | (x >> (N - r)); if r is negative, rotr(x, -r).
template<class T> [[nodiscard]] constexpr T rotr(T x, int s) noexcept;
Constraints: T is an unsigned integer type ([basic.fundamental]).
Let r be s % N.
Returns: If r is 0, x; if r is positive, (x >> r) | (x << (N - r)); if r is negative, rotl(x, -r).

26.5.6 Counting [bit.count]

In the following descriptions, let N denote numeric_­limits<T>​::​digits.
template<class T> constexpr int countl_zero(T x) noexcept;
Constraints: T is an unsigned integer type ([basic.fundamental]).
Returns: The number of consecutive 0 bits in the value of x, starting from the most significant bit.
[Note 1:
Returns N if x == 0.
— end note]
template<class T> constexpr int countl_one(T x) noexcept;
Constraints: T is an unsigned integer type ([basic.fundamental]).
Returns: The number of consecutive 1 bits in the value of x, starting from the most significant bit.
[Note 2:
Returns N if x == numeric_­limits<T>​::​max().
— end note]
template<class T> constexpr int countr_zero(T x) noexcept;
Constraints: T is an unsigned integer type ([basic.fundamental]).
Returns: The number of consecutive 0 bits in the value of x, starting from the least significant bit.
[Note 3:
Returns N if x == 0.
— end note]
template<class T> constexpr int countr_one(T x) noexcept;
Constraints: T is an unsigned integer type ([basic.fundamental]).
Returns: The number of consecutive 1 bits in the value of x, starting from the least significant bit.
[Note 4:
Returns N if x == numeric_­limits<T>​::​max().
— end note]
template<class T> constexpr int popcount(T x) noexcept;
Constraints: T is an unsigned integer type ([basic.fundamental]).
Returns: The number of 1 bits in the value of x.

26.5.7 Endian [bit.endian]

Two common methods of byte ordering in multibyte scalar types are big-endian and little-endian in the execution environment.
Big-endian is a format for storage of binary data in which the most significant byte is placed first, with the rest in descending order.
Little-endian is a format for storage of binary data in which the least significant byte is placed first, with the rest in ascending order.
This subclause describes the endianness of the scalar types of the execution environment.
enum class endian { little = see below, big = see below, native = see below };
If all scalar types have size 1 byte, then all of endian​::​little, endian​::​big, and endian​::​native have the same value.
Otherwise, endian​::​little is not equal to endian​::​big.
If all scalar types are big-endian, endian​::​native is equal to endian​::​big.
If all scalar types are little-endian, endian​::​native is equal to endian​::​little.
Otherwise, endian​::​native is not equal to either endian​::​big or endian​::​little.

26.6 Random number generation [rand]

26.6.1 General [rand.general]

Subclause [rand] defines a facility for generating (pseudo-)random numbers.
In addition to a few utilities, four categories of entities are described: uniform random bit generators, random number engines, random number engine adaptors, and random number distributions.
These categorizations are applicable to types that meet the corresponding requirements, to objects instantiated from such types, and to templates producing such types when instantiated.
[Note 1:
These entities are specified in such a way as to permit the binding of any uniform random bit generator object e as the argument to any random number distribution object d, thus producing a zero-argument function object such as given by bind(d,e).
— end note]
Each of the entities specified in [rand] has an associated arithmetic type ([basic.fundamental]) identified as result_­type.
With T as the result_­type thus associated with such an entity, that entity is characterized:
If integer-valued, an entity may optionally be further characterized as signed or unsigned, according to numeric_­limits<T>​::​is_­signed.
Unless otherwise specified, all descriptions of calculations in [rand] use mathematical real numbers.
Throughout [rand], the operators bitand, bitor, and xor denote the respective conventional bitwise operations.
Further:
  • the operator rshift denotes a bitwise right shift with zero-valued bits appearing in the high bits of the result, and
  • the operator denotes a bitwise left shift with zero-valued bits appearing in the low bits of the result, and whose result is always taken modulo .

26.6.2 Header <random> synopsis [rand.synopsis]

#include <initializer_list> namespace std { // [rand.req.urng], uniform random bit generator requirements template<class G> concept uniform_random_bit_generator = see below; // [rand.eng.lcong], class template linear_­congruential_­engine template<class UIntType, UIntType a, UIntType c, UIntType m> class linear_congruential_engine; // [rand.eng.mers], class template mersenne_­twister_­engine template<class UIntType, size_t w, size_t n, size_t m, size_t r, UIntType a, size_t u, UIntType d, size_t s, UIntType b, size_t t, UIntType c, size_t l, UIntType f> class mersenne_twister_engine; // [rand.eng.sub], class template subtract_­with_­carry_­engine template<class UIntType, size_t w, size_t s, size_t r> class subtract_with_carry_engine; // [rand.adapt.disc], class template discard_­block_­engine template<class Engine, size_t p, size_t r> class discard_block_engine; // [rand.adapt.ibits], class template independent_­bits_­engine template<class Engine, size_t w, class UIntType> class independent_bits_engine; // [rand.adapt.shuf], class template shuffle_­order_­engine template<class Engine, size_t k> class shuffle_order_engine; // [rand.predef], engines and engine adaptors with predefined parameters using minstd_rand0 = see below; using minstd_rand = see below; using mt19937 = see below; using mt19937_64 = see below; using ranlux24_base = see below; using ranlux48_base = see below; using ranlux24 = see below; using ranlux48 = see below; using knuth_b = see below; using default_random_engine = see below; // [rand.device], class random_­device class random_device; // [rand.util.seedseq], class seed_­seq class seed_seq; // [rand.util.canonical], function template generate_­canonical template<class RealType, size_t bits, class URBG> RealType generate_canonical(URBG& g); // [rand.dist.uni.int], class template uniform_­int_­distribution template<class IntType = int> class uniform_int_distribution; // [rand.dist.uni.real], class template uniform_­real_­distribution template<class RealType = double> class uniform_real_distribution; // [rand.dist.bern.bernoulli], class bernoulli_­distribution class bernoulli_distribution; // [rand.dist.bern.bin], class template binomial_­distribution template<class IntType = int> class binomial_distribution; // [rand.dist.bern.geo], class template geometric_­distribution template<class IntType = int> class geometric_distribution; // [rand.dist.bern.negbin], class template negative_­binomial_­distribution template<class IntType = int> class negative_binomial_distribution; // [rand.dist.pois.poisson], class template poisson_­distribution template<class IntType = int> class poisson_distribution; // [rand.dist.pois.exp], class template exponential_­distribution template<class RealType = double> class exponential_distribution; // [rand.dist.pois.gamma], class template gamma_­distribution template<class RealType = double> class gamma_distribution; // [rand.dist.pois.weibull], class template weibull_­distribution template<class RealType = double> class weibull_distribution; // [rand.dist.pois.extreme], class template extreme_­value_­distribution template<class RealType = double> class extreme_value_distribution; // [rand.dist.norm.normal], class template normal_­distribution template<class RealType = double> class normal_distribution; // [rand.dist.norm.lognormal], class template lognormal_­distribution template<class RealType = double> class lognormal_distribution; // [rand.dist.norm.chisq], class template chi_­squared_­distribution template<class RealType = double> class chi_squared_distribution; // [rand.dist.norm.cauchy], class template cauchy_­distribution template<class RealType = double> class cauchy_distribution; // [rand.dist.norm.f], class template fisher_­f_­distribution template<class RealType = double> class fisher_f_distribution; // [rand.dist.norm.t], class template student_­t_­distribution template<class RealType = double> class student_t_distribution; // [rand.dist.samp.discrete], class template discrete_­distribution template<class IntType = int> class discrete_distribution; // [rand.dist.samp.pconst], class template piecewise_­constant_­distribution template<class RealType = double> class piecewise_constant_distribution; // [rand.dist.samp.plinear], class template piecewise_­linear_­distribution template<class RealType = double> class piecewise_linear_distribution; }

26.6.3 Requirements [rand.req]

26.6.3.1 General requirements [rand.req.genl]

Throughout this subclause [rand], the effect of instantiating a template:
  • that has a template type parameter named Sseq is undefined unless the corresponding template argument is cv-unqualified and meets the requirements of seed sequence.
  • that has a template type parameter named URBG is undefined unless the corresponding template argument is cv-unqualified and meets the requirements of uniform random bit generator.
  • that has a template type parameter named Engine is undefined unless the corresponding template argument is cv-unqualified and meets the requirements of random number engine.
  • that has a template type parameter named RealType is undefined unless the corresponding template argument is cv-unqualified and is one of float, double, or long double.
  • that has a template type parameter named IntType is undefined unless the corresponding template argument is cv-unqualified and is one of short, int, long, long long, unsigned short, unsigned int, unsigned long, or unsigned long long.
  • that has a template type parameter named UIntType is undefined unless the corresponding template argument is cv-unqualified and is one of unsigned short, unsigned int, unsigned long, or unsigned long long.
Throughout this subclause [rand], phrases of the form “x is an iterator of a specific kind” shall be interpreted as equivalent to the more formal requirement that “x is a value of a type meeting the requirements of the specified iterator type”.
Throughout this subclause [rand], any constructor that can be called with a single argument and that meets a requirement specified in this subclause shall be declared explicit.

26.6.3.2 Seed sequence requirements [rand.req.seedseq]

A seed sequence is an object that consumes a sequence of integer-valued data and produces a requested number of unsigned integer values i, , based on the consumed data.
[Note 1:
Such an object provides a mechanism to avoid replication of streams of random variates.
This can be useful, for example, in applications requiring large numbers of random number engines.
— end note]
A class S meets the requirements of a seed sequence if the expressions shown in Table 93 are valid and have the indicated semantics, and if S also meets all other requirements of this subclause [rand.req.seedseq].
In that Table and throughout this subclause:
  • T is the type named by S's associated result_­type;
  • q is a value of S and r is a possibly const value of S;
  • ib and ie are input iterators with an unsigned integer value_­type of at least 32 bits;
  • rb and re are mutable random access iterators with an unsigned integer value_­type of at least 32 bits;
  • ob is an output iterator; and
  • il is a value of initializer_­list<T>.
Table 93: Seed sequence requirements [tab:rand.req.seedseq]
Expression
Return type
Pre/post-condition
Complexity
S​::​result_­type
T
T is an unsigned integer type of at least 32 bits.
compile-time
S()
Creates a seed sequence with the same initial state as all other default-constructed seed sequences of type S.
constant
S(ib,ie)
Creates a seed sequence having internal state that depends on some or all of the bits of the supplied sequence .
S(il)
Same as S(il.begin(), il.end()).
same as S(il.begin(), il.end())
q.generate(rb,re)
void
Does nothing if rb == re.
Otherwise, fills the supplied sequence with 32-bit quantities that depend on the sequence supplied to the constructor and possibly also depend on the history of generate's previous invocations.
r.size()
size_­t
The number of 32-bit units that would be copied by a call to r.param.
constant
r.param(ob)
void
Copies to the given destination a sequence of 32-bit units that can be provided to the constructor of a second object of type S, and that would reproduce in that second object a state indistinguishable from the state of the first object.

26.6.3.3 Uniform random bit generator requirements [rand.req.urng]

A uniform random bit generator g of type G is a function object returning unsigned integer values such that each value in the range of possible results has (ideally) equal probability of being returned.
[Note 1:
The degree to which g's results approximate the ideal is often determined statistically.
— end note]
template<class G> concept uniform_­random_­bit_­generator = invocable<G&> && unsigned_­integral<invoke_result_t<G&>> && requires { { G::min() } -> same_­as<invoke_result_t<G&>>; { G::max() } -> same_­as<invoke_result_t<G&>>; requires bool_constant<(G::min() < G::max())>::value; };
Let g be an object of type G.
G models uniform_­random_­bit_­generator only if
  • G​::​min() <= g(),
  • g() <= G​::​max(), and
  • g() has amortized constant complexity.
A class G meets the uniform random bit generator requirements if G models uniform_­random_­bit_­generator, invoke_­result_­t<G&> is an unsigned integer type ([basic.fundamental]), and G provides a nested typedef-name result_­type that denotes the same type as invoke_­result_­t<G&>.

26.6.3.4 Random number engine requirements [rand.req.eng]

A random number engine (commonly shortened to engine) e of type E is a uniform random bit generator that additionally meets the requirements (e.g., for seeding and for input/output) specified in this subclause.
At any given time, e has a state e for some integer .
Upon construction, e has an initial state e.
An engine's state may be established via a constructor, a seed function, assignment, or a suitable operator>>.
E's specification shall define:
A class E that meets the requirements of a uniform random bit generator also meets the requirements of a random number engine if the expressions shown in Table 94 are valid and have the indicated semantics, and if E also meets all other requirements of this subclause [rand.req.eng].
In that Table and throughout this subclause:
  • T is the type named by E's associated result_­type;
  • e is a value of E, v is an lvalue of E, x and y are (possibly const) values of E;
  • s is a value of T;
  • q is an lvalue meeting the requirements of a seed sequence;
  • z is a value of type unsigned long long;
  • os is an lvalue of the type of some class template specialization basic_­ostream<charT, traits>; and
  • is is an lvalue of the type of some class template specialization basic_­istream<charT, traits>;
where charT and traits are constrained according to [strings] and [input.output].
Table 94: Random number engine requirements [tab:rand.req.eng]
Expression
Return type
Pre/post-condition
Complexity
E()
Creates an engine with the same initial state as all other default-constructed engines of type E.
E(x)
Creates an engine that compares equal to x.
E(s)
Creates an engine with initial state determined by s.
E(q)247
Creates an engine with an initial state that depends on a sequence produced by one call to q.generate.
same as complexity of q.generate called on a sequence whose length is size of state
e.seed()
void
Postconditions: e == E().
same as E()
e.seed(s)
void
Postconditions: e == E(s).
same as E(s)
e.seed(q)
void
Postconditions: e == E(q).
same as E(q)
e()
T
Advances e's state e to e e) and returns GA(e).
e.discard(z)248
void
Advances e's state e to by any means equivalent to z consecutive calls e().
no worse than the complexity of z consecutive calls e()
x == y
bool
This operator is an equivalence relation.
With and as the infinite sequences of values that would be generated by repeated future calls to x() and y(), respectively, returns true if ; else returns false.
x != y
bool
!(x == y).
os << x
reference to the type of os
With os.fmtflags set to ios_­base​::​dec|ios_­base​::​left and the fill character set to the space character, writes to os the textual representation of x's current state.
In the output, adjacent numbers are separated by one or more space characters.
Postconditions: The os.fmtflags and fill character are unchanged.
is >> v
reference to the type of is
With is.fmtflags set to ios_­base​::​dec, sets v's state as determined by reading its textual representation from is.
If bad input is encountered, ensures that v's state is unchanged by the operation and calls is.setstate(ios_­base​::​failbit) (which may throw ios_­base​::​failure ([iostate.flags])).
If a textual representation written via os << x was subsequently read via is >> v, then x == v provided that there have been no intervening invocations of x or of v.
Preconditions: is provides a textual representation that was previously written using an output stream whose imbued locale was the same as that of is, and whose type's template specialization arguments charT and traits were respectively the same as those of is.
Postconditions: The is.fmtflags are unchanged.
E shall meet the Cpp17CopyConstructible (Table 29) and Cpp17CopyAssignable (Table 31) requirements.
These operations shall each be of complexity no worse than .
This constructor (as well as the subsequent corresponding seed() function) can be particularly useful to applications requiring a large number of independent random sequences.
 
This operation is common in user code, and can often be implemented in an engine-specific manner so as to provide significant performance improvements over an equivalent naive loop that makes z consecutive calls e().
 

26.6.3.5 Random number engine adaptor requirements [rand.req.adapt]

A random number engine adaptor (commonly shortened to adaptor) a of type A is a random number engine that takes values produced by some other random number engine, and applies an algorithm to those values in order to deliver a sequence of values with different randomness properties.
An engine b of type B adapted in this way is termed a base engine in this context.
The expression a.base() shall be valid and shall return a const reference to a's base engine.
The requirements of a random number engine type shall be interpreted as follows with respect to a random number engine adaptor type.
A::A();
Effects: The base engine is initialized as if by its default constructor.
bool operator==(const A& a1, const A& a2);
Returns: true if a1's base engine is equal to a2's base engine.
Otherwise returns false.
A::A(result_type s);
Effects: The base engine is initialized with s.
template<class Sseq> A::A(Sseq& q);
Effects: The base engine is initialized with q.
void seed();
Effects: With b as the base engine, invokes b.seed().
void seed(result_type s);
Effects: With b as the base engine, invokes b.seed(s).
template<class Sseq> void seed(Sseq& q);
Effects: With b as the base engine, invokes b.seed(q).
A shall also meet the following additional requirements:
  • The complexity of each function shall not exceed the complexity of the corresponding function applied to the base engine.
  • The state of A shall include the state of its base engine.
    The size of A's state shall be no less than the size of the base engine.
  • Copying A's state (e.g., during copy construction or copy assignment) shall include copying the state of the base engine of A.
  • The textual representation of A shall include the textual representation of its base engine.

26.6.3.6 Random number distribution requirements [rand.req.dist]

A random number distribution (commonly shortened to distribution) d of type D is a function object returning values that are distributed according to an associated mathematical probability density function p(z) or according to an associated discrete probability function .
A distribution's specification identifies its associated probability function p(z) or .
An associated probability function is typically expressed using certain externally-supplied quantities known as the parameters of the distribution.
Such distribution parameters are identified in this context by writing, for example, or , to name specific parameters, or by writing, for example, p(z|{p}) or , to denote a distribution's parameters p taken as a whole.
A class D meets the requirements of a random number distribution if the expressions shown in Table 95 are valid and have the indicated semantics, and if D and its associated types also meet all other requirements of this subclause [rand.req.dist].
In that Table and throughout this subclause,
  • T is the type named by D's associated result_­type;
  • P is the type named by D's associated param_­type;
  • d is a value of D, and x and y are (possibly const) values of D;
  • glb and lub are values of T respectively corresponding to the greatest lower bound and the least upper bound on the values potentially returned by d's operator(), as determined by the current values of d's parameters;
  • p is a (possibly const) value of P;
  • g, g1, and g2 are lvalues of a type meeting the requirements of a uniform random bit generator;
  • os is an lvalue of the type of some class template specialization basic_­ostream<charT, traits>; and
  • is is an lvalue of the type of some class template specialization basic_­istream<charT, traits>;
where charT and traits are constrained according to [strings] and [input.output].
Table 95: Random number distribution requirements [tab:rand.req.dist]
Expression
Return type
Pre/post-condition
Complexity
D​::​result_­type
T
compile-time
D​::​param_­type
P
compile-time
D()
Creates a distribution whose behavior is indistinguishable from that of any other newly default-constructed distribution of type D.
constant
D(p)
Creates a distribution whose behavior is indistinguishable from that of a distribution newly constructed directly from the values used to construct p.
same as p's construction
d.reset()
void
Subsequent uses of d do not depend on values produced by any engine prior to invoking reset.
constant
x.param()
P
Returns a value p such that D(p).param() == p.
no worse than the complexity of D(p)
d.param(p)
void
Postconditions: d.param() == p.
no worse than the complexity of D(p)
d(g)
T
With , the sequence of numbers returned by successive invocations with the same object g is randomly distributed according to the associated p(z|{p}) or function.
amortized constant number of invocations of g
d(g,p)
T
The sequence of numbers returned by successive invocations with the same objects g and p is randomly distributed according to the associated p(z|{p}) or function.
amortized constant number of invocations of g
x.min()
T
Returns glb.
constant
x.max()
T
Returns lub.
constant
x == y
bool
This operator is an equivalence relation.
Returns true if x.param() == y.param() and , where and are the infinite sequences of values that would be generated, respectively, by repeated future calls to x(g1) and y(g2) whenever g1 == g2.
Otherwise returns false.
constant
x != y
bool
!(x == y).
same as x == y.
os << x
reference to the type of os
Writes to os a textual representation for the parameters and the additional internal data of x.
Postconditions: The os.fmtflags and fill character are unchanged.
is >> d
reference to the type of is
Restores from is the parameters and additional internal data of the lvalue d.
If bad input is encountered, ensures that d is unchanged by the operation and calls is.setstate(ios_­base​::​failbit) (which may throw ios_­base​::​failure ([iostate.flags])).
Preconditions: is provides a textual representation that was previously written using an os whose imbued locale and whose type's template specialization arguments charT and traits were the same as those of is.
Postconditions: The is.fmtflags are unchanged.
D shall meet the Cpp17CopyConstructible (Table 29) and Cpp17CopyAssignable (Table 31) requirements.
The sequence of numbers produced by repeated invocations of d(g) shall be independent of any invocation of os << d or of any const member function of D between any of the invocations d(g).
If a textual representation is written using os << x and that representation is restored into the same or a different object y of the same type using is >> y, repeated invocations of y(g) shall produce the same sequence of numbers as would repeated invocations of x(g).
It is unspecified whether D​::​param_­type is declared as a (nested) class or via a typedef.
In this subclause [rand], declarations of D​::​param_­type are in the form of typedefs for convenience of exposition only.
P shall meet the Cpp17CopyConstructible (Table 29), Cpp17CopyAssignable (Table 31), and Cpp17EqualityComparable (Table 25) requirements.
For each of the constructors of D taking arguments corresponding to parameters of the distribution, P shall have a corresponding constructor subject to the same requirements and taking arguments identical in number, type, and default values.
Moreover, for each of the member functions of D that return values corresponding to parameters of the distribution, P shall have a corresponding member function with the identical name, type, and semantics.
P shall have a declaration of the form using distribution_type = D;

26.6.4 Random number engine class templates [rand.eng]

26.6.4.1 General [rand.eng.general]

Each type instantiated from a class template specified in [rand.eng] meets the requirements of a random number engine type.
Except where specified otherwise, the complexity of each function specified in [rand.eng] is constant.
Except where specified otherwise, no function described in [rand.eng] throws an exception.
Every function described in [rand.eng] that has a function parameter q of type Sseq& for a template type parameter named Sseq that is different from type seed_­seq throws what and when the invocation of q.generate throws.
Descriptions are provided in [rand.eng] only for engine operations that are not described in [rand.req.eng] or for operations where there is additional semantic information.
In particular, declarations for copy constructors, for copy assignment operators, for streaming operators, and for equality and inequality operators are not shown in the synopses.
Each template specified in [rand.eng] requires one or more relationships, involving the value(s) of its non-type template parameter(s), to hold.
A program instantiating any of these templates is ill-formed if any such required relationship fails to hold.
For every random number engine and for every random number engine adaptor X defined in [rand.eng] and in [rand.adapt]:
  • if the constructor template<class Sseq> explicit X(Sseq& q); is called with a type Sseq that does not qualify as a seed sequence, then this constructor shall not participate in overload resolution;
  • if the member function template<class Sseq> void seed(Sseq& q); is called with a type Sseq that does not qualify as a seed sequence, then this function shall not participate in overload resolution.
The extent to which an implementation determines that a type cannot be a seed sequence is unspecified, except that as a minimum a type shall not qualify as a seed sequence if it is implicitly convertible to X​::​result_­type.

26.6.4.2 Class template linear_­congruential_­engine [rand.eng.lcong]

A linear_­congruential_­engine random number engine produces unsigned integer random numbers.
The state x of a linear_­congruential_­engine object x is of size 1 and consists of a single integer.
The transition algorithm is a modular linear function of the form ; the generation algorithm is .
template<class UIntType, UIntType a, UIntType c, UIntType m> class linear_congruential_engine { public: // types using result_type = UIntType; // engine characteristics static constexpr result_type multiplier = a; static constexpr result_type increment = c; static constexpr result_type modulus = m; static constexpr result_type min() { return c == 0u ? 1u: 0u; } static constexpr result_type max() { return m - 1u; } static constexpr result_type default_seed = 1u; // constructors and seeding functions linear_congruential_engine() : linear_congruential_engine(default_seed) {} explicit linear_congruential_engine(result_type s); template<class Sseq> explicit linear_congruential_engine(Sseq& q); void seed(result_type s = default_seed); template<class Sseq> void seed(Sseq& q); // generating functions result_type operator()(); void discard(unsigned long long z); };
If the template parameter m is 0, the modulus m used throughout this subclause [rand.eng.lcong] is numeric_­limits<result_­type>​::​max() plus 1.
[Note 1:
m need not be representable as a value of type result_­type.
— end note]
If the template parameter m is not 0, the following relations shall hold: a < m and c < m.
The textual representation consists of the value of x.
explicit linear_congruential_engine(result_type s);
Effects: If is 0 and is 0, sets the engine's state to 1, otherwise sets the engine's state to .
template<class Sseq> explicit linear_congruential_engine(Sseq& q);
Effects: With and a an array (or equivalent) of length , invokes q.generate(, ) and then computes .
If is 0 and S is 0, sets the engine's state to 1, else sets the engine's state to S.

26.6.4.3 Class template mersenne_­twister_­engine [rand.eng.mers]

A mersenne_­twister_­engine random number engine249 produces unsigned integer random numbers in the closed interval .
The state x of a mersenne_­twister_­engine object x is of size n and consists of a sequence X of n values of the type delivered by x; all subscripts applied to X are to be taken modulo n.
The transition algorithm employs a twisted generalized feedback shift register defined by shift values n and m, a twist value r, and a conditional xor-mask a.
To improve the uniformity of the result, the bits of the raw shift register are additionally tempered (i.e., scrambled) according to a bit-scrambling matrix defined by values u, d, s, b, t, c, and .
The state transition is performed as follows:
  • Concatenate the upper bits of with the lower r bits of to obtain an unsigned integer value Y.
  • With , set to .
The sequence X is initialized with the help of an initialization multiplier f.
The generation algorithm determines the unsigned integer values as follows, then delivers as its result:
  • Let .
  • Let .
  • Let .
  • Let .
template<class UIntType, size_t w, size_t n, size_t m, size_t r, UIntType a, size_t u, UIntType d, size_t s, UIntType b, size_t t, UIntType c, size_t l, UIntType f> class mersenne_twister_engine { public: // types using result_type = UIntType; // engine characteristics static constexpr size_t word_size = w; static constexpr size_t state_size = n; static constexpr size_t shift_size = m; static constexpr size_t mask_bits = r; static constexpr UIntType xor_mask = a; static constexpr size_t tempering_u = u; static constexpr UIntType tempering_d = d; static constexpr size_t tempering_s = s; static constexpr UIntType tempering_b = b; static constexpr size_t tempering_t = t; static constexpr UIntType tempering_c = c; static constexpr size_t tempering_l = l; static constexpr UIntType initialization_multiplier = f; static constexpr result_type min() { return 0; } static constexpr result_type max() { return ; } static constexpr result_type default_seed = 5489u; // constructors and seeding functions mersenne_twister_engine() : mersenne_twister_engine(default_seed) {} explicit mersenne_twister_engine(result_type value); template<class Sseq> explicit mersenne_twister_engine(Sseq& q); void seed(result_type value = default_seed); template<class Sseq> void seed(Sseq& q); // generating functions result_type operator()(); void discard(unsigned long long z); };
The following relations shall hold: 0 < m, m <= n, 2u < w, r <= w, u <= w, s <= w, t <= w, l <= w, w <= numeric_­limits<UIntType>​::​digits, a <= (1u<<w) - 1u, b <= (1u<<w) - 1u, c <= (1u<<w) - 1u, d <= (1u<<w) - 1u, and f <= (1u<<w) - 1u.
The textual representation of x consists of the values of , in that order.
explicit mersenne_twister_engine(result_type value);
Effects: Sets to .
Then, iteratively for , sets to
Complexity: .
template<class Sseq> explicit mersenne_twister_engine(Sseq& q);
Effects: With and a an array (or equivalent) of length , invokes q.generate(, ) and then, iteratively for , sets to .
Finally, if the most significant bits of are zero, and if each of the other resulting is 0, changes to .
The name of this engine refers, in part, to a property of its period: For properly-selected values of the parameters, the period is closely related to a large Mersenne prime number.
 

26.6.4.4 Class template subtract_­with_­carry_­engine [rand.eng.sub]

A subtract_­with_­carry_­engine random number engine produces unsigned integer random numbers.
The state x of a subtract_­with_­carry_­engine object x is of size , and consists of a sequence X of r integer values ; all subscripts applied to X are to be taken modulo r.
The state x additionally consists of an integer c (known as the carry) whose value is either 0 or 1.
The state transition is performed as follows:
  • Let .
  • Set to .
    Set c to 1 if , otherwise set c to 0.
[Note 1:
This algorithm corresponds to a modular linear function of the form , where b is of the form and .
— end note]
The generation algorithm is given by , where y is the value produced as a result of advancing the engine's state as described above.
template<class UIntType, size_t w, size_t s, size_t r> class subtract_with_carry_engine { public: // types using result_type = UIntType; // engine characteristics static constexpr size_t word_size = w; static constexpr size_t short_lag = s; static constexpr size_t long_lag = r; static constexpr result_type min() { return 0; } static constexpr result_type max() { return ; } static constexpr result_type default_seed = 19780503u; // constructors and seeding functions subtract_with_carry_engine() : subtract_with_carry_engine(default_seed) {} explicit subtract_with_carry_engine(result_type value); template<class Sseq> explicit subtract_with_carry_engine(Sseq& q); void seed(result_type value = default_seed); template<class Sseq> void seed(Sseq& q); // generating functions result_type operator()(); void discard(unsigned long long z); };
The following relations shall hold: 0u < s, s < r, 0 < w, and w <= numeric_­limits<UIntType>​::​digits.
The textual representation consists of the values of , in that order, followed by c.
explicit subtract_with_carry_engine(result_type value);
Effects: Sets the values of , in that order, as specified below.
If is then 0, sets c to 1; otherwise sets c to 0.
To set the values , first construct e, a linear_­congruential_­engine object, as if by the following definition: linear_congruential_engine<result_type, 40014u,0u,2147483563u> e(value == 0u ? default_seed : value);
Then, to set each , obtain new values from successive invocations of e taken modulo .
Set to .
Complexity: Exactly invocations of e.
template<class Sseq> explicit subtract_with_carry_engine(Sseq& q);
Effects: With and a an array (or equivalent) of length , invokes q.generate(, ) and then, iteratively for , sets to .
If is then 0, sets c to 1; otherwise sets c to 0.

26.6.5 Random number engine adaptor class templates [rand.adapt]

26.6.5.1 In general [rand.adapt.general]

Each type instantiated from a class template specified in this subclause [rand.adapt] meets the requirements of a random number engine adaptor type.
Except where specified otherwise, the complexity of each function specified in this subclause [rand.adapt] is constant.
Except where specified otherwise, no function described in this subclause [rand.adapt] throws an exception.
Every function described in this subclause [rand.adapt] that has a function parameter q of type Sseq& for a template type parameter named Sseq that is different from type seed_­seq throws what and when the invocation of q.generate throws.
Descriptions are provided in this subclause [rand.adapt] only for adaptor operations that are not described in subclause [rand.req.adapt] or for operations where there is additional semantic information.
In particular, declarations for copy constructors, for copy assignment operators, for streaming operators, and for equality and inequality operators are not shown in the synopses.
Each template specified in this subclause [rand.adapt] requires one or more relationships, involving the value(s) of its non-type template parameter(s), to hold.
A program instantiating any of these templates is ill-formed if any such required relationship fails to hold.

26.6.5.2 Class template discard_­block_­engine [rand.adapt.disc]

A discard_­block_­engine random number engine adaptor produces random numbers selected from those produced by some base engine e.
The state x of a discard_­block_­engine engine adaptor object x consists of the state e of its base engine e and an additional integer n.
The size of the state is the size of e's state plus 1.
The transition algorithm discards all but values from each block of values delivered by e.
The state transition is performed as follows: If , advance the state of e from e to e and set n to 0.
In any case, then increment n and advance e's then-current state e to e.
The generation algorithm yields the value returned by the last invocation of e() while advancing e's state as described above.
template<class Engine, size_t p, size_t r> class discard_block_engine { public: // types using result_type = typename Engine::result_type; // engine characteristics static constexpr size_t block_size = p; static constexpr size_t used_block = r; static constexpr result_type min() { return Engine::min(); } static constexpr result_type max() { return Engine::max(); } // constructors and seeding functions discard_block_engine(); explicit discard_block_engine(const Engine& e); explicit discard_block_engine(Engine&& e); explicit discard_block_engine(result_type s); template<class Sseq> explicit discard_block_engine(Sseq& q); void seed(); void seed(result_type s); template<class Sseq> void seed(Sseq& q); // generating functions result_type operator()(); void discard(unsigned long long z); // property functions const Engine& base() const noexcept { return e; }; private: Engine e; // exposition only int n; // exposition only };
The following relations shall hold: 0 < r and r <= p.
The textual representation consists of the textual representation of e followed by the value of n.
In addition to its behavior pursuant to subclause [rand.req.adapt], each constructor that is not a copy constructor sets n to 0.

26.6.5.3 Class template independent_­bits_­engine [rand.adapt.ibits]

An independent_­bits_­engine random number engine adaptor combines random numbers that are produced by some base engine e, so as to produce random numbers with a specified number of bits w.
The state x of an independent_­bits_­engine engine adaptor object x consists of the state e of its base engine e; the size of the state is the size of e's state.
The transition and generation algorithms are described in terms of the following integral constants:
  • Let and .
  • With n as determined below, let , , , and .
  • Let if and only if the relation holds as a result.
    Otherwise let .
[Note 1:
The relation always holds.
— end note]
The transition algorithm is carried out by invoking e() as often as needed to obtain values less than and values less than .
The generation algorithm uses the values produced while advancing the state as described above to yield a quantity S obtained as if by the following algorithm: S = 0; for (k = 0; ; k += 1) { do u = e() - e.min(); while (); S = ; } for (k = ; ; k += 1) { do u = e() - e.min(); while (); S = ; }
template<class Engine, size_t w, class UIntType> class independent_bits_engine { public: // types using result_type = UIntType; // engine characteristics static constexpr result_type min() { return 0; } static constexpr result_type max() { return ; } // constructors and seeding functions independent_bits_engine(); explicit independent_bits_engine(const Engine& e); explicit independent_bits_engine(Engine&& e); explicit independent_bits_engine(result_type s); template<class Sseq> explicit independent_bits_engine(Sseq& q); void seed(); void seed(result_type s); template<class Sseq> void seed(Sseq& q); // generating functions result_type operator()(); void discard(unsigned long long z); // property functions const Engine& base() const noexcept { return e; }; private: Engine e; // exposition only };
The following relations shall hold: 0 < w and w <= numeric_­limits<result_­type>​::​digits.
The textual representation consists of the textual representation of e.

26.6.5.4 Class template shuffle_­order_­engine [rand.adapt.shuf]

A shuffle_­order_­engine random number engine adaptor produces the same random numbers that are produced by some base engine e, but delivers them in a different sequence.
The state x of a shuffle_­order_­engine engine adaptor object x consists of the state e of its base engine e, an additional value Y of the type delivered by e, and an additional sequence V of k values also of the type delivered by e.
The size of the state is the size of e's state plus .
The transition algorithm permutes the values produced by e.
The state transition is performed as follows:
  • Calculate an integer .
  • Set Y to and then set to e().
The generation algorithm yields the last value of Y produced while advancing e's state as described above.
template<class Engine, size_t k> class shuffle_order_engine { public: // types using result_type = typename Engine::result_type; // engine characteristics static constexpr size_t table_size = k; static constexpr result_type min() { return Engine::min(); } static constexpr result_type max() { return Engine::max(); } // constructors and seeding functions shuffle_order_engine(); explicit shuffle_order_engine(const Engine& e); explicit shuffle_order_engine(Engine&& e); explicit shuffle_order_engine(result_type s); template<class Sseq> explicit shuffle_order_engine(Sseq& q); void seed(); void seed(result_type s); template<class Sseq> void seed(Sseq& q); // generating functions result_type operator()(); void discard(unsigned long long z); // property functions const Engine& base() const noexcept { return e; }; private: Engine e; // exposition only result_type V[k]; // exposition only result_type Y; // exposition only };
The following relation shall hold: 0 < k.
The textual representation consists of the textual representation of e, followed by the k values of V, followed by the value of Y.
In addition to its behavior pursuant to subclause [rand.req.adapt], each constructor that is not a copy constructor initializes and Y, in that order, with values returned by successive invocations of e().

26.6.6 Engines and engine adaptors with predefined parameters [rand.predef]

using minstd_rand0 = linear_congruential_engine<uint_fast32_t, 16'807, 0, 2'147'483'647>;
Required behavior: The consecutive invocation of a default-constructed object of type minstd_­rand0 produces the value 1043618065.
using minstd_rand = linear_congruential_engine<uint_fast32_t, 48'271, 0, 2'147'483'647>;
Required behavior: The consecutive invocation of a default-constructed object of type minstd_­rand produces the value 399268537.
using mt19937 = mersenne_twister_engine<uint_fast32_t, 32, 624, 397, 31, 0x9908'b0df, 11, 0xffff'ffff, 7, 0x9d2c'5680, 15, 0xefc6'0000, 18, 1'812'433'253>;
Required behavior: The consecutive invocation of a default-constructed object of type mt19937 produces the value 4123659995.
using mt19937_64 = mersenne_twister_engine<uint_fast64_t, 64, 312, 156, 31, 0xb502'6f5a'a966'19e9, 29, 0x5555'5555'5555'5555, 17, 0x71d6'7fff'eda6'0000, 37, 0xfff7'eee0'0000'0000, 43, 6'364'136'223'846'793'005>;
Required behavior: The consecutive invocation of a default-constructed object of type mt19937_­64 produces the value 9981545732273789042.
using ranlux24_base = subtract_with_carry_engine<uint_fast32_t, 24, 10, 24>;
Required behavior: The consecutive invocation of a default-constructed object of type ranlux24_­base produces the value 7937952.
using ranlux48_base = subtract_with_carry_engine<uint_fast64_t, 48, 5, 12>;
Required behavior: The consecutive invocation of a default-constructed object of type ranlux48_­base produces the value 61839128582725.
using ranlux24 = discard_block_engine<ranlux24_base, 223, 23>;
Required behavior: The consecutive invocation of a default-constructed object of type ranlux24 produces the value 9901578.
using ranlux48 = discard_block_engine<ranlux48_base, 389, 11>;
Required behavior: The consecutive invocation of a default-constructed object of type ranlux48 produces the value 249142670248501.
using knuth_b = shuffle_order_engine<minstd_rand0,256>;
Required behavior: The consecutive invocation of a default-constructed object of type knuth_­b produces the value 1112339016.
using default_random_engine = implementation-defined;
Remarks: The choice of engine type named by this typedef is implementation-defined.
[Note 1:
The implementation can select this type on the basis of performance, size, quality, or any combination of such factors, so as to provide at least acceptable engine behavior for relatively casual, inexpert, and/or lightweight use.
Because different implementations can select different underlying engine types, code that uses this typedef need not generate identical sequences across implementations.
— end note]

26.6.7 Class random_­device [rand.device]

A random_­device uniform random bit generator produces nondeterministic random numbers.
If implementation limitations prevent generating nondeterministic random numbers, the implementation may employ a random number engine.
class random_device { public: // types using result_type = unsigned int; // generator characteristics static constexpr result_type min() { return numeric_limits<result_type>::min(); } static constexpr result_type max() { return numeric_limits<result_type>::max(); } // constructors random_device() : random_device(implementation-defined) {} explicit random_device(const string& token); // generating functions result_type operator()(); // property functions double entropy() const noexcept; // no copy functions random_device(const random_device&) = delete; void operator=(const random_device&) = delete; };
explicit random_device(const string& token);
Throws: A value of an implementation-defined type derived from exception if the random_­device could not be initialized.
Remarks: The semantics of the token parameter and the token value used by the default constructor are implementation-defined.250
double entropy() const noexcept;
Returns: If the implementation employs a random number engine, returns 0.0.
Otherwise, returns an entropy estimate251 for the random numbers returned by operator(), in the range min() to .
result_type operator()();
Returns: A nondeterministic random value, uniformly distributed between min() and max() (inclusive).
It is implementation-defined how these values are generated.
Throws: A value of an implementation-defined type derived from exception if a random number could not be obtained.
The parameter is intended to allow an implementation to differentiate between different sources of randomness.
 
If a device has n states whose respective probabilities are , the device entropy S is defined as
.
 

26.6.8 Utilities [rand.util]

26.6.8.1 Class seed_­seq [rand.util.seedseq]

class seed_seq { public: // types using result_type = uint_least32_t; // constructors seed_seq(); template<class T> seed_seq(initializer_list<T> il); template<class InputIterator> seed_seq(InputIterator begin, InputIterator end); // generating functions template<class RandomAccessIterator> void generate(RandomAccessIterator begin, RandomAccessIterator end); // property functions size_t size() const noexcept; template<class OutputIterator> void param(OutputIterator dest) const; // no copy functions seed_seq(const seed_seq&) = delete; void operator=(const seed_seq&) = delete; private: vector<result_type> v; // exposition only };
seed_seq();
Postconditions: v.empty() is true.
Throws: Nothing.
template<class T> seed_seq(initializer_list<T> il);
Mandates: T is an integer type.
Effects: Same as seed_­seq(il.begin(), il.end()).
template<class InputIterator> seed_seq(InputIterator begin, InputIterator end);
Mandates: iterator_­traits<InputIterator>​::​value_­type is an integer type.
Preconditions: InputIterator meets the Cpp17InputIterator requirements ([input.iterators]).
Effects: Initializes v by the following algorithm: for (InputIterator s = begin; s != end; ++s) v.push_back((*s));
template<class RandomAccessIterator> void generate(RandomAccessIterator begin, RandomAccessIterator end);
Mandates: iterator_­traits<RandomAccessIterator>​::​​value_­type is an unsigned integer type capable of accommodating 32-bit quantities.
Preconditions: RandomAccessIterator meets the Cpp17RandomAccessIterator requirements ([random.access.iterators]) and the requirements of a mutable iterator.
Effects: Does nothing if begin == end.
Otherwise, with and , fills the supplied range according to the following algorithm in which each operation is to be carried out modulo , each indexing operator applied to begin is to be taken modulo n, and T(x) is defined as :
  • By way of initialization, set each element of the range to the value 0x8b8b8b8b.
    Additionally, for use in subsequent steps, let and let , where
  • With m as the larger of and n, transform the elements of the range: iteratively for , calculate values
    and, in order, increment begin[] by , increment begin[] by , and set begin[k] to .
  • Transform the elements of the range again, beginning where the previous step ended: iteratively for , calculate values
    and, in order, update begin[] by xoring it with , update begin[] by xoring it with , and set begin[k] to .
Throws: What and when RandomAccessIterator operations of begin and end throw.
size_t size() const noexcept;
Returns: The number of 32-bit units that would be returned by a call to param().
Complexity: Constant time.
template<class OutputIterator> void param(OutputIterator dest) const;
Mandates: Values of type result_­type are writable ([iterator.requirements.general]) to dest.
Preconditions: OutputIterator meets the Cpp17OutputIterator requirements ([output.iterators]).
Effects: Copies the sequence of prepared 32-bit units to the given destination, as if by executing the following statement: copy(v.begin(), v.end(), dest);
Throws: What and when OutputIterator operations of dest throw.

26.6.8.2 Function template generate_­canonical [rand.util.canonical]

template<class RealType, size_t bits, class URBG> RealType generate_canonical(URBG& g);
Complexity: Exactly invocations of g, where b252 is the lesser of numeric_­limits<RealType>​::​digits and bits, and R is the value of .
Effects: Invokes g() k times to obtain values , respectively.
Calculates a quantity
using arithmetic of type RealType.
Returns: .
[Note 1:
.
— end note]
Throws: What and when g throws.
[Note 2:
If the values produced by g are uniformly distributed, the instantiation's results are distributed as uniformly as possible.
Obtaining a value in this way can be a useful step in the process of transforming a value generated by a uniform random bit generator into a value that can be delivered by a random number distribution.
— end note]
b is introduced to avoid any attempt to produce more bits of randomness than can be held in RealType.
 

26.6.9 Random number distribution class templates [rand.dist]

26.6.9.1 In general [rand.dist.general]

Each type instantiated from a class template specified in this subclause [rand.dist] meets the requirements of a random number distribution type.
Descriptions are provided in this subclause [rand.dist] only for distribution operations that are not described in [rand.req.dist] or for operations where there is additional semantic information.
In particular, declarations for copy constructors, for copy assignment operators, for streaming operators, and for equality and inequality operators are not shown in the synopses.
The algorithms for producing each of the specified distributions are implementation-defined.
The value of each probability density function p(z) and of each discrete probability function specified in this subclause is 0 everywhere outside its stated domain.

26.6.9.2 Uniform distributions [rand.dist.uni]

26.6.9.2.1 Class template uniform_­int_­distribution [rand.dist.uni.int]

A uniform_­int_­distribution random number distribution produces random integers i, , distributed according to the constant discrete probability function
template<class IntType = int> class uniform_int_distribution { public: // types using result_type = IntType; using param_type = unspecified; // constructors and reset functions uniform_int_distribution() : uniform_int_distribution(0) {} explicit uniform_int_distribution(IntType a, IntType b = numeric_limits<IntType>::max()); explicit uniform_int_distribution(const param_type& parm); void reset(); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions result_type a() const; result_type b() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; };
explicit uniform_int_distribution(IntType a, IntType b = numeric_limits<IntType>::max());
Preconditions: .
Remarks: a and b correspond to the respective parameters of the distribution.
result_type a() const;
Returns: The value of the a parameter with which the object was constructed.
result_type b() const;
Returns: The value of the b parameter with which the object was constructed.

26.6.9.2.2 Class template uniform_­real_­distribution [rand.dist.uni.real]

A uniform_­real_­distribution random number distribution produces random numbers x, , distributed according to the constant probability density function
[Note 1:
This implies that is undefined when a == b.
— end note]
template<class RealType = double> class uniform_real_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructors and reset functions uniform_real_distribution() : uniform_real_distribution(0.0) {} explicit uniform_real_distribution(RealType a, RealType b = 1.0); explicit uniform_real_distribution(const param_type& parm); void reset(); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions result_type a() const; result_type b() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; };
explicit uniform_real_distribution(RealType a, RealType b = 1.0);
Preconditions: and .
Remarks: a and b correspond to the respective parameters of the distribution.
result_type a() const;
Returns: The value of the a parameter with which the object was constructed.
result_type b() const;
Returns: The value of the b parameter with which the object was constructed.

26.6.9.3 Bernoulli distributions [rand.dist.bern]

26.6.9.3.1 Class bernoulli_­distribution [rand.dist.bern.bernoulli]

A bernoulli_­distribution random number distribution produces bool values b distributed according to the discrete probability function
class bernoulli_distribution { public: // types using result_type = bool; using param_type = unspecified; // constructors and reset functions bernoulli_distribution() : bernoulli_distribution(0.5) {} explicit bernoulli_distribution(double p); explicit bernoulli_distribution(const param_type& parm); void reset(); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions double p() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; };
explicit bernoulli_distribution(double p);
Preconditions: .
Remarks: p corresponds to the parameter of the distribution.
double p() const;
Returns: The value of the p parameter with which the object was constructed.

26.6.9.3.2 Class template binomial_­distribution [rand.dist.bern.bin]

A binomial_­distribution random number distribution produces integer values distributed according to the discrete probability function
template<class IntType = int> class binomial_distribution { public: // types using result_type = IntType; using param_type = unspecified; // constructors and reset functions binomial_distribution() : binomial_distribution(1) {} explicit binomial_distribution(IntType t, double p = 0.5); explicit binomial_distribution(const param_type& parm); void reset(); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions IntType t() const; double p() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; };
explicit binomial_distribution(IntType t, double p = 0.5);
Preconditions: and .
Remarks: t and p correspond to the respective parameters of the distribution.
IntType t() const;
Returns: The value of the t parameter with which the object was constructed.
double p() const;
Returns: The value of the p parameter with which the object was constructed.

26.6.9.3.3 Class template geometric_­distribution [rand.dist.bern.geo]

A geometric_­distribution random number distribution produces integer values distributed according to the discrete probability function
template<class IntType = int> class geometric_distribution { public: // types using result_type = IntType; using param_type = unspecified; // constructors and reset functions geometric_distribution() : geometric_distribution(0.5) {} explicit geometric_distribution(double p); explicit geometric_distribution(const param_type& parm); void reset(); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions double p() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; };
explicit geometric_distribution(double p);
Preconditions: .
Remarks: p corresponds to the parameter of the distribution.
double p() const;
Returns: The value of the p parameter with which the object was constructed.

26.6.9.3.4 Class template negative_­binomial_­distribution [rand.dist.bern.negbin]

A negative_­binomial_­distribution random number distribution produces random integers distributed according to the discrete probability function
[Note 1:
This implies that is undefined when p == 1.
— end note]
template<class IntType = int> class negative_binomial_distribution { public: // types using result_type = IntType; using param_type = unspecified; // constructor and reset functions negative_binomial_distribution() : negative_binomial_distribution(1) {} explicit negative_binomial_distribution(IntType k, double p = 0.5); explicit negative_binomial_distribution(const param_type& parm); void reset(); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions IntType k() const; double p() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; };
explicit negative_binomial_distribution(IntType k, double p = 0.5);
Preconditions: and .
Remarks: k and p correspond to the respective parameters of the distribution.
IntType k() const;
Returns: The value of the k parameter with which the object was constructed.
double p() const;
Returns: The value of the p parameter with which the object was constructed.

26.6.9.4 Poisson distributions [rand.dist.pois]

26.6.9.4.1 Class template poisson_­distribution [rand.dist.pois.poisson]

A poisson_­distribution random number distribution produces integer values distributed according to the discrete probability function
The distribution parameter μ is also known as this distribution's mean.
template<class IntType = int> class poisson_distribution { public: // types using result_type = IntType; using param_type = unspecified; // constructors and reset functions poisson_distribution() : poisson_distribution(1.0) {} explicit poisson_distribution(double mean); explicit poisson_distribution(const param_type& parm); void reset(); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions double mean() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; };
explicit poisson_distribution(double mean);
Preconditions: .
Remarks: mean corresponds to the parameter of the distribution.
double mean() const;
Returns: The value of the mean parameter with which the object was constructed.

26.6.9.4.2 Class template exponential_­distribution [rand.dist.pois.exp]

An exponential_­distribution random number distribution produces random numbers distributed according to the probability density function
template<class RealType = double> class exponential_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructors and reset functions exponential_distribution() : exponential_distribution(1.0) {} explicit exponential_distribution(RealType lambda); explicit exponential_distribution(const param_type& parm); void reset(); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions RealType lambda() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; };
explicit exponential_distribution(RealType lambda);
Preconditions: .
Remarks: lambda corresponds to the parameter of the distribution.
RealType lambda() const;
Returns: The value of the lambda parameter with which the object was constructed.

26.6.9.4.3 Class template gamma_­distribution [rand.dist.pois.gamma]

A gamma_­distribution random number distribution produces random numbers distributed according to the probability density function
template<class RealType = double> class gamma_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructors and reset functions gamma_distribution() : gamma_distribution(1.0) {} explicit gamma_distribution(RealType alpha, RealType beta = 1.0); explicit gamma_distribution(const param_type& parm); void reset(); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions RealType alpha() const; RealType beta() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; };
explicit gamma_distribution(RealType alpha, RealType beta = 1.0);
Preconditions: and .
Remarks: alpha and beta correspond to the parameters of the distribution.
RealType alpha() const;
Returns: The value of the alpha parameter with which the object was constructed.
RealType beta() const;
Returns: The value of the beta parameter with which the object was constructed.

26.6.9.4.4 Class template weibull_­distribution [rand.dist.pois.weibull]

A weibull_­distribution random number distribution produces random numbers distributed according to the probability density function
template<class RealType = double> class weibull_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructor and reset functions weibull_distribution() : weibull_distribution(1.0) {} explicit weibull_distribution(RealType a, RealType b = 1.0); explicit weibull_distribution(const param_type& parm); void reset(); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions RealType a() const; RealType b() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; };
explicit weibull_distribution(RealType a, RealType b = 1.0);
Preconditions: and .
Remarks: a and b correspond to the respective parameters of the distribution.
RealType a() const;
Returns: The value of the a parameter with which the object was constructed.
RealType b() const;
Returns: The value of the b parameter with which the object was constructed.

26.6.9.4.5 Class template extreme_­value_­distribution [rand.dist.pois.extreme]

An extreme_­value_­distribution random number distribution produces random numbers x distributed according to the probability density function253
template<class RealType = double> class extreme_value_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructor and reset functions extreme_value_distribution() : extreme_value_distribution(0.0) {} explicit extreme_value_distribution(RealType a, RealType b = 1.0); explicit extreme_value_distribution(const param_type& parm); void reset(); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions RealType a() const; RealType b() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; };
explicit extreme_value_distribution(RealType a, RealType b = 1.0);
Preconditions: .
Remarks: a and b correspond to the respective parameters of the distribution.
RealType a() const;
Returns: The value of the a parameter with which the object was constructed.
RealType b() const;
Returns: The value of the b parameter with which the object was constructed.
The distribution corresponding to this probability density function is also known (with a possible change of variable) as the Gumbel Type I, the log-Weibull, or the Fisher-Tippett Type I distribution.
 

26.6.9.5 Normal distributions [rand.dist.norm]

26.6.9.5.1 Class template normal_­distribution [rand.dist.norm.normal]

A normal_­distribution random number distribution produces random numbers x distributed according to the probability density function
The distribution parameters μ and σ are also known as this distribution's mean and standard deviation.
template<class RealType = double> class normal_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructors and reset functions normal_distribution() : normal_distribution(0.0) {} explicit normal_distribution(RealType mean, RealType stddev = 1.0); explicit normal_distribution(const param_type& parm); void reset(); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions RealType mean() const; RealType stddev() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; };
explicit normal_distribution(RealType mean, RealType stddev = 1.0);
Preconditions: .
Remarks: mean and stddev correspond to the respective parameters of the distribution.
RealType mean() const;
Returns: The value of the mean parameter with which the object was constructed.
RealType stddev() const;
Returns: The value of the stddev parameter with which the object was constructed.

26.6.9.5.2 Class template lognormal_­distribution [rand.dist.norm.lognormal]

A lognormal_­distribution random number distribution produces random numbers distributed according to the probability density function
template<class RealType = double> class lognormal_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructor and reset functions lognormal_distribution() : lognormal_distribution(0.0) {} explicit lognormal_distribution(RealType m, RealType s = 1.0); explicit lognormal_distribution(const param_type& parm); void reset(); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions RealType m() const; RealType s() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; };
explicit lognormal_distribution(RealType m, RealType s = 1.0);
Preconditions: .
Remarks: m and s correspond to the respective parameters of the distribution.
RealType m() const;
Returns: The value of the m parameter with which the object was constructed.
RealType s() const;
Returns: The value of the s parameter with which the object was constructed.

26.6.9.5.3 Class template chi_­squared_­distribution [rand.dist.norm.chisq]

A chi_­squared_­distribution random number distribution produces random numbers distributed according to the probability density function