29 Numerics library [numerics]

29.6 Random number generation [rand]

29.6.7 Utilities [rand.util] Class seed_­seq [rand.util.seedseq]

class seed_seq {
  // types
  using result_type = uint_least32_t;

  // constructors
  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;

  vector<result_type> v;   // exposition only


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

template<class RandomAccessIterator> void generate(RandomAccessIterator begin, RandomAccessIterator end);

Requires: RandomAccessIterator shall meet the requirements of a mutable random access iterator. 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=endbegin, fills the supplied range [begin,end) according to the following algorithm in which each operation is to be carried out modulo 232, each indexing operator applied to begin is to be taken modulo n, and T(x) is defined as xxor(xrshift27):

  1. a)By way of initialization, set each element of the range to the value 0x8b8b8b8b. Additionally, for use in subsequent steps, let p=(nt)/2 and let q=p+t, where

    t=(n623) ? 11 : (n68) ? 7 : (n39) ? 5 : (n7) ? 3 : (n1)/2;

  2. b)With m as the larger of s+1 and n, transform the elements of the range: iteratively for k=0,,m1, calculate values


    and, in order, increment begin[k+p] by r1, increment begin[k+q] by r2, and set begin[k] to r2.

  3. c)Transform the elements of the range again, beginning where the previous step ended: iteratively for k=m,,m+n1, calculate values


    and, in order, update begin[k+p] by xoring it with r3, update begin[k+q] by xoring it with r4, and set begin[k] to r4.

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;

Requires: OutputIterator shall satisfy the requirements of an output iterator. 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. Function template generate_­canonical [rand.util.canonical]

Each function instantiated from the template described in this section [rand.util.canonical] 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 gi produced by g are uniformly distributed, the instantiation's results tj, 0tj<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/log2R) invocations of g, where b273 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 g0,,gk1, respectively. Calculates a quantity


using arithmetic of type RealType.

Returns: S/Rk.

Throws: What and when g throws.

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