random : C++26対応として、generate_random関数を追加 (close #1339)

Author: faithandbrave

lang/cpp26.md

@@ -288,7 +288,7 @@ C++26とは、2026年中に改訂される予定の、C++バージョンの通
     - [`std::real()`](/reference/complex/complex/real_free.md) (算術型オーバーロード)
 - [`std::complex`](/reference/complex/complex.md)を構造化束縛や、将来のパターンマッチで使用できるようタプルインタフェースの特殊化を追加
 - [`<random>`](/reference/random.md)の範囲`[0, 1)`の乱数を生成する[`std::generate_canonical()`](/reference/random/generate_canonical.md)を、望ましい統計的性質を保証するようアルゴリズムと制約を変更
-- [`<random>`](/reference/random.md)に、乱数列を生成する[`std::ranges::generate_random()`](/reference/random/generate_random.md.nolink)関数を追加
+- [`<random>`](/reference/random.md)に、乱数列を生成する[`std::ranges::generate_random()`](/reference/random/generate_random.md)関数を追加
 
 
 ### ユーティリティ

reference/random.md

@@ -143,6 +143,7 @@
 | 名前 | 説明 | 対応バージョン |
 |----------------|------------------------------|-------|
 | [`generate_canonical`](random/generate_canonical.md) | 実数区間\[0.0,1.0\)に展開（事実上正規化）された一様分布乱数を得る(function template) | C++11 |
+| [`generate_random`](random/generate_random.md) | 乱数列を生成する(function template) | C++26 |
 
 
 ## 例

reference/random/generate_random.md

@@ -0,0 +1,162 @@
+# generate_random
+* random[meta header]
+* std[meta namespace]
+* function template[meta id-type]
+* cpp26[meta cpp]
+
+```cpp
+namespace std::ranges {
+  template <class R, class G>
+    requires output_range<R, invoke_result_t<G&>> &&
+             uniform_random_bit_generator<remove_cvref_t<G>>
+  constexpr borrowed_iterator_t<R>
+    generate_random(R&& r, G&& g);                  // (1) C++26
+
+  template <class G,
+            output_iterator<invoke_result_t<G&>> O,
+            sentinel_for<O> S>
+    requires uniform_random_bit_generator<remove_cvref_t<G>>
+  constexpr O
+    generate_random(O first, S last, G&& g);        // (2) C++26
+
+  template <class R, class G, class D>
+    requires output_range<R, invoke_result_t<D&, G&>> &&
+             invocable<D&, G&> &&
+             uniform_random_bit_generator<remove_cvref_t<G>>
+  constexpr borrowed_iterator_t<R>
+    generate_random(R&& r, G&& g, D&& d);           // (3) C++26
+
+  template <class G,
+            class D,
+            output_iterator<invoke_result_t<D&, G&>> O,
+            sentinel_for<O> S>
+    requires invocable<D&, G&> &&
+             uniform_random_bit_generator<remove_cvref_t<G>>
+  constexpr O
+    generate_random(O first, S last, G&& g, D&& d); // (4) C++26
+}
+```
+* output_range[link /reference/ranges/output_range.md]
+* uniform_random_bit_generator[link uniform_random_bit_generator.md]
+* invoke_result_t[link /reference/type_traits/invoke_result.md]
+* remove_cvref_t[link /reference/type_traits/remove_cvref.md]
+* borrowed_iterator_t[link /reference/ranges/borrowed_iterator_t.md]
+* output_iterator[link /reference/iterator/output_iterator.md]
+* sentinel_for[link /reference/iterator/sentinel_for.md]
+* invocable[link /reference/concepts/invocable.md]
+
+## 概要
+乱数列を生成する。
+
+- (1) : 出力範囲`r`の各要素に、乱数生成器`g`で生成した乱数を代入する
+- (2) : 出力イテレータ範囲`[first, last)`の各要素に、乱数生成器`g`で生成した乱数を代入する
+- (3) : 出力範囲`r`の各要素に、乱数生成器`g`と分布生成器`d`で生成した乱数を代入する
+- (4) : 出力イテレータ範囲`[first, last)`の各要素に、乱数生成器`g`と分布生成器`d`で生成した乱数を代入する
+
+この関数は、`for`文を使用した以下のコードをアルゴリズム関数化したものである。
+
+```cpp
+std::vector<int> v(10);
+std::mt19937 gen {std::random_device{}()};
+std::uniform_int_distribution<int> dist{1, 100};
+
+// 以下の3つのコードは等価
+std::ranges::generate_random(v, gen);                  // (1)
+std::ranges::generate_random(v.begin(), v.end(), gen); // (2)
+for (auto& x : v) {
+  x = gen();
+}
+
+// 以下の3つのコードは等価
+std::ranges::generate_random(v, gen, dist);                  // (3)
+std::ranges::generate_random(v.begin(), v.end(), gen, dist); // (4)
+for (auto& x : v) {
+  x = dist(gen);
+}
+```
+
+
+## 効果
+- (1) :
+    - `g.generate_random(`[`std::forward`](/reference/utility/forward.md)`<R>(r))`が妥当な式であれば、それを呼び出す
+        - 備考 : 乱数生成器が`generate_random()`メンバ関数をもっていればそれを使用する
+    - そうでなく、`R`が[`sized_range`](/reference/ranges/sized_range.md)のモデルである場合、値`N`と[`span`](/reference/span/span.md)`<`[`invoke_result_t`](/reference/type_traits/invoke_result.md)`<G&>, N>`型オブジェクト`s`に対して、式`g()`または`g.generate_random(s)`を未規定の回数だけ呼び出して実行し、`r`の各要素に代入する
+        - 備考 : ここでの`N`は乱数生成の回数と異なってもよい
+    - そうでなければ、[`ranges::generate`](/reference/algorithm/ranges_generate.md)`(`[`std::forward`](/reference/utility/forward.md)`<R>(r), ref(g))`を呼び出す
+        - 備考 : [`std::forward_list`](/reference/forward_list/forward_list.md)のような`size()`メンバ関数をもたないコンテナがこちらに該当する
+
+- (2) : 以下と等価
+    ```cpp
+    return generate_random(subrange<O, S>(std::move(first), last), g);
+    ```
+    * subrange[link /reference/ranges/subrange.md]
+    * std::move[link /reference/utility/move.md]
+
+- (3) :
+     - `d.generate_random(`[`std::forward`](/reference/utility/forward.md)`<R>(r), g)`が妥当な式であれば、それを呼び出す
+        - 備考 : 分布生成器が`generate_random()`メンバ関数をもっていればそれを使用する
+    - そうでなく、`R`が[`sized_range`](/reference/ranges/sized_range.md)のモデルである場合、値`N`と[`span`](/reference/span/span.md)`<`[`invoke_result_t`](/reference/type_traits/invoke_result.md)`<D&, G&>, N>`型オブジェクト`s`に対して、式[`invoke`](/reference/functional/invoke.md)`(d, g)`または`d.generate_random(s, g)`を未規定の回数だけ呼び出して実行し、`r`の各要素に代入する
+        - 備考 : ここでの`N`は乱数生成の回数と異なってもよい
+    - そうでなければ、[`ranges::generate`](/reference/algorithm/ranges_generate.md)`(`[`std::forward`](/reference/utility/forward.md)`<R>(r), [&d, &g] { return` [`invoke`](/reference/functional/invoke.md)`(d, g); })`を呼び出す
+        - 備考 : [`std::forward_list`](/reference/forward_list/forward_list.md)のような`size()`メンバ関数をもたないコンテナがこちらに該当する
+
+- (4) : 以下と等価
+    ```cpp
+    return generate_random(subrange<O, S>(std::move(first), last), g, d);
+    ```
+    * subrange[link /reference/ranges/subrange.md]
+    * std::move[link /reference/utility/move.md]
+
+
+## 戻り値
+- (1), (3) :
+    ```cpp
+    return ranges::end(r);
+    ```
+    * ranges::end[link /reference/ranges/end.md]
+
+
+## 例
+```cpp example
+#include <random>
+#include <print>
+#include <vector>
+
+int main()
+{
+  std::random_device seed_gen;
+  std::mt19937 engine(seed_gen());
+  std::uniform_int_distribution<int> dist{0, 100};
+
+  std::vector<int> v(10);
+
+  // コンテナの全要素を乱数で埋める
+  std::ranges::generate_random(v, engine);
+  std::println("{}", v);
+
+  // コンテナの全要素を、指定した分布の乱数で埋める
+  std::ranges::generate_random(v, engine, dist);
+  std::println("{}", v);
+}
+```
+* std::generate_canonical[color ff0000]
+* digits[link /reference/limits/numeric_limits/digits.md]
+
+### 出力
+```
+[2034091041, 1919373608, 514210727, -1154669807, -315048337, -1224623446, -1986406128, -1034429876, -844125616, 1858136340]
+[83, 25, 48, 15, 9, 60, 47, 31, 91, 54]
+```
+
+## バージョン
+### 言語
+- C++26
+
+### 処理系
+- [Clang](/implementation.md#clang): 19.0 [mark noimpl]
+- [GCC](/implementation.md#gcc): 14 [mark noimpl]
+- [Visual C++](/implementation.md#visual_cpp): 2022 Update 10 [mark noimpl]
+
+
+## 参照
+- [P1068R11 Vector API for random number generation](https://open-std.org/jtc1/sc22/wg21/docs/papers/2024/p1068r11.pdf)