Working Draft, Standard for Programming Language C++ (N4713, 2017 year)

Table 102 — Seed sequence requirements (continued)

Expression

Return type

Pre/post-condition

Complexity

S(il)

Same as S(il.begin(),

same as

il.end()).

S(il.begin(),

il.end())

q.generate(rb,re)

void

Does nothing if rb == re.

O(re − rb)

Otherwise, fills the supplied

sequence [rb, re) 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

constant

would be copied by a call to

r.param.

r.param(ob)

void

Copies to the given destination

O(r.size())

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.

29.6.1.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: The

degree to which g’s results approximate the ideal is often determined statistically.

— end note ]

A class G satisfies the requirements of a uniform random bit generator if the expressions shown in Table 103

are valid and have the indicated semantics, and if G also satisfies all other requirements of this subclause

29.6.1.3. In that Table and throughout this subclause:

a) T is the type named by G’s associated result_type, and

b) g is a value of G.

Table 103 — Uniform random bit generator requirements

Expression

Return type

Pre/post-condition

Complexity

G::result_type

T is an unsigned integer

compile-time

type (6.7.1).

g()

Returns a value in the closed

amortized

interval [G::min(), G::max()].

constant

G::min()

Denotes the least value

compile-time

potentially returned by

operator().

G::max()

Denotes the greatest value

compile-time

potentially returned by

operator().

The following relation shall hold: G::min() < G::max().

29.6.1.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.

§ 29.6.1.4

952

At any given time, e has a state e_i for some integer i ≥ 0. 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) the size of E’s state in multiples of the size of result_type, given as an integral constant expression;

b) the transition algorithm TA by which e’s state e_i is advanced to its successor state e_i+1; and

c) the generation algorithm GA by which an engine’s state is mapped to a value of type result_type.

A class E that satisfies the requirements of a uniform random bit generator (29.6.1.3) also satisfies the

requirements of a random number engine if the expressions shown in Table 104 are valid and have the

indicated semantics, and if E also satisfies all other requirements of this subclause 29.6.1.4. In that Table and

throughout this subclause:

a) T is the type named by E’s associated result_type;

b) e is a value of E, v is an lvalue of E, x and y are (possibly const) values of E;

c) s is a value of T;

d) q is an lvalue satisfying the requirements of a seed sequence (29.6.1.2);

e) z is a value of type unsigned long long;

f) os is an lvalue of the type of some class template specialization basic_ostream<charT, traits>; and

g) is is an lvalue of the type of some class template specialization basic_istream<charT, traits>;

where charT and traits are constrained according to Clause 24 and Clause 30.

Table 104 — Random number engine requirements

Expression

Return type

Pre/post-condition

Complexity

E()

Creates an engine with the same

O(size of state)

initial state as all other

default-constructed engines of

type E.

E(x)

Creates an engine that compares

O(size of state)

equal to x.

E(s)

Creates an engine with initial

O(size of state)

state determined by s.

E(q)²⁷¹

Creates an engine with an initial

same as

state that depends on a

complexity of

sequence produced by one call

q.generate

to 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()

Advances e’s state e_i to e_i+1

per Table 103

= TA(e_i) and returns GA(e_i).

e.discard(z)²⁷²

void

Advances e’s state e_i to e_i+z by

no worse than

any means equivalent to z

the complexity

consecutive calls e().

of z consecutive

calls e()

271) This constructor (as well as the subsequent corresponding seed() function) may be particularly useful to applications

requiring a large number of independent random sequences.

272) 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().

§ 29.6.1.4

953

Expression

Return type

Pre/post-condition

Complexity

x == y

bool

This operator is an equivalence

O(size of state)

relation. With S_x and S_y as the

infinite sequences of values that

would be generated by repeated

future calls to x() and y(),

respectively, returns true if

S_x = S_y; else returns false.

x != y

bool

!(x == y).

O(size of state)

reference to the type of

With os.fmtflags set to ios_-

O(size of state)

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.

reference to the type of

With is.fmtflags set to

O(size of state)

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::failbit)

(which may throw

ios::failure (30.5.5.4)). 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.

Requires: 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 requirements of

CopyConstructible (Table 24) and CopyAssignable (Table

26) types.

These operations shall each be of complexity no worse than O(size of state).

29.6.1.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.

§ 29.6.1.5

954

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 satisfy the following additional requirements:

a) The complexity of each function shall not exceed the complexity of the corresponding function applied

to the base engine.

b) 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.

c) Copying A’s state (e.g., during copy construction or copy assignment) shall include copying the state of

the base engine of A.

d) The textual representation of A shall include the textual representation of its base engine.

29.6.1.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 P(z_i). A distribution’s specification identifies its

associated probability function p(z) or P (z_i).

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, p(z |a,b) or P(z_i |a,b), to name specific parameters, or by writing, for example, p(z |{p}) or

P (z_i | {p}), to denote a distribution’s parameters p taken as a whole.

