Skip to content

Commit 284b03c

Browse files
yohhoyyohhoy
committed
generator: 説明増補
- iteratorクラスメンバ個別解説を追加 - promise_type::yield_value説明を改善 - 説明用メンバ変数名を明記 - 他調整
1 parent f001592 commit 284b03c

File tree

14 files changed

+264
-51
lines changed

14 files changed

+264
-51
lines changed

‎reference/generator/generator.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ namespace std {
1818
}
1919
```
2020
* ranges::view_interface[link /reference/ranges/view_interface.md]
21-
21+
* polymorphic_allocator[link /reference/memory_resource/polymorphic_allocator.md]
2222
2323
## 概要
2424
`generator`クラステンプレートは、[コルーチン](/lang/cpp20/coroutines.md)の評価により生成される要素列のビュー(view)を表現する。
@@ -29,9 +29,9 @@ namespace std {
2929
ジェネレータコルーチンでは`co_await`式を利用できない。
3030
3131
ジェネレータコルーチンは遅延評価される。
32-
ジェネレータコルーチンが返す`generator`オブジェクトを利用するコード（以下、ジェネレータ利用側）において、先頭要素を指す[イテレータ](generator/iterator.md)を取得する([`begin`](generator/begin.md))、またはイテレータのインクリメント操作を行う(`operator++`)までジェネレータコルーチンは再開(resume)されない。
32+
ジェネレータコルーチンが返す`generator`オブジェクトを利用するコード（以下、ジェネレータ利用側）において、先頭要素を指す[イテレータ](generator/iterator.md)を取得する([`begin`](generator/begin.md))、またはイテレータの[インクリメント操作](generator/iterator/op_increment.md)を行うまでジェネレータコルーチンは再開(resume)されない。
3333
ジェネレータコルーチン本体処理において`co_yield`式に到達すると、生成値を保持してから中断(suspend)しジェネレータ利用側へと制御を戻す。
34-
ジェネレータ利用側ではイテレータの間接参照(単項`operator*`)を行うことで、ジェネレータによる生成値を取得する。
34+
ジェネレータ利用側では[イテレータの間接参照](generator/iterator/op_deref.md)を行うことで、ジェネレータによる生成値を取得する。
3535
3636
3737
### 説明用メンバ
@@ -41,10 +41,10 @@ namespace std {
4141
- `reference` : [`conditional_t`](/reference/type_traits/conditional.md)`<`[`is_void_v`](/reference/type_traits/is_void.md)`<V>, Ref&&, Ref>`
4242
- [`iterator`](generator/iterator.md) : ジェネレータが返すイテレータ型。
4343
44-
`generator`および[`promise_type`](generator/promise_type.md)の動作説明のため、下記の説明用メンバを用いる。
44+
`generator`および[`promise_type`](generator/promise_type.md)と[`iterator`](generator/iterator.md)の動作説明のため、下記の説明用メンバを用いる。
4545
46-
- [`coroutine_handle`](/reference/coroutine/coroutine_handle.md)`<`[`promise_type`](generator/promise_type.md)`>` : コルーチンハンドル(`coroutine_`)
47-
- [`unique_ptr`](/reference/memory/unique_ptr.md)`<`[`stack`](/reference/stack/stack.md)`<`[`coroutine_handle<>`](/reference/coroutine/coroutine_handle.md)`>>`: アクティブスタック(`active_`)
46+
- `coroutine_` : [`coroutine_handle`](/reference/coroutine/coroutine_handle.md)`<`[`promise_type`](generator/promise_type.md)`>`型のコルーチンハンドル
47+
- `active_` : [`unique_ptr`](/reference/memory/unique_ptr.md)`<`[`stack`](/reference/stack/stack.md)`<`[`coroutine_handle<>`](/reference/coroutine/coroutine_handle.md)`>>`型のアクティブスタック
4848
4949
5050
### 第1テンプレートパラメータ`Ref`の概要

‎reference/generator/generator/begin.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,15 +16,16 @@ iterator begin();
1616

1717

1818
## 事前条件
19-
ジェネレータコルーチンは[初期サスペンドポイント](/lang/cpp20/coroutines.md)で中断している。
19+
ジェネレータコルーチンは[初期サスペンドポイント](promise_type/initial_suspend.md)で中断している。
2020

2121

2222
## 効果
23-
ジェネレータコルーチンを再開(resume)する。
23+
[コルーチンハンドル](/reference/coroutine/coroutine_handle.md)をアクティブスタック`*active_`にpushし、ジェネレータコルーチンを[再開(resume)](/reference/coroutine/coroutine_handle/resume.md)する。
2424

2525

2626
## 戻り値
2727
ジェネレータコルーチンに対応する[`iterator`](iterator.md)オブジェクト。
28+
同`iterator`オブジェクトの説明用メンバ`coroutine_`は自ジェネレータコルーチンを参照する。
2829

2930

3031
## 備考
@@ -40,3 +41,7 @@ iterator begin();
4041
- [GCC](/implementation.md#gcc): ??
4142
- [ICC](/implementation.md#icc): ??
4243
- [Visual C++](/implementation.md#visual_cpp): ??
44+
45+
46+
## 関連項目
47+
- [`generator::iterator::operator++`](iterator/op_increment.md)

‎reference/generator/generator/iterator.md‎

Lines changed: 18 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -8,47 +8,43 @@
88
namespace std {
99
template<class Ref, class V, class Allocator>
1010
class generator<Ref, V, Allocator>::iterator {
11-
public:
12-
using value_type = value;
13-
using difference_type = ptrdiff_t;
14-
15-
iterator(iterator&& other) noexcept;
16-
iterator& operator=(iterator&& other) noexcept;
17-
18-
reference operator*() const noexcept(is_nothrow_copy_constructible_v<reference>);
19-
iterator& operator++();
20-
void operator++(int);
21-
22-
friend bool operator==(const iterator& i, default_sentinel_t);
11+
...
2312
};
2413
}
2514
```
2615
* generator[link ../generator.md]
27-
* value[link ../generator.md]
28-
* reference[link ../generator.md]
29-
* is_nothrow_copy_constructible_v[link /reference/type_traits/is_nothrow_copy_constructible.md]
30-
3116
3217
## 概要
3318
[`generator`](../generator.md)に対応する説明専用のイテレータ型。
3419
20+
`iterator`の動作説明のため、下記の説明用メンバを用いる。
21+
22+
- `coroutine_` : [`coroutine_handle`](/reference/coroutine/coroutine_handle.md)`<`[`promise_type`](promise_type.md)`>`型のコルーチンハンドル
23+
3524
3625
## メンバ関数
3726
### 構築・破棄
3827
3928
| 名前 | 説明 | 対応バージョン |
4029
|-----------------|----------------|----------------|
41-
| `(constructor)` | コンストラクタ | C++23 |
42-
| `(destructor)` | デストラクタ | C++23 |
43-
| `operator=` | 代入演算子 | C++23 |
30+
| [`(constructor)`](iterator/op_constructor.md) | コンストラクタ | C++23 |
31+
| `(destructor)` | デストラクタ | C++23 |
32+
| [`operator=`](iterator/op_assign.md) | 代入演算子 | C++23 |
4433
4534
### イテレータ
4635
4736
| 名前 | 説明 | 対応バージョン |
4837
|-----------------|----------------|----------------|
49-
| `operator*()` | 間接参照 | C++23 |
50-
| `operator++()` | 前置インクリメント | C++23 |
51-
| `operator++(int)` | 後置インクリメント | C++23 |
38+
| [`operator*`](iterator/op_deref.md) | 間接参照 | C++23 |
39+
| [`operator++`](iterator/op_increment.md) | インクリメント | C++23 |
40+
41+
### 比較演算子
42+
43+
| 名前 | 説明 | 対応バージョン |
44+
|-----|-----|-----|
45+
| [`operator==`](iterator/op_equal.md) | 等値比較 | C++23 |
46+
| [`operator!=`](iterator/op_equal.md) | 非等値比較 (`==`により使用可能) | C++23 |
47+
5248
5349
## メンバ型
5450
@@ -57,13 +53,6 @@ namespace std {
5753
| `value_type` | 要素型となる説明用の型[`value`](../generator.md) | C++23 |
5854
| `difference_type` | 2つの値の差を表す整数型`ptrdiff_t` | C++23 |
5955
60-
### 比較演算子
61-
62-
| 名前 | 説明 | 対応バージョン |
63-
|-----|-----|-----|
64-
| `bool operator==(const iterator&, default_sentinel_t)` | 等値比較 | C++23 |
65-
| `bool operator!=(const iterator&, default_sentinel_t)` | 非等値比較 (`==`により使用可能) | C++23 |
66-
6756
6857
## バージョン
6958
### 言語

‎reference/generator/generator/iterator/op_assign.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# operator=
2+
* generator[meta header]
3+
* function[meta id-type]
4+
* std[meta namespace]
5+
* generator::iterator[meta class]
6+
* cpp23[meta cpp]
7+
8+
```cpp
9+
iterator& operator=(iterator&& other) noexcept;
10+
```
11+
12+
## 概要
13+
ジェネレータコルーチンのイテレータをムーブ代入する。
14+
15+
16+
## 効果
17+
```cpp
18+
coroutine_ = exchange(other.coroutine_, {});
19+
```
20+
* exchange[link /reference/utility/exchange.md]
21+
22+
23+
## 戻り値
24+
`*this`
25+
26+
27+
## 例外
28+
投げない
29+
30+
31+
## バージョン
32+
### 言語
33+
- C++23
34+
35+
### 処理系
36+
- [Clang](/implementation.md#clang):
37+
- [GCC](/implementation.md#gcc):
38+
- [ICC](/implementation.md#icc):
39+
- [Visual C++](/implementation.md#visual_cpp):

‎reference/generator/generator/iterator/op_constructor.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# コンストラクタ
2+
* generator[meta header]
3+
* function[meta id-type]
4+
* std[meta namespace]
5+
* generator::iterator[meta class]
6+
* cpp23[meta cpp]
7+
8+
```cpp
9+
iterator(iterator&& other) noexcept;
10+
```
11+
12+
## 概要
13+
ジェネレータコルーチンのイテレータをムーブ構築する。
14+
15+
ジェネレータコルーチンの有効なイテレータは[`generator::begin()`](../begin.md)によって構築される。
16+
17+
18+
## 効果
19+
説明用メンバ`coroutine_`を[`exchange`](/reference/utility/exchange.md)`(other.coroutine_, {})`で初期化する。
20+
21+
22+
## 例外
23+
投げない
24+
25+
26+
## バージョン
27+
### 言語
28+
- C++23
29+
30+
### 処理系
31+
- [Clang](/implementation.md#clang):
32+
- [GCC](/implementation.md#gcc):
33+
- [ICC](/implementation.md#icc):
34+
- [Visual C++](/implementation.md#visual_cpp):
35+
36+
37+
## 関連項目
38+
- [`generator::begin()`](../begin.md)

‎reference/generator/generator/iterator/op_deref.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# operator*
2+
* generator[meta header]
3+
* function[meta id-type]
4+
* std[meta namespace]
5+
* generator::iterator[meta class]
6+
* cpp23[meta cpp]
7+
8+
```cpp
9+
reference operator*() const
10+
noexcept(is_nothrow_copy_constructible_v<reference>);
11+
```
12+
* reference[link ../../generator.md]
13+
* is_nothrow_copy_constructible_v[link /reference/type_traits/is_nothrow_copy_constructible.md]
14+
15+
## 概要
16+
ジェネレータコルーチンにより生成された値にアクセスする。
17+
18+
19+
## 事前条件
20+
ある[`generator`](../../generator.md)オブジェクト`x`において`coroutine_`がアクティブスタック`*x.active_`に含まれており、かつアクティブスタックのトップ(`x.active_->top()`)がPromiseオブジェクト`p`をもつ中断されたコルーチンを指すこと。
21+
22+
23+
## 効果
24+
以下と等価
25+
26+
```cpp
27+
return static_cast<reference>(*p.value_);
28+
```
29+
* p.value_[link ../promise_type.md]
30+
31+
32+
## 例外
33+
[`is_nothrow_copy_constructible_v`](/reference/type_traits/is_nothrow_copy_constructible.md)`<reference>`が`true`のとき、`reference`コピーコンストラクタから送出された例外。
34+
35+
36+
## バージョン
37+
### 言語
38+
- C++23
39+
40+
### 処理系
41+
- [Clang](/implementation.md#clang):
42+
- [GCC](/implementation.md#gcc):
43+
- [ICC](/implementation.md#icc):
44+
- [Visual C++](/implementation.md#visual_cpp):

‎reference/generator/generator/iterator/op_equal.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# operator==
2+
* generator[meta header]
3+
* function[meta id-type]
4+
* std[meta namespace]
5+
* generator::iterator[meta class]
6+
* cpp23[meta cpp]
7+
8+
```cpp
9+
friend bool operator==(const iterator& i, default_sentinel_t);
10+
11+
// operator==により、以下の演算子が使用可能になる
12+
friend bool operator!=(const iterator& i, default_sentinel_t);
13+
```
14+
* default_sentinel_t[link /reference/iterator/default_sentinel_t.md]
15+
16+
## 概要
17+
ジェネレータコルーチンのイテレータが終端まで到達したか否かを判定する。
18+
19+
20+
## 効果
21+
以下と等価
22+
23+
```cpp
24+
return i.coroutine_.done();
25+
```
26+
* done()[link /reference/coroutine/coroutine_handle/done.md]
27+
28+
29+
## バージョン
30+
### 言語
31+
- C++23
32+
33+
### 処理系
34+
- [Clang](/implementation.md#clang):
35+
- [GCC](/implementation.md#gcc):
36+
- [ICC](/implementation.md#icc):
37+
- [Visual C++](/implementation.md#visual_cpp):
38+
39+
40+
## 関連項目
41+
- [`generator::end()`](../end.md)

‎reference/generator/generator/iterator/op_increment.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# operator++
2+
* generator[meta header]
3+
* function[meta id-type]
4+
* std[meta namespace]
5+
* generator::iterator[meta class]
6+
* cpp23[meta cpp]
7+
8+
```cpp
9+
iterator& operator++(); // (1)
10+
void operator++(int); // (2)
11+
```
12+
13+
## 概要
14+
ジェネレータコルーチンを再開し、次の値生成を促す。
15+
16+
17+
## 事前条件
18+
ある[`generator`](../../generator.md)オブジェクト`x`において、`coroutine_`がアクティブスタック`*x.active_`に含まれること。
19+
20+
21+
## 効果
22+
- (1) : 次と等価
23+
```cpp
24+
x.active_->top().resume()
25+
```
26+
* resume()[link /reference/coroutine/coroutine_handle/resume.md]
27+
- (2) : 次と等価: `++*this`
28+
29+
30+
## 戻り値
31+
- (1) : `*this`
32+
33+
34+
## バージョン
35+
### 言語
36+
- C++23
37+
38+
### 処理系
39+
- [Clang](/implementation.md#clang):
40+
- [GCC](/implementation.md#gcc):
41+
- [ICC](/implementation.md#icc):
42+
- [Visual C++](/implementation.md#visual_cpp):
43+
44+
45+
## 関連項目
46+
- [`generator::begin()`](../begin.md)

‎reference/generator/generator/promise_type.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,8 @@ namespace std {
2222
2323
`generator::promise_type`クラスの動作説明のため、以下の説明専用メンバを用いる。
2424
25-
- [`add_pointer_t`](/reference/type_traits/add_pointer.md)`<`[`yielded`](../generator.md)`>`型 : `value_`
26-
- [`exception_ptr`](/reference/exception/exception_ptr.md)型 : `except_`
25+
- `value_` : [`add_pointer_t`](/reference/type_traits/add_pointer.md)`<`[`yielded`](../generator.md)`>`型の生成値
26+
- `except_` : [`exception_ptr`](/reference/exception/exception_ptr.md)型の例外ポインタ
2727
2828
2929
## メンバ関数

‎reference/generator/generator/promise_type/final_suspend.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,16 @@ auto final_suspend() noexcept;
1515

1616

1717
## 事前条件
18-
Promiseオブジェクトが`*this`となる[コルーチンへのハンドル](/reference/coroutine/coroutine_handle.md)が、ある[`generator`オブジェクト](../../generator.md)`x`のアクティブスタックのトップにあること。
18+
Promiseオブジェクトが`*this`となる[コルーチンへのハンドル](/reference/coroutine/coroutine_handle.md)が、ある[`generator`オブジェクト](../../generator.md)`x`のアクティブスタック(`*active_`)のトップにあること。
1919
この関数はコルーチン実行が最終サスペンドポイントに到達したときに呼び出される。
2020

2121

2222
## 戻り値
2323
下記動作を行うメンバ関数をもつ、未規定の型のAwaitableオブジェクト。
2424

25-
コルーチンの中断(suspend)時に、ジェネレータ`x`のアクティブスタックのトップからコルーチンハンドルをpopし、アクティブスタックが空でなければトップ要素が指すコルーチンを再開(resume)する。アクティブスタックが空の場合は、現在の[コルーチンの呼び出し元もしくは再開元(resumer)](/lang/cpp20/coroutines.md)へ制御フローを戻す。
25+
- コルーチンの中断(suspend)時に、ジェネレータ`x`のアクティブスタック(`*x.active_`)のトップからコルーチンハンドルをpopし、
26+
- アクティブスタックが空でなければトップ要素(`*x.active_->top()`)が指すコルーチンを[再開(resume)](/reference/coroutine/coroutine_handle/resume.md)する。
27+
- アクティブスタックが空の場合は、現在の[コルーチンの呼び出し元もしくは再開元(resumer)](/lang/cpp20/coroutines.md)へ制御フローを戻す。
2628

2729

2830
## 例外

0 commit comments

Comments
 (0)