[rand.util] - C++17 → C++20

Files changed (1) hide show

tmp/tmp_rhp8ak9/{from.md → to.md} +67 -26

tmp/tmp_rhp8ak9/{from.md → to.md} RENAMED Viewed

@@ -35,35 +35,35 @@ private:
 ``` cpp
 seed_seq();
 ```
-*Effects:* Constructs a `seed_seq` object as if by default-constructing
-its member `v`.
 *Throws:* Nothing.
 ``` cpp
 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())`.
 ``` cpp
 template<class InputIterator>
   seed_seq(InputIterator begin, InputIterator end);
 ```
-*Requires:* `InputIterator` shall satisfy the requirements of an input
-iterator (Table  [[tab:iterator.input.requirements]]) type. Moreover,
-`iterator_traits<InputIterator>::value_type` shall denote an integer
 type.
-*Effects:* Constructs a `seed_seq` object by the following algorithm:
 ``` cpp
 for (InputIterator s = begin; s != end; ++s)
  v.push_back((*s) mod  2³²);
 ```
@@ -71,21 +71,63 @@ for( InputIterator s = begin; s != end; ++s)
 ``` cpp
 template<class RandomAccessIterator>
   void generate(RandomAccessIterator begin, RandomAccessIterator end);
 ```
-*Requires:* `RandomAccessIterator` shall meet the requirements of a
-mutable random access iterator ([[random.access.iterators]]). 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 \, \rightshift \, 27)$:
 *Throws:* What and when `RandomAccessIterator` operations of `begin` and
 `end` throw.
 ``` cpp
@@ -100,13 +142,15 @@ to `param()`.
 ``` cpp
 template<class OutputIterator>
   void param(OutputIterator dest) const;
 ```
-*Requires:* `OutputIterator` shall satisfy the requirements of an output
-iterator ([[output.iterators]]). 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:
 ``` cpp
@@ -115,22 +159,10 @@ copy(v.begin(), v.end(), dest);
 *Throws:* What and when `OutputIterator` operations of `dest` throw.
 #### Function template `generate_canonical` <a id="rand.util.canonical">[[rand.util.canonical]]</a>
-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 gᵢ produced by `g` are uniformly
-distributed, the instantiation’s results tⱼ, 0 ≤ tⱼ < 1, are distributed
-as uniformly as possible as specified below.
-[*Note 1*: 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*]
 ``` cpp
 template<class RealType, size_t bits, class URBG>
   RealType generate_canonical(URBG& g);
 ```
@@ -143,7 +175,16 @@ respectively. Calculates a quantity
 $$S = \sum_{i=0}^{k-1} (g_i - \texttt{g.min()})
                         \cdot R^i$$ using arithmetic of type `RealType`.
 *Returns:* S / Rᵏ.
 *Throws:* What and when `g` throws.

 ``` cpp
 seed_seq();
 ```
+*Ensures:* `v.empty()` is `true`.
 *Throws:* Nothing.
 ``` cpp
 template<class T>
  seed_seq(initializer_list<T> il);
 ```
+*Mandates:* `T` is an integer type.
 *Effects:* Same as `seed_seq(il.begin(), il.end())`.
 ``` cpp
 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:
 ``` cpp
 for (InputIterator s = begin; s != end; ++s)
  v.push_back((*s) mod  2³²);
 ```
 ``` cpp
 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
 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 \rightshift 27)$:
+- 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 \ge 623) \mbox{ ? } 11 \mbox{ : } (n \ge 68) \mbox{ ? } 7 \mbox{ : } (n \ge 39) \mbox{ ? } 5 \mbox{ : } (n \ge 7) \mbox{ ? } 3 \mbox{ : } (n - 1)/2;$$
+- With m as the larger of s + 1 and n, transform the elements of the
+  range: iteratively for k = 0, …, m - 1, calculate values
+  $$\begin{aligned}
+       r_1 & = &
+         1664525 \cdot T(    \texttt{begin[}k\texttt{]}
+                        \xor \texttt{begin[}k+p\texttt{]}
+                        \xor \texttt{begin[}k-1 \texttt{]}
+                        )
+       \\
+       r_2 & = & r_1 + \left\{
+         \begin{array}{cl}
+           s                                  & \mbox{,  } k = 0
+           \\
+           k \bmod n + \texttt{v[}k-1\texttt{]} & \mbox{,  } 0 < k \le s
+           \\
+           k \bmod n                          & \mbox{,  } s < k
+         \end{array}
+       \right.
+  \end{aligned}$$ and, in order, increment `begin[`k+p`]` by r₁,
+  increment `begin[`k+q`]` by r₂, and set `begin[`k`]` to r₂.
+- Transform the elements of the range again, beginning where the
+  previous step ended: iteratively for k = m, …, m + n - 1, calculate
+  values $$\begin{aligned}
+       r_3 & = &
+         1566083941 \cdot T( \texttt{begin[}k  \texttt{]}
+                           + \texttt{begin[}k+p\texttt{]}
+                           + \texttt{begin[}k-1\texttt{]}
+                           )
+       \\
+       r_4 & = & r_3 - (k \bmod n)
+  \end{aligned}$$ 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.
 ``` cpp
 ``` cpp
 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:
 ``` cpp
 *Throws:* What and when `OutputIterator` operations of `dest` throw.
 #### Function template `generate_canonical` <a id="rand.util.canonical">[[rand.util.canonical]]</a>
 ``` cpp
 template<class RealType, size_t bits, class URBG>
   RealType generate_canonical(URBG& g);
 ```
 $$S = \sum_{i=0}^{k-1} (g_i - \texttt{g.min()})
                         \cdot R^i$$ using arithmetic of type `RealType`.
 *Returns:* S / Rᵏ.
+[*Note 1*: 0 ≤ S / Rᵏ < 1. — *end note*]
 *Throws:* What and when `g` throws.
+[*Note 2*: If the values gᵢ 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*]

Diff to HTML by rtfpessoa