A class D satisfies the requirements of a random number distribution if the expressions shown in Table 105 are

valid and have the indicated semantics, and if D and its associated types also satisfy all other requirements of

this subclause 29.6.1.6. In that Table and throughout this subclause,

a) T is the type named by D’s associated result_type;

b) P is the type named by D’s associated param_type;

c) d is a value of D, and x and y are (possibly const) values of D;

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;

e) p is a (possibly const) value of P;

f) g, g1, and g2 are lvalues of a type satisfying the requirements of a uniform random bit generator

(29.6.1.3);

g) os is an lvalue of the type of some class template specialization basic_ostream<charT, traits>; and

§ 29.6.1.6

955

h) is is an lvalue of the type of some class template specialization basic_istream<charT, traits>;

where charT and traits are constrained according to Clause 24 and Clause 30.

Table 105 — Random number distribution requirements

Expression

Return type

Pre/post-condition

Complexity

D::result_type

T is an arithmetic type (6.7.1).

compile-time

D::param_type

compile-time

D()

Creates a distribution whose

constant

behavior is indistinguishable

from that of any other newly

default-constructed distribution

of type D.

D(p)

Creates a distribution whose

same as p’s

behavior is indistinguishable

construction

from that of a distribution

newly constructed directly from

the values used to construct p.

d.reset()

void

Subsequent uses of d do not

constant

depend on values produced by

any engine prior to invoking

reset.

x.param()

Returns a value p such that

no worse than

D(p).param() == p.

the complexity

of D(p)

d.param(p)

void

Postconditions: d.param() ==

no worse than

the complexity

of D(p)

d(g)

With p = d.param(), the

amortized

sequence of numbers returned by

constant

successive invocations with the

number of

same object g is randomly

invocations of g

distributed according to the

associated p(z | {p}) or

P (z_i | {p}) function.

d(g,p)

The sequence of numbers

amortized

returned by successive

constant

invocations with the same

number of

objects g and p is randomly

invocations of g

distributed according to the

associated p(z | {p}) or

P (z_i | {p}) function.

x.min()

Returns glb.

constant

x.max()

Returns lub.

constant

x == y

bool

This operator is an equivalence

constant

relation. Returns true if

x.param() == y.param() and

S₁ = S₂, where S₁ and S₂ 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.

x != y

bool

!(x == y).

same as x == y.

§ 29.6.1.6

956

Expression

Return type

Pre/post-condition

Complexity

os << x

reference to the type of

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

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::failbit)

(which may throw

ios::failure (30.5.5.4)).

Requires: 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 satisfy the requirements of CopyConstructible (Table 24) and CopyAssignable (Table 26) types.

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

29.6, declarations of D::param_type are in the form of typedefs for convenience of exposition only.

P shall satisfy the requirements of CopyConstructible (Table 24), CopyAssignable (Table 26), and

EqualityComparable (Table 20) types.

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;

29.6.2

Header <random> synopsis

[rand.synopsis]

#include <initializer_list>

namespace std {

// 29.6.3.1, class template linear_congruential_engine

template<class UIntType, UIntType a, UIntType c, UIntType m>

class linear_congruential_engine;

§ 29.6.2

957

// 29.6.3.2, class template mersenne_twister_engine

template<class UIntType, size_t w, size_t n, size_t m, size_t

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;

// 29.6.3.3, class template subtract_with_carry_engine

template<class UIntType, size_t w, size_t s, size_t r>

class subtract_with_carry_engine;

// 29.6.4.2, class template discard_block_engine

template<class Engine, size_t p, size_t r>

class discard_block_engine;

// 29.6.4.3, class template independent_bits_engine

template<class Engine, size_t w, class UIntType>

class independent_bits_engine;

// 29.6.4.4, class template shuffle_order_engine

template<class Engine, size_t k>

class shuffle_order_engine;

// 29.6.5, 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 ;

// 29.6.6, class random_device

class random_device;

// 29.6.7.1, class seed_seq

class seed_seq;

// 29.6.7.2, function template generate_canonical

template<class RealType, size_t bits, class URBG>

RealType generate_canonical(URBG& g);

// 29.6.8.2.1, class template uniform_int_distribution

template<class IntType = int>

class uniform_int_distribution;

// 29.6.8.2.2, class template uniform_real_distribution

template<class RealType = double>

class uniform_real_distribution;

// 29.6.8.3.1, class bernoulli_distribution

class bernoulli_distribution;

// 29.6.8.3.2, class template binomial_distribution

template<class IntType = int>

class binomial_distribution;

// 29.6.8.3.3, class template geometric_distribution

template<class IntType = int>

class geometric_distribution;

29.6.2

958

// 29.6.8.3.4, class template negative_binomial_distribution

template<class IntType = int>

class negative_binomial_distribution;

// 29.6.8.4.1, class template poisson_distribution

template<class IntType = int>

class poisson_distribution;

// 29.6.8.4.2, class template exponential_distribution

template<class RealType = double>

class exponential_distribution;

// 29.6.8.4.3, class template gamma_distribution

template<class RealType = double>

class gamma_distribution;

// 29.6.8.4.4, class template weibull_distribution

template<class RealType = double>

class weibull_distribution;

// 29.6.8.4.5, class template extreme_value_distribution

template<class RealType = double>

class extreme_value_distribution;

// 29.6.8.5.1, class template normal_distribution

template<class RealType = double>

class normal_distribution;

// 29.6.8.5.2, class template lognormal_distribution

template<class RealType = double>

class lognormal_distribution;

// 29.6.8.5.3, class template chi_squared_distribution

template<class RealType = double>

class chi_squared_distribution;

// 29.6.8.5.4, class template cauchy_distribution

template<class RealType = double>

class cauchy_distribution;

// 29.6.8.5.5, class template fisher_f_distribution

template<class RealType = double>

class fisher_f_distribution;

// 29.6.8.5.6, class template student_t_distribution

template<class RealType = double>

class student_t_distribution;

// 29.6.8.6.1, class template discrete_distribution

template<class IntType = int>

class discrete_distribution;

// 29.6.8.6.2, class template piecewise_constant_distribution

template<class RealType = double>

class piecewise_constant_distribution;

// 29.6.8.6.3, class template piecewise_linear_distribution

template<class RealType = double>

class piecewise_linear_distribution;

}

