28 Numerics library [numerics]

28.5 Random number generation [rand]

28.5.8 Utilities [rand.util]

28.5.8.1 Class seed_seq [rand.util.seedseq]

namespace std { class seed_seq { public: // types using result_type = uint_least32_t; // constructors seed_seq() noexcept; 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() noexcept;
Postconditions: v.empty() is true.
template<class T> seed_seq(initializer_list<T> il);
Constraints: 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 [begin,end) 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 x xor(x rshift27):
  • 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.

28.5.8.2 Function template generate_canonical [rand.util.canonical]

template<class RealType, size_t digits, class URBG> RealType generate_canonical(URBG& g);
Let
  • r be numeric_limits<RealType>​::​radix,
  • R be ,
  • d be the smaller of digits and numeric_limits<RealType>​::​digits,229
  • k be the smallest integer such that , and
  • x be .
An attempt is k invocations of g() to obtain values , respectively, and the calculation of a quantity
Effects: Attempts are made until .
[Note 1: 
When R is a power of r, precisely one attempt is made.
— end note]
Returns: .
[Note 2: 
The return value c satisfies .
— end note]
Throws: What and when g throws.
Complexity: Exactly k invocations of g per attempt.
[Note 3: 
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]
[Note 4: 
When R is a power of r, an implementation can avoid using an arithmetic type that is wider than the output when computing S.
— end note]
229)229)
d is introduced to avoid any attempt to produce more bits of randomness than can be held in RealType.