generate_canonical : C++26で範囲外の値が生成されなくなった仕様変更に対応 #1239

仕様として変更を記載したので、Qiitaの考察・検証の記事への参照を削除

Author: faithandbrave

reference/random/generate_canonical.md

@@ -7,7 +7,10 @@
 ```cpp
 namespace std {
   template<class RealType, std::size_t bits, class URBG>
-  RealType generate_canonical(URBG& g);
+  RealType generate_canonical(URBG& g);  // (1) C++11
+
+  template<class RealType, std::size_t digits, class URBG>
+  RealType generate_canonical(URBG& g);  // (1) C++26
 }
 ```
 
@@ -18,17 +21,50 @@ namespace std {
 
 ## テンプレートパラメータ
 - `class RealType` : 生成する実数の型。
-- `size_t bits` : 生成する実数における仮数部への分解能の最低要求。最大値は `std::`[`numeric_limits`](/reference/limits/numeric_limits.md)`<RealType>::`[`digits`](/reference/limits/numeric_limits/digits.md) 。
+- `size_t bits` : 生成する実数における仮数部への分解能の最低要求。最大値は `std::`[`numeric_limits`](/reference/limits/numeric_limits.md)`<RealType>::`[`digits`](/reference/limits/numeric_limits/digits.md)
+    - C++26で`digits`に名称変更
+- `size_t digits` : 生成する実数における基数非依存の桁数としての分解能の最低要求。最大値は `std::`[`numeric_limits`](/reference/limits/numeric_limits.md)`<RealType>::`[`digits`](/reference/limits/numeric_limits/digits.md) 。
 - `class URBG` : 一様乱数生成器の型。
 
 ## 関数パラメータ
 - URBG& g : 一様乱数生成器。
 
 
+## 効果
+- C++11からC++23まで :
+    以下の変数を定義する。
+    - `R` = `g.`[`max()`](/reference/random/uniform_random_bit_generator.md) `-` `g.`[`min()`](/reference/random/uniform_random_bit_generator.md) `+ 1`
+    - `k` = max(1, ⌈`bits` / log<sub>2</sub>`R`⌉)
+    - `S` = `g()` から `k` 回呼び出した結果を `R` のべき乗で重み付けして累積した値
+
+    戻り値は `S` / `R`<sup>`k`</sup> となる。ただし浮動小数点数の丸めにより、結果が1.0になる場合がある。
+
+- C++26 :
+    以下の変数を定義する。
+    - `r` = [`numeric_limits`](/reference/limits/numeric_limits.md)`<RealType>::`[`radix`](/reference/limits/numeric_limits/radix.md)
+    - `R` = `g.`[`max()`](/reference/random/uniform_random_bit_generator.md) `-` `g.`[`min()`](/reference/random/uniform_random_bit_generator.md) `+ 1`
+    - `d` = min(`digits`, [`numeric_limits`](/reference/limits/numeric_limits.md)`<RealType>::`[`digits`](/reference/limits/numeric_limits/digits.md))
+    - `k` = `R`<sup>`k`</sup> ≥ `r`<sup>`d`</sup> を満たす最小の整数
+    - `x` = ⌊`R`<sup>`k`</sup> / `r`<sup>`d`</sup>⌋
+
+    以下の手順で乱数を生成する。
+
+    1. `g()` を `k` 回呼び出して値 `S` を生成する
+    2. `S` ≥ `x` · `r`<sup>`d`</sup> の場合、手順1に戻って再試行する（棄却法）
+    3. 戻り値は ⌊`S` / `x`⌋ / `r`<sup>`d`</sup> となる
+
+    この棄却法により、浮動小数点数の丸めで結果が1.0になる問題が解消され、戻り値は必ず0以上1未満となることが保証される。
+
+
 ## 例外
 `URBG g` が例外を送出する場合はそれに準ずる。
 
 
+## 備考
+- C++23まではアルゴリズムの仕様上、浮動小数点数の丸めにより値`1.0`が生成されることがあった
+- C++26では棄却法（reject-and-retry）方式が導入され、戻り値が\[0.0, 1.0\)の範囲内であることが保証されるようになった
+
+
 ## 例
 ```cpp example
 #include <random>
@@ -80,10 +116,8 @@ int main()
 - GCC 4.9時点において、`float`型を指定した場合に、値`1.0`が生成されることがあるバグがある([Bug 63176](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=63176))
 - Clang 3.3時点において、値`1.0`が生成されることがある([Bug 18767](https://llvm.org/bugs/show_bug.cgi?id=18767))
 
-### 参考
-- N3337 p.909 §26.5.7.2
-
-
 ## 参照
 - [P0346R1 A `<random>` Nomenclature Tweak](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0346r1.pdf)
     - URNGをURBGに変更
+- [P0952R2 A New Specification for `generate_canonical`](https://open-std.org/jtc1/sc22/wg21/docs/papers/2023/p0952r2.html)
+    - C++26でテンプレートパラメータ名を`bits`から`digits`に変更し、棄却法による新しいアルゴリズムを導入

reference/random/uniform_real_distribution.md

@@ -20,6 +20,13 @@ namespace std {
 - `RealType` : 生成する実数の型。
 
 
+## 備考
+- `uniform_real_distribution`の実装は、内部的に[`std::generate_canonical()`](generate_canonical.md)を使用している環境がある
+    - C++23まではその`std::generate_canonical()`の仕様上、浮動小数点数の丸めにより指定範囲外の値（上限値`b`）が生成されることがあった
+    - C++26では`std::generate_canonical()`に棄却法が導入されたことで、この問題は解消された
+        - [P0952R2 A New Specification for `generate_canonical`](https://open-std.org/jtc1/sc22/wg21/docs/papers/2023/p0952r2.html)
+
+
 ## メンバ関数
 ### 構築・リセット
 

reference/random/uniform_real_distribution/op_constructor.md

@@ -85,5 +85,3 @@ int main()
 ## 参照
 
 - [P0935R0 Eradicating unnecessarily explicit default constructors from the standard library](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0935r0.html)
-- [C++ の std::uniform_real_distribution はあまり信用できない。](https://qiita.com/Nabetani/items/b6b5f80c77b92ff8bd9f)
-    - a ≤ x < b なるx を返すはずであるが、その範囲外の値が返ってくるライブラリ実装が存在することの指摘。