§ 29.6.2

959

29.6.3

Random number engine class templates

[rand.eng]

Each type instantiated from a class template specified in this subclause 29.6.3 satisfies the requirements of a

random number engine (29.6.1.4) type.

Except where specified otherwise, the complexity of each function specified in this subclause 29.6.3 is constant.

Except where specified otherwise, no function described in this subclause 29.6.3 throws an exception.

Every function described in this subclause 29.6.3 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 29.6.3 only for engine operations that are not described in

29.6.1.4 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 29.6.3 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 this subclause

(29.6.3) and in subclause 29.6.4:

(7.1)

—

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;

(7.2)

—

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.

29.6.3.1

Class template linear_congruential_engine

[rand.eng.lcong]

A linear_congruential_engine random number engine produces unsigned integer random numbers. The

state x_i 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 TA(x_i) = (a · x_i + c) mod m; the generation algorithm is

GA(x_i) = x_i+1.

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

explicit linear_congruential_engine(result_type s = default_seed);

template<class Sseq> explicit linear_congruential_engine(Sseq& q);

void seed(result_type s = default_seed);

template<class Sseq> void seed(Sseq& q);

§ 29.6.3.1

960

// 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 29.6.3.1 is numeric_-

limits<result_type>::max() plus 1. [ Note: 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_i.

explicit linear_congruential_engine(result_type s = default_seed);

Effects: Constructs a linear_congruential_engine object. If c mod m is 0 and s mod m is 0, sets

the engine’s state to 1, otherwise sets the engine’s state to s mod m.

template<class Sseq> explicit linear_congruential_engine(Sseq& q);

⌈

⌉

log₂ m

Effects: Constructs a linear_congruential_engine object. With k =

and a an array

(or equivalent) of length k + 3, invokes q.generate(a + 0, a + k + 3) and then computes S =

)

(∑_k−1

a_j+3 · 2^32j mod m. If c mod m is 0 and S is 0, sets the engine’s state to 1, else sets the engine’s

j=0

state to S.

29.6.3.2

Class template mersenne_twister_engine

[rand.eng.mers]

A mersenne_twister_engine random number engine²⁷³ produces unsigned integer random numbers in the

closed interval [0, 2^w − 1]. The state x_i 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:

a) Concatenate the upper w − r bits of X_i−n with the lower r bits of X_i+1−n to obtain an unsigned integer

value Y .

b) With α = a · (Y bitand 1), set X_i to X_i+m−n xor (Y rshift 1) xor α.

The sequence X is initialized with the help of an initialization multiplier f .

The generation algorithm determines the unsigned integer values z₁, z₂, z₃, z₄ as follows, then delivers z₄ as

its result:

(

)

a) Let z₁ = X_i xor

(X_i rshift u) bitand d

(

)

b) Let z₂ = z₁ xor

(z₁ lshift_w s) bitand b

(

)

c) Let z₃ = z₂ xor

(z₂ lshift_w t) bitand c

d) Let z₄ = z₃ xor (z₃ rshift ℓ).

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;

273) 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.

§ 29.6.3.2

961

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

2^w − 1; }

static constexpr result_type default_seed = 5489u;

// constructors and seeding functions

explicit mersenne_twister_engine(result_type value = default_seed);

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_i consists of the values of X_i−n, . . . , X_i−1, in that order.

explicit mersenne_twister_engine(result_type value = default_seed);

Effects: Constructs a mersenne_twister_engine object. Sets X_−n to value mod 2^w . Then, iteratively

