functional/function_ref: 概要のみ(#1192)

yohhoy · yohhoy · commit 4cbbdaef0bc7 · 2024-01-05T18:09:24.000+09:00
diff --git a/lang/cpp26.md b/lang/cpp26.md
@@ -86,7 +86,7 @@ C++26とは、2026年中に改訂される予定の、C++バージョンの通
 
 
 ### 関数オブジェクト
-- 所有権を保持しない[`std::function`](/reference/functional/function.md)として、[`<functional>`](/reference/functional.md)に[`std::function_ref`](/reference/functional/function_ref.md.nolink)クラスを追加
+- 所有権を保持しない[`std::function`](/reference/functional/function.md)として、[`<functional>`](/reference/functional.md)に[`std::function_ref`](/reference/functional/function_ref.md)クラスを追加
 - [`std::move_only_function`](/reference/functional/move_only_function.md)のコピー可能版として、[`<functional>`](/reference/functional.md)に[`std::copyable_function`](/reference/functional/copyable_function.md)クラスを追加
 - [`std::bind_front()`](/reference/functional/bind_front.md)と[`std::bind_back()`](/reference/functional/bind_back.md.nolink)に、非型テンプレート引数として関数を指定するオーバーロードを追加
     - 関連して、非型テンプレート引数の関数オブジェクトを反転させられるよう、[`not_fn()`](/reference/functional/not_fn.md)に非型テンプレート引数版のオーバーロードを追加
diff --git a/reference/functional.md b/reference/functional.md
@@ -27,7 +27,7 @@ struct doubler {
 | [`bad_function_call`](functional/bad_function_call.md) | 不正な関数呼び出しに関する例外(class)  | C++11 |
 | [`move_only_function`](functional/move_only_function.md) | ムーブのみ可能な関数・関数オブジェクトの多相軽量ラッパー(class template) | C++23 |
 | [`copyable_function`](functional/copyable_function.md) | コピー可能な関数・関数オブジェクトの多相軽量ラッパー(class template) | C++26 |
-| [`function_ref`](functional/function_ref.md.nolink) | 関数・関数オブジェクトの多相参照ラッパー(class template) | C++26 |
+| [`function_ref`](functional/function_ref.md) | 関数・関数オブジェクトの多相参照ラッパー(class template) | C++26 |
 
 
 ## 統一的な関数呼び出し
diff --git a/reference/functional/copyable_function.md b/reference/functional/copyable_function.md
@@ -36,7 +36,6 @@ namespace std {
 
 
 ## メンバ関数
-### 構築・破棄
 
 | 名前            | 説明           | 対応バージョン |
 |-----------------|----------------|----------------|
@@ -235,8 +234,9 @@ int main()
 
 
 ## 関連項目
-- [`function`](function.md)
-- [`move_only_function`](move_only_function.md)
+- C++11 [`function`](function.md)
+- C++23 [`move_only_function`](move_only_function.md)
+- C++26 [`function_ref`](function_ref.md)
 
 
 ## 参照
diff --git a/reference/functional/function.md b/reference/functional/function.md
@@ -117,7 +117,7 @@ int main()
 ## 関連項目
 - C++23 [`move_only_function`](move_only_function.md)
 - C++26 [`copyable_function`](copyable_function.md)
-- C++26 [`function_ref`](function_ref.md.nolink)
+- C++26 [`function_ref`](function_ref.md)
 
 
 ## 参照
diff --git a/reference/functional/function_ref.md b/reference/functional/function_ref.md
@@ -0,0 +1,119 @@
+# function_ref
+* functional[meta header]
+* class template[meta id-type]
+* std[meta namespace]
+* cpp26[meta cpp]
+
+```cpp
+namespace std {
+  template<class... S>
+  class function_ref; // 宣言のみ
+
+  template<class R, class... ArgTypes>
+  class function_ref<R(ArgTypes...) /*cv*/ noexcept(/*noex*/)>;
+}
+```
+
+## 概要
+`function_ref`クラステンプレートは、パラメータの型リスト`ArgTypes...`、戻り値の型`R`に合致する、あらゆる関数ポインタ、関数オブジェクト、メンバ関数ポインタ、メンバ変数ポインタを参照できるクラスである。
+
+下記全ての組み合わせ（4種類）に対して、クラステンプレートの部分特殊化が提供される。
+
+- CV修飾子 *cv* : `const`, CV修飾無し
+- noexcept例外指定 *noex* : `true`, `false`
+
+`function_ref`クラステンプレートのあらゆる特殊化は[トリビアルコピー可能](/reference/type_traits/is_trivially_copyable.md)である。
+
+
+### `function`ファミリとの比較
+類似機能を提供する[`function`](function.md), [`move_only_function`](move_only_function.md), [`copyable_function`](copyable_function.md)とは異なり、`function_ref`は下記の特徴をもつ。
+
+- 対象の所有権を管理しない軽量ラッパーとして実装される。
+    - ポインタ2個のオブジェクトサイズで実装可能。
+- 構築時に必ず呼び出し対象を指定する必要がある。デフォルト構築不可。
+    - `operator bool`を提供しない。
+- メンバ関数・メンバ変数を参照する場合は、[`std::nontype`](/reference/utility/nontype_t.md)タグを利用する。
+    - 対象オブジェクトの束縛タイミングは、構築時または呼び出し時のいずれもサポートする。
+- ダングリング(dangling)参照を避けるため、左辺値(lvalue)のみを取り扱う。
+
+
+## メンバ関数
+
+| 名前            | 説明           | 対応バージョン |
+|-----------------|----------------|----------------|
+| [`(constructor)`](function_ref/op_constructor.md.nolink) | コンストラクタ      | C++26 |
+| (destructor) | デストラクタ | C++26 |
+| [`operator=`](function_ref/op_assign.md.nolink) | 代入演算子 | C++26 |
+| [`operator()`](function_ref/op_call.md.nolink) | 関数呼び出し | C++26 |
+
+
+## 推論補助
+
+| 名前 | 説明 | 対応バージョン |
+|-----------------|----------------|----------------|
+| [`(deduction_guide)`](function_ref/op_deduction_guide.md.nolink) | クラステンプレートの推論補助 | C++26 |
+
+
+## 例
+### 例1: 基本の使い方
+```cpp example
+#include <functional>
+#include <iostream>
+#include <utility>  // nontype
+
+// 呼び出し可能な何かを受け取る高階関数
+int hof(std::function_ref<int(int)> fn)
+{
+  return fn(2);
+}
+
+int add(int x) { return x + 1; }
+
+struct Calc {
+  int x_;
+  int eval(int y) {
+    return x_ * y;
+  }
+};
+
+int main()
+{
+  // 通常関数を指定
+  std::cout << hof(add) << std::endl;
+  // ラムダ式を指定
+  std::cout << hof([](int x) { return x * 2; }) << std::endl;
+
+  // オブジェクト束縛済みメンバ関数を指定
+  Calc obj{ 3 };
+  std::cout << hof({std::nontype<&Calc::eval>, obj}) << std::endl;
+}
+```
+* std::function_ref[color ff0000]
+* std::nontype[link /reference/utility/nontype_t.md]
+
+#### 出力
+```
+3
+4
+6
+```
+
+## バージョン
+### 言語
+- C++26
+
+### 処理系
+- [Clang](/implementation.md#clang): ??
+- [GCC](/implementation.md#gcc): ??
+- [ICC](/implementation.md#icc): ??
+- [Visual C++](/implementation.md#visual_cpp): ??
+
+
+## 関連項目
+- C++11 [`function`](function.md)
+- C++23 [`move_only_function`](move_only_function.md)
+- C++26 [`copyable_function`](copyable_function.md)
+
+
+## 参照
+- [P0792R14 `function_ref`: a type-erased callable reference](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p0792r14.html)
diff --git a/reference/functional/move_only_function.md b/reference/functional/move_only_function.md
@@ -37,7 +37,6 @@ namespace std {
 
 
 ## メンバ関数
-### 構築・破棄
 
 | 名前            | 説明           | 対応バージョン |
 |-----------------|----------------|----------------|
@@ -236,7 +235,9 @@ int main()
 
 
 ## 関連項目
-- [`function`](function.md)
+- C++11 [`function`](function.md)
+- C++26 [`copyable_function`](copyable_function.md)
+- C++26 [`copyable_function`](copyable_function.md)
 
 
 ## 参照
diff --git a/reference/utility.md b/reference/utility.md
@@ -98,6 +98,14 @@
 | [`in_place_index`](utility/in_place_index_t.md)   | 指定位置にある要素型のコンストラクタ引数を直接受け取って構築するためのタグ値 (constant variable) | C++17 |
 
 
+## 非型引数
+
+| 名前 | 説明 | 対応バージョン |
+|------|------|----------------|
+| [`nontype_t`](utility/nontype_t.md) | 非型引数を表現するためのタグ型 (class template) | C++26 |
+| [`nontype`](utility/nontype_t.md)   | 非型引数を表現するためのタグ値 (variable template) | C++26 |
+
+
 ## コンパイル時の整数シーケンス
 
 | 名前 | 説明 | 対応バージョン |
diff --git a/reference/utility/nontype_t.md b/reference/utility/nontype_t.md
@@ -0,0 +1,74 @@
+# nontype_t
+* utility[meta header]
+* std[meta namespace]
+* class template[meta id-type]
+* cpp26[meta cpp]
+
+```cpp
+namespace std {
+  template <auto V>
+  struct nontype_t {
+    explicit nontype_t() = default;
+  };
+
+  template <auto V> constexpr nontype_t<V> nontype{};
+}
+```
+
+## 概要
+`nontype_t`クラスは、オーバーロードのための空クラスである。
+
+標準ライブラリの特定機能において、非型引数をテンプレートパラメータとして受け取って構築するための関数オーバーロードを定義するためにある。
+
+
+## 備考
+デフォルトコンストラクタに`explicit`が付いているのは、`nontype_t<F> x = {};`のように`=`付きの波カッコ初期化を禁止するためである。ユーザーは通常、`nontype_t`型の変数テンプレートとして事前定義されている`nontype`を使用すればよいので、問題にはならない。
+
+
+## 例
+```cpp example
+#include <functional>
+#include <print>
+#include <utility>
+
+void call(std::function_ref<void()> fn)
+{
+  fn();
+}
+
+struct Dog {
+  void cry() { std::println("Bow-wow"); }
+};
+
+int main()
+{
+  Dog dog;
+  call({std::nontype<&Dog::cry>, dog});
+}
+```
+* std::nontype[color ff0000]
+* std::function_ref[link /reference/functional/function_ref.md]
+
+### 出力
+```
+Bow-wow
+```
+
+
+## バージョン
+### 言語
+- C++26
+
+### 処理系
+- [Clang](/implementation.md#clang): ??
+- [GCC](/implementation.md#gcc): ??
+- [ICC](/implementation.md#icc): ??
+- [Visual C++](/implementation.md#visual_cpp): ??
+
+
+## 関連項目
+- [`copyable_function`](/reference/functional/copyable_function.md)
+
+
+## 参照
+- [P0792R14 `function_ref`: a type-erased callable reference](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p0792r14.html)