for i = 1−n, . . . , −1, sets X_i to

[

(

))

]

f·

X_i−1 xor

X_i−1 rshift(w − 2)

+ i mod n

mod 2^w .

Complexity: O(n).

template<class Sseq> explicit mersenne_twister_engine(Sseq& q);

Effects: Constructs a mersenne_twister_engine object. With k = ⌈w/32⌉ and a an array (or

equivalent) of length n · k, invokes q.generate(a + 0, a + n · k) and then, iteratively for i = −n, . . . , −1,

)

(∑_k−1

sets X_i to

· 2^32j mod 2^w. Finally, if the most significant w − r bits of X_−n are zero,

j=0 ak(i+n)+j

and if each of the other resulting X_i is 0, changes X_−n to 2^w−1.

29.6.3.3

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_i of a subtract_with_carry_engine object x is of size O(r), and consists of a sequence X of

r integer values 0 ≤ X_i < m = 2^w; all subscripts applied to X are to be taken modulo r. The state x_i

additionally consists of an integer c (known as the carry) whose value is either 0 or 1.

The state transition is performed as follows:

a) Let Y = X_i−s − X_i−r − c.

b) Set X_i to y = Y mod m. Set c to 1 if Y < 0, otherwise set c to 0.

[ Note: This algorithm corresponds to a modular linear function of the form TA(x_i) = (a · x_i) mod b, where b

is of the form m^r − m^s + 1 and a = b − (b − 1)/m. — end note ]

The generation algorithm is given by GA(x_i) = y, where y is the value produced as a result of advancing the

engine’s state as described above.

§ 29.6.3.3

962

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 m − 1; }

static constexpr result_type default_seed = 19780503u;

// constructors and seeding functions

explicit subtract_with_carry_engine(result_type value = default_seed);

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 X_i−r , . . . , X_i−1, in that order, followed by c.

explicit subtract_with_carry_engine(result_type value = default_seed);

Effects: Constructs a subtract_with_carry_engine object. Sets the values of X_−r , . . . , X₋₁, in that

order, as specified below. If X₋₁ is then 0, sets c to 1; otherwise sets c to 0.

To set the values X_k , 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 X_k , obtain new values z₀, . . . , z_n−1 from n = ⌈w/32⌉ successive invocations of e taken

)

(∑_n−1

modulo 2³². Set X_k to

z_j · 2^32j mod m.

j=0

Complexity: Exactly n · r invocations of e.

template<class Sseq> explicit subtract_with_carry_engine(Sseq& q);

Effects: Constructs a subtract_with_carry_engine object. With k = ⌈w/32⌉ and a an array (or

equivalent) of length r · k, invokes q.generate(a + 0, a + r · k) and then, iteratively for i = −r, . . . , −1,

)

(∑_k−1

sets X_i to

· 2^32j mod m. If X₋₁ is then 0, sets c to 1; otherwise sets c to 0.

j=0 ak(i+r)+j

29.6.4

Random number engine adaptor class templates

[rand.adapt]

29.6.4.1

In general

[rand.adapt.general]

Each type instantiated from a class template specified in this subclause 29.6.4 satisfies the requirements of a

random number engine adaptor (29.6.1.5) type.

Except where specified otherwise, the complexity of each function specified in this subclause 29.6.4 is constant.

Except where specified otherwise, no function described in this subclause 29.6.4 throws an exception.

Every function described in this subclause 29.6.4 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 29.6.4 only for adaptor operations that are not described in

subclause 29.6.1.5 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.

§ 29.6.4.1

963

Each template specified in this subclause 29.6.4 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.

29.6.4.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_i of a discard_block_engine engine adaptor object x consists

of the state e_i 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 r > 0 values from each block of p ≥ r values delivered by e. The

state transition is performed as follows: If n ≥ r, advance the state of e from e_i to e_i+p−r and set n to 0. In

any case, then increment n and advance e’s then-current state e_j to e_j+1.

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 29.6.1.5, each constructor that is not a copy constructor

sets n to 0.

29.6.4.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_i of

an independent_bits_engine engine adaptor object x consists of the state e_i 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:

§ 29.6.4.3

964

a) Let R = e.max() - e.min() + 1 and m = ⌊log₂ R⌋.

b) With n as determined below, let w₀ = ⌊w/n⌋, n₀ = n − w mod n, y₀ = 2w0 ⌊R/2w0 ⌋, and y₁ =

2w0+1 ⌊R/2w0+1⌋.

c) Let n = ⌈w/m⌉ if and only if the relation R−y₀ ≤ ⌊y₀/n⌋ holds as a result. Otherwise let n = 1+⌈w/m⌉.

[ Note: The relation w = n₀w₀ + (n − n₀)(w₀ + 1) always holds. — end note ]

The transition algorithm is carried out by invoking e() as often as needed to obtain n₀

values less than

y₀ + e.min() and n − n₀ values less than y₁ + e.min().

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 = n0; k += 1)

{

do u = e() - e.min(); while (u ≥ y0);

S = 2w0 · S + u mod 2w0;

}

for (k = n0; k = n; k += 1)

{

do u = e() - e.min(); while (u ≥ y1);

S = 2w0+1 · S + u mod 2w0+1;

}

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 2^w − 1; }

// 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.

29.6.4.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_i of a shuffle_-

order_engine engine adaptor object x consists of the state e_i 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 k + 1.

The transition algorithm permutes the values produced by e. The state transition is performed as follows:

§ 29.6.4.4

965

⌊

⌋

k·(Y −emin )

a) Calculate an integer j =

emax −emin +1

b) Set Y to V_j and then set V_j 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 29.6.1.5, each constructor that is not a copy constructor

initializes V[0], . . . , V[k-1] and Y , in that order, with values returned by successive invocations of e().

29.6.5

Engines and engine adaptors with predefined parameters

[rand.predef]

using minstd_rand0 =

linear_congruential_engine<uint_fast32_t, 16807, 0, 2147483647>;

Required behavior: The 10000^th consecutive invocation of a default-constructed object of type minstd_-

rand0 shall produce the value 1043618065.

using minstd_rand =

linear_congruential_engine<uint_fast32_t, 48271, 0, 2147483647>;

Required behavior: The 10000^th consecutive invocation of a default-constructed object of type minstd_-

rand shall produce the value 399268537.

using mt19937 =

mersenne_twister_engine<uint_fast32_t,

32,624,397,31,0x9908b0df,11,0xffffffff,7,0x9d2c5680,15,0xefc60000,18,1812433253>;

Required behavior: The 10000^th consecutive invocation of a default-constructed object of type mt19937

shall produce the value 4123659995.

§ 29.6.5

966

using mt19937_64 =

mersenne_twister_engine<uint_fast64_t,

64,312,156,31,0xb5026f5aa96619e9,29,

0x5555555555555555,17,

0x71d67fffeda60000,37,

0xfff7eee000000000,43,

6364136223846793005>;

Required behavior: The 10000^th consecutive invocation of a default-constructed object of type mt19937_-

64 shall produce the value 9981545732273789042.

using ranlux24_base =

subtract_with_carry_engine<uint_fast32_t, 24, 10, 24>;

Required behavior: The 10000^th consecutive invocation of a default-constructed object of type ran-

lux24_base shall produce the value 7937952.

using ranlux48_base =

subtract_with_carry_engine<uint_fast64_t, 48, 5, 12>;

Required behavior: The 10000^th consecutive invocation of a default-constructed object of type ran-

lux48_base shall produce the value 61839128582725.

using ranlux24 = discard_block_engine<ranlux24_base, 223, 23>;

Required behavior: The 10000^th consecutive invocation of a default-constructed object of type ranlux24

shall produce the value 9901578.

using ranlux48 = discard_block_engine<ranlux48_base, 389, 11>;

Required behavior: The 10000^th consecutive invocation of a default-constructed object of type ranlux48

shall produce the value 249142670248501.

using knuth_b = shuffle_order_engine<minstd_rand0,256>;

Required behavior: The 10000^th consecutive invocation of a default-constructed object of type knuth_b

shall produce the value 1112339016.

using default_random_engine = implementation-defined ;

Remarks: The choice of engine type named by this typedef is implementation-defined. [ Note: The

implementation may 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 may select different underlying engine types, code

that uses this typedef need not generate identical sequences across implementations.

— end note ]

29.6.6

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

explicit random_device(const string& token = implementation-defined );

// generating functions

result_type operator()();

§ 29.6.6

967

// 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 = implementation-defined );

Effects: Constructs a random_device nondeterministic uniform random bit generator object. The

semantics and default value of the token parameter are implementation-defined.²⁷⁴

Throws: A value of an implementation-defined type derived from exception if the random_device

could not be initialized.

double entropy() const noexcept;

Returns: If the implementation employs a random number engine, returns 0.0. Otherwise, returns

an entropy estimate²⁷⁵ for the random numbers returned by operator(), in the range min() to

log₂(max() + 1).

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.

29.6.7

Utilities

[rand.util]

29.6.7.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

};

274) The parameter is intended to allow an implementation to differentiate between different sources of randomness.

275) If a device has n states whose respective probabilities are P₀, . . . , P_n−1, the device entropy S is defined as

∑_n−1

S =−

log P_i.

i=0 Pⁱ ·

§ 29.6.7.1

968

seed_seq();

Effects: Constructs a seed_seq object as if by default-constructing its member v.

Throws: Nothing.

template<class T>

seed_seq(initializer_list<T> il);

Requires: T shall be an integer type.

Effects: Same as seed_seq(il.begin(), il.end()).

template<class InputIterator>

seed_seq(InputIterator begin, InputIterator end);

Requires: InputIterator shall satisfy the requirements of an input iterator (Table 95) type. Moreover,

iterator_traits<InputIterator>::value_type shall denote an integer type.

Effects: Constructs a seed_seq object by the following algorithm:

for( InputIterator s = begin; s != end; ++s)

v.push_back((*s)mod2³²);

template<class RandomAccessIterator>

void generate(RandomAccessIterator begin, RandomAccessIterator end);

Requires: RandomAccessIterator shall meet the requirements of a mutable random access itera-

tor (27.2.7). Moreover, iterator_traits<RandomAccessIterator>::value_type shall denote an

unsigned integer type capable of accommodating 32-bit quantities.

Effects: Does nothing if begin == end. Otherwise, with s = v.size() and n = end − begin, fills

the supplied range [begin, end) according to the following algorithm in which each operation is to be

carried out modulo 2³², each indexing operator applied to begin is to be taken modulo n, and T (x) is

defined as x xor (x rshift 27):

a) By way of initialization, set each element of the range to the value 0x8b8b8b8b. Additionally, for

use in subsequent steps, let p = (n − t)/2 and let q = p + t, where

t = (n ≥ 623) ? 11 : (n ≥ 68) ? 7 : (n ≥ 39) ? 5 : (n ≥ 7) ? 3 : (n − 1)/2;

b) With m as the larger of s + 1 and n, transform the elements of the range: iteratively for

k = 0,...,m − 1, calculate values

r₁

1664525 · T (begin[k] xor begin[k + p] xor begin[k − 1])





,k=0

r₂

= r₁ +

,0<k≤s

 kmodn+v[k−1]

k mod n

,s<k

and, in order, increment begin[k + p] by r₁, increment begin[k + q] by r₂, and set begin[k] to

r₂.

c) Transform the elements of the range again, beginning where the previous step ended: iteratively

for k = m, . . . , m+n−1, calculate values

r₃

1566083941 · T (begin[k] + begin[k + p] + begin[k − 1])

r₄

= r₃ − (k mod n)

and, in order, update begin[k + p] by xoring it with r₃, update begin[k + q] by xoring it with

r₄, and set begin[k] to r₄.

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.

§ 29.6.7.1

969

template<class OutputIterator>

void param(OutputIterator dest) const;

Requires: OutputIterator shall satisfy the requirements of an output iterator (27.2.4). Moreover, the

expression *dest = rt shall be valid for a value rt of type result_type.

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.

29.6.7.2

Function template generate_canonical

[rand.util.canonical]

Each function instantiated from the template described in this subclause 29.6.7.2 maps the result of one or

more invocations of a supplied uniform random bit generator g to one member of the specified RealType

such that, if the values g_i produced by g are uniformly distributed, the instantiation’s results t_j , 0 ≤ t_j < 1,

are distributed as uniformly as possible as specified below.

[ Note: 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 ]

template<class RealType, size_t bits, class URBG>

RealType generate_canonical(URBG& g);

Complexity: Exactly k = max(1,⌈b/log₂ R⌉) invocations of g, where b²⁷⁶ is the lesser of numeric_-

limits<RealType>::digits and bits, and R is the value of g.max() − g.min() + 1.

Effects: Invokes g() k times to obtain values g₀, . . . , g_k−1, respectively. Calculates a quantity

∑

S =

(g_i − g.min()) · Rⁱ

i=0

using arithmetic of type RealType.

Returns: S/R^k .

Throws: What and when g throws.

29.6.8

Random number distribution class templates

[rand.dist]

29.6.8.1

In general

[rand.dist.general]

Each type instantiated from a class template specified in this subclause 29.6.8 satisfies the requirements of a

random number distribution (29.6.1.6) type.

Descriptions are provided in this subclause 29.6.8 only for distribution operations that are not described

in 29.6.1.6 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 P (z_i) specified

in this subclause is 0 everywhere outside its stated domain.

29.6.8.2

Uniform distributions

[rand.dist.uni]

29.6.8.2.1

Class template uniform_int_distribution

[rand.dist.uni.int]

A uniform_int_distribution random number distribution produces random integers i, a ≤ i ≤ b, dis-

tributed according to the constant discrete probability function

P (i | a, b) = 1/(b − a + 1) .

276) b is introduced to avoid any attempt to produce more bits of randomness than can be held in RealType.

§ 29.6.8.2.1

970

template<class IntType = int>

class uniform_int_distribution {

public:

// types

using result_type = IntType;

using param_type

= unspecified ;

// constructors and reset functions

explicit uniform_int_distribution(IntType a = 0, 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 = 0, IntType b = numeric_limits<IntType>::max());

Requires: a ≤ b.

Effects: Constructs a uniform_int_distribution object; a and b correspond to the respective param-

eters 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.

29.6.8.2.2

Class template uniform_real_distribution

[rand.dist.uni.real]

A uniform_real_distribution random number distribution produces random numbers x, a ≤ x < b,

distributed according to the constant probability density function

p(x | a, b) = 1/(b − a) .

[ Note: This implies that p(x | a, b) 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

explicit uniform_real_distribution(RealType a = 0.0, 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);

§ 29.6.8.2.2

971

// 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 = 0.0, RealType b = 1.0);

Requires: a ≤ b and b − a ≤ numeric_limits<RealType>::max().

Effects: Constructs a uniform_real_distribution object; 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.

29.6.8.3

Bernoulli distributions

[rand.dist.bern]

29.6.8.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

{

if b = true

P (b | p) =

1−p

if b = false

class bernoulli_distribution {

public:

// types

using result_type = bool;

using param_type

= unspecified ;

// constructors and reset functions

explicit bernoulli_distribution(double p = 0.5);

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 = 0.5);

Requires: 0 ≤ p ≤ 1.

Effects: Constructs a bernoulli_distribution object; p corresponds to the parameter of the distri-

bution.

double p() const;

Returns: The value of the p parameter with which the object was constructed.

§ 29.6.8.3.1

972

29.6.8.3.2

Class template binomial_distribution

[rand.dist.bern.bin]

A binomial_distribution random number distribution produces integer values i ≥

distributed according

to the discrete probability function

)

P (i | t, p) =

· pⁱ · (1 − p)^t−i .

template<class IntType = int>

class binomial_distribution {

public:

// types

using result_type = IntType;

using param_type

= unspecified ;

// constructors and reset functions

explicit binomial_distribution(IntType t = 1, 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 = 1, double p = 0.5);

Requires: 0 ≤ p ≤ 1 and 0 ≤ t.

Effects: Constructs a binomial_distribution object; 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.

29.6.8.3.3

Class template geometric_distribution

[rand.dist.bern.geo]

A geometric_distribution random number distribution produces integer values i ≥ 0 distributed according

to the discrete probability function

P (i | p) = p · (1 − p)ⁱ .

template<class IntType = int>

class geometric_distribution {

public:

// types

using result_type = IntType;

using param_type

= unspecified ;

// constructors and reset functions

explicit geometric_distribution(double p = 0.5);

explicit geometric_distribution(const param_type& parm);

void reset();

§ 29.6.8.3.3

973

// 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 = 0.5);

Requires: 0 < p < 1.

Effects: Constructs a geometric_distribution object; p corresponds to the parameter of the distri-

bution.

double p() const;

Returns: The value of the p parameter with which the object was constructed.

29.6.8.3.4

Class template negative_binomial_distribution

[rand.dist.bern.negbin]

A negative_binomial_distribution random number distribution produces random integers i ≥

dis-

tributed according to the discrete probability function

)

(k + i − 1

P (i | k, p) =

· p^k · (1 − p)ⁱ .

[ Note: This implies that P (i | k, p) 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

explicit negative_binomial_distribution(IntType k = 1, 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 = 1, double p = 0.5);

Requires: 0 < p ≤ 1 and 0 < k.

Effects: Constructs a negative_binomial_distribution object; k and p correspond to the respective

parameters of the distribution.

§ 29.6.8.3.4

974

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.

29.6.8.4

Poisson distributions

[rand.dist.pois]

29.6.8.4.1

Class template poisson_distribution

[rand.dist.pois.poisson]

A poisson_distribution random number distribution produces integer values i ≥ 0

distributed according

to the discrete probability function

e^−µµ

P (i | µ) =

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

explicit poisson_distribution(double mean = 1.0);

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 = 1.0);

Requires: 0 < mean.

Effects: Constructs a poisson_distribution object; mean corresponds

the

parameter of

the

distribution.

double mean() const;

Returns: The value of the mean parameter with which the object was constructed.

29.6.8.4.2

Class template exponential_distribution

[rand.dist.pois.exp]

An exponential_distribution random number distribution produces random numbers x > 0 distributed

according to the probability density function

p(x | λ) = λe^−λx .

template<class RealType = double>

class exponential_distribution {

public:

// types

using result_type = RealType;

using param_type

= unspecified ;

§ 29.6.8.4.2

975

// constructors and reset functions

explicit exponential_distribution(RealType lambda = 1.0);

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 = 1.0);

Requires: 0 < lambda.

Effects: Constructs an exponential_distribution object; lambda corresponds to the parameter of

the distribution.

RealType lambda() const;

Returns: The value of the lambda parameter with which the object was constructed.

29.6.8.4.3

Class template gamma_distribution

[rand.dist.pois.gamma]

A gamma_distribution random number distribution produces random numbers x >

distributed according

to the probability density function

−x/β

p(x | α, β) =

· x^α−1 .

β^α · Γ(α)

template<class RealType = double>

class gamma_distribution {

public:

// types

using result_type = RealType;

using param_type

= unspecified ;

// constructors and reset functions

explicit gamma_distribution(RealType alpha = 1.0, 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;

};

§ 29.6.8.4.3

976

explicit gamma_distribution(RealType alpha = 1.0, RealType beta = 1.0);

Requires: 0 < alpha and 0 < beta.

Effects: Constructs a gamma_distribution object; 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.

29.6.8.4.4

Class template weibull_distribution

[rand.dist.pois.weibull]

A weibull_distribution random number distribution produces random numbers x ≥

0 distributed according

to the probability density function

(

)_a−1

(

)_a)

p(x | a, b) =

· exp

−

b ·

template<class RealType = double>

class weibull_distribution {

public:

// types

using result_type = RealType;

using param_type

= unspecified ;

// constructor and reset functions

explicit weibull_distribution(RealType a = 1.0, 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 = 1.0, RealType b = 1.0);

Requires: 0 < a and 0 < b.

Effects: Constructs a weibull_distribution object; 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.

§ 29.6.8.4.4

977

29.6.8.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 function²⁷⁷

))

(a−x

p(x | a, b) =

exp

− exp

b ·

template<class RealType = double>

class extreme_value_distribution {

public:

// types

using result_type = RealType;

using param_type

= unspecified ;

// constructor and reset functions

explicit extreme_value_distribution(RealType a = 0.0, 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 = 0.0, RealType b = 1.0);

Requires: 0 < b.

Effects: Constructs an extreme_value_distribution object; 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.

29.6.8.5

Normal distributions

[rand.dist.norm]

29.6.8.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

(

p(x | µ, σ) =

√

· exp

−(x−µ)2)

2π

2σ²

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 ;

277) 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.

§ 29.6.8.5.1

978

// constructors and reset functions

explicit normal_distribution(RealType mean = 0.0, 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 = 0.0, RealType stddev = 1.0);

Requires: 0 < stddev.

Effects: Constructs a normal_distribution object; 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.

29.6.8.5.2

Class template lognormal_distribution

[rand.dist.norm.lognormal]

A lognormal_distribution random number distribution produces random numbers x >

distributed

according to the probability density function

(

p(x | m, s) =

√

· exp

−(lnx−m)2)

2π

2s²

template<class RealType = double>

class lognormal_distribution {

public:

// types

using result_type = RealType;

using param_type

= unspecified ;

// constructor and reset functions

explicit lognormal_distribution(RealType m = 0.0, 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;

§ 29.6.8.5.2

979

result_type max() const;

};

explicit lognormal_distribution(RealType m = 0.0, RealType s = 1.0);

Requires: 0 < s.

Effects: Constructs a lognormal_distribution object; 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.

29.6.8.5.3

Class template chi_squared_distribution

[rand.dist.norm.chisq]

A chi_squared_distribution random number distribution produces random numbers x >

distributed

according to the probability density function

−x/2

x^(n/2)−1 · e

p(x | n) =

Γ(n/2) · 2^n/2

template<class RealType = double>

class chi_squared_distribution {

public:

// types

using result_type = RealType;

using param_type

= unspecified ;

// constructor and reset functions

explicit chi_squared_distribution(RealType n = 1);

explicit chi_squared_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 n() const;

param_type param() const;

void param(const param_type& parm);

result_type min() const;

result_type max() const;

};

explicit chi_squared_distribution(RealType n = 1);

Requires: 0 < n.

Effects: Constructs a chi_squared_distribution object; n corresponds to the parameter of the

distribution.

RealType n() const;

Returns: The value of the n parameter with which the object was constructed.

29.6.8.5.4

Class template cauchy_distribution

[rand.dist.norm.cauchy]

A cauchy_distribution random number distribution produces random numbers x distributed according to

the probability density function

(

(x−a)2 ))−1

p(x | a, b) = πb

§ 29.6.8.5.4

980

template<class RealType = double>

class cauchy_distribution {

public:

// types

using result_type = RealType;

using param_type

= unspecified ;

// constructor and reset functions

explicit cauchy_distribution(RealType a = 0.0, RealType b =

1.0);

explicit cauchy_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 cauchy_distribution(RealType a = 0.0, RealType b = 1.0);

Requires: 0 < b.

Effects: Constructs a cauchy_distribution object; 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.

29.6.8.5.5

Class template fisher_f_distribution

[rand.dist.norm.f]

A fisher_f_distribution random number distribution produces random numbers x ≥ 0 distributed

according to the probability density function

(

)

(

)_m/2

(

)_−(m+n)/2

(m + n)/2

p(x | m, n) =

·x^(m/2)−1 ·

1+^mx

Γ(m/2) Γ(n/2)

template<class RealType = double>

class fisher_f_distribution {

public:

// types

using result_type = RealType;

using param_type

= unspecified ;

// constructor and reset functions

explicit fisher_f_distribution(RealType m = 1, RealType n = 1);

explicit fisher_f_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);

§ 29.6.8.5.5

981

Working Draft, Standard for Programming Language C++ (N4713, 2017 year) - page 33