Skip to content

Commit deacb47

Browse files
yohhoyyohhoy
committed
mdspan: (名前付き)要件(#1077)
1 parent d436315 commit deacb47

File tree

9 files changed

+245
-41
lines changed

9 files changed

+245
-41
lines changed

‎reference/mdspan/AccessorPolicy.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# AccsessorPolicy
2+
* named requirement[meta id-type]
3+
* cpp23[meta cpp]
4+
5+
6+
## 概要
7+
AccsessorPolicyは、多次元配列ビュー[`mdspan`](mdspan.md)を介した要素アクセス動作を定義するクラスが満たすべき要件である。
8+
9+
10+
## 要件
11+
AccsessorPolicyを満たす型`A`は
12+
13+
- `A`は[`copyable`](/reference/concepts/copyable.md)のモデルであり、かつ
14+
- [`is_nothrow_move_constructible_v`](/reference/type_traits/is_nothrow_constructible.md)`<A>`は`true`であり、かつ
15+
- [`is_nothrow_move_assignable_v`](/reference/type_traits/is_nothrow_move_assignable.md)`<A>`は`true`であり、かつ
16+
- [`is_nothrow_swappable_v`](/reference/type_traits/is_nothrow_swappable.md)`<A>`は`true`であること
17+
18+
型`A`は下記のメンバ型を持つこと
19+
20+
- `A::element_type` : 要素型
21+
- `A::data_handle_type` : メモリブロックのポインタ型
22+
- `A::reference` : 要素への参照型
23+
- `A::offset_policy` : `offset`適用後のアクセサポリシー
24+
25+
説明用の変数`a`を`(const) A`の値、`p`を`(const) A::data_handle_type`の値、`i`を`size_t`の値としたとき、下記の式が妥当であること
26+
27+
- `a.access(p, i)` : `A::reference`を返す
28+
- `a.offset(p, i)` : `A::offset_policy::data_handle_type`を返す
29+
30+
31+
## `AccessorPolicy`に該当する型
32+
33+
- [`default_accessor`](default_accessor.md)
34+
35+
36+
## バージョン
37+
### 言語
38+
- C++23
39+
40+
41+
## 関連項目
42+
- [`mdspan`](mdspan.md)
43+
44+
45+
## 参照
46+
- [P0009R18 MDSPAN](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p0009r18.html)
47+
- [P2604R0 `mdspan`: rename `pointer` and `contiguous`](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2604r0.html)

‎reference/mdspan/LayoutMapping.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# LayoutMapping
2+
* named requirement[meta id-type]
3+
* cpp23[meta cpp]
4+
5+
6+
## 概要
7+
LayoutMappingは、多次元配列ビュー[`mdspan`](mdspan.md)において多次元インデクスから参照先メモリブロック位置への対応関係（レイアウトマッピング）を定めるクラスが満たすべき要件である。
8+
9+
LayoutMappingを満たすユーザ定義型`layout_custom::mapping<E>`は、常に[レイアウトマッピングポリシー](LayoutMappingPolicy.md)を満たす`layout_custom`の公開メンバ`mapping`クラステンプレートとして定義される。
10+
11+
```cpp
12+
// レイアウトマッピングポリシーs
13+
struct layout_custom {
14+
// レイアウトマッピング
15+
template<class Extents>
16+
class mapping {
17+
public:
18+
using layout_type = layout_custom;
19+
using extent_type = Extents;
20+
// ...
21+
};
22+
};
23+
```
24+
* Extents[link extents.md]
25+
26+
### レイアウトマッピング特性
27+
28+
レイアウトマッピングによる多次元インデクスからメモリブロック位置への変換は、次の3種類の特性によって記述される。
29+
30+
- Unique特性 : 異なる多次元インデクス値であれば、互いに異なる要素位置へと変換される。
31+
- Exhaustive特性 : 取りうる全ての多次元インデクス値に対応する要素位置を考えたとき、アクセスされうる要素位置に隙間が生じない。
32+
- Strided特性 : 要素位置は多次元インデクス値と各次元ストライド幅のみを用いて計算できる。
33+
34+
例えば、多次元配列ビュー[`mdspan`](mdspan.md)のデフォルトレイアウトポリシー[`layout_right`](layout_right.md)は3つの特性を全て満たす。
35+
要素数3×2の2次元配列ビュー`mat3x2`における有効な多次元インデクス値`i,j`は`0,0`, `0,1`, `1,0`, `1,1`, `2,0`, `2,1`の6パターンとなり、それぞれ参照先メモリブロック`a`の要素位置`a[0]`, `a[1]`, `a[2]`, `a[3]`, `a[4]`, `a[5]`に対応する。
36+
37+
```cpp
38+
int a[6] = {0, 1, 2, 3, 4, 5};
39+
40+
using Extents = std::extents<size_t, 3, 2>;
41+
std::mdspan<int, Extents> mat3x2{a};
42+
```
43+
44+
- Unique特性 : 異なる多次元インデクス値は、異なる要素位置に対応する。参照先が重複することはない。
45+
- Exhaustive特性 : 全ての多次元インデクス値に対応する要素位置は連続している。
46+
- Strided特性 : 多次元インデクス値`i,j`に対応する要素位置は、ストライド幅`2,1`を用いて`(i*2+j)*1`と計算できる。
47+
48+
49+
## 要件
50+
LayoutMappingを満たす型`M`は
51+
52+
- `M`は[`copyable`](/reference/concepts/copyable.md)および[`equality_comparable`](/reference/concepts/equality_comparable.md)のモデルであり、かつ
53+
- [`is_nothrow_move_constructible_v`](/reference/type_traits/is_nothrow_constructible.md)`<M>`は`true`であり、かつ
54+
- [`is_nothrow_move_assignable_v`](/reference/type_traits/is_nothrow_move_assignable.md)`<M>`は`true`であり、かつ
55+
- [`is_nothrow_swappable_v`](/reference/type_traits/is_nothrow_swappable.md)`<M>`は`true`であること
56+
57+
型`M`は下記のメンバ型を持つこと
58+
59+
- `M::extents_type` : [`extents`](extents.md)の特殊化
60+
- `M::index_type` : [`extents_type::index_type`](extents.md)
61+
- `M::rank_type` : [`extents_type::rank_type`](extents.md)
62+
- `M::layout_type` : 自クラスを提供する[レイアウトマッピングポリシー型](LayoutMappingPolicy.md)
63+
64+
説明用の変数`m`を`(const) M`の値、パック`i`を[`M::extents_type::rank()`](extents/rank.md)個からなる整数値、変数`r`を多次元の次元番号としたとき、下記の式が妥当であること
65+
66+
- `m.extents()` : `const M​::​extents_type&`型を返すこと。
67+
- `m(i...)` : `M​::​index_type`型を返すこと。
68+
- 戻り値 : 非負整数値
69+
- `m(i...) == m(static_cast<M::index_type>(i)...)` : `true`となること。
70+
- `m.required_span_size()` : `M​::​index_type`型を返すこと。
71+
- 戻り値 : `m.extents()`の多次元インデクス空間サイズが0のときは値`0`。そうでなければ、レイアウトマッピングによりアクセスする可能性のあるメモリブロック範囲の最大値に`1`を足した値。
72+
- `m.is_unique()` : `bool`型を返すこと。
73+
- 戻り値 : Unique特性を満たすときに限り`true`。
74+
- `m.is_exhaustive()` : `bool`型を返すこと。
75+
- 戻り値 : Exhaustive特性を満たすときに限り`true`。
76+
- `m.is_strided()` : `bool`型を返すこと。
77+
- 戻り値 : Strided特性を満たすときに限り`true`。
78+
- `m.stride(r)` : `M​::​index_type`型を返すこと。
79+
- 前提条件 : `m.is_strided() == true`
80+
- 戻り値 : `r`番目次元のストライド幅
81+
- `M::is_always_unique()` : `bool`型の定数式となること。
82+
- 戻り値 : 型`M`のあらゆるオブジェクトにおいてUnique特性を満たすときに`true`。
83+
- `M::is_always_exhaustive()` : `bool`型の定数となること。
84+
- 戻り値 : 型`M`のあらゆるオブジェクトにおいてExhaustive特性を満たすときに`true`。
85+
- `M::is_always_strided()` : `bool`型の定数となること。
86+
- 戻り値 : 型`M`のあらゆるオブジェクトにおいてStrided特性を満たすときに`true`。
87+
88+
89+
## `LayoutMapping`に該当する型
90+
91+
- `layout_left::mapping<E>`
92+
- `layout_right::mapping<E>`
93+
- `layout_stride::mapping<E>`
94+
95+
96+
## バージョン
97+
### 言語
98+
- C++23
99+
100+
101+
## 関連項目
102+
- [`mdspan`](mdspan.md)
103+
- [`extents`](extents.md)
104+
- [LayoutMappingPolicy](LayoutMappingPolicy.md)
105+
106+
107+
## 参照
108+
- [P0009R18 MDSPAN](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p0009r18.html)
109+
- [P2604R0 `mdspan`: rename `pointer` and `contiguous`](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2604r0.html)

‎reference/mdspan/LayoutMappingPolicy.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# LayoutMappingPolicy
2+
* named requirement[meta id-type]
3+
* cpp23[meta cpp]
4+
5+
6+
## 概要
7+
LayoutMappingPolicyは、多次元配列ビュー[`mdspan`](mdspan.md)において多次元インデクスから参照先メモリブロック位置へと変換する[レイアウトマッピング](LayoutMapping.md)を定めるクラスが満たすべき要件である。
8+
9+
LayoutMappingPolicyを満たすユーザ定義`layout_custom`ポリシークラスは、下記の構造で定義される。
10+
11+
```cpp
12+
// レイアウトマッピングポリシー
13+
struct layout_custom {
14+
// レイアウトマッピング
15+
template<class Extents>
16+
class mapping {
17+
public:
18+
using layout_type = layout_custom;
19+
using extent_type = Extents;
20+
// ...
21+
};
22+
};
23+
```
24+
* Extents[link extents.md]
25+
26+
27+
## 要件
28+
LayoutMappingPolicyを満たす型`MP`は
29+
30+
- [`extents`](extents.md)の特殊化`E`に対して`MP::mapping<E>`が有効であり、かつ
31+
- その型`X`が[レイアウトマッピング要件](LayoutMapping.md)を満たし、かつ
32+
- メンバ型`X::layout_type`が型`MP`を表しており、かつ
33+
- メンバ型`X::extent_type`が型`E`を表すこと。
34+
35+
36+
## `LayoutMappingPolicy`に該当する型
37+
38+
- [`layout_left`](layout_left.md)
39+
- [`layout_right`](layout_right.md)
40+
- [`layout_stride`](layout_stride.md)
41+
42+
43+
## バージョン
44+
### 言語
45+
- C++23
46+
47+
48+
## 関連項目
49+
- [`mdspan`](mdspan.md)
50+
- [`extents`](extents.md)
51+
- [LayoutMapping](LayoutMapping.md)
52+
53+
54+
## 参照
55+
- [P0009R18 MDSPAN](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p0009r18.html)

‎reference/mdspan/default_accessor.md‎

Lines changed: 1 addition & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -18,27 +18,7 @@ namespace std {
1818
1919
`default_accessor`は[トリビアルコピー可能](/reference/type_traits/is_trivially_copyable.md)であり、[`semiregular`](/reference/concepts/semiregular.md)のモデルである。
2020
21-
### アクセサポリシー要件
22-
`default_accessor`は、下記のアクセサポリシー要件を満たす。
23-
24-
説明用の型`A`をアクセサポリシーとしたとき
25-
26-
- `A`は[`copyable`](/reference/concepts/copyable.md)のモデルであり、かつ
27-
- [`is_nothrow_move_constructible_v`](/reference/type_traits/is_nothrow_constructible.md)`<A>`は`true`であり、かつ
28-
- [`is_nothrow_move_assignable_v`](/reference/type_traits/is_nothrow_move_assignable.md)`<A>`は`true`であり、かつ
29-
- [`is_nothrow_swappable_v`](/reference/type_traits/is_nothrow_swappable.md)`<A>`は`true`であること
30-
31-
型`A`は下記のメンバ型を持つこと
32-
33-
- `A::element_type` : 要素型
34-
- `A::data_handle_type` : メモリブロックのポインタ型
35-
- `A::reference` : 要素への参照型
36-
- `A::offset_policy` : `offset`適用後のアクセサポリシー
37-
38-
説明用の変数`a`を`(const) A`の値、`p`を`(const) A::data_handle_type`の値、`i`を`size_t`の値としたとき、下記の式が妥当であること
39-
40-
- `a.access(p, i)` : `A::eference`を返す
41-
- `a.offset(p, i)` : `A::offset_policy::data_handle_type`を返す
21+
`default_accessor`は[アクセサポリシー要件](AccessorPolicy.md)を満たす。
4222
4323
4424
## メンバ関数

‎reference/mdspan/layout_left.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,11 @@ namespace std {
1616
* mapping[link mapping.md.nolink]
1717
1818
## 概要
19-
`layout_left`は、多次元配列ビュー[`mdspan`](mdspan.md)に対して、FortranやMatlab多次元配列と互換性のある列優先(column major)レイアウトマッピングを表現するポリシークラスである。
19+
`layout_left`は、多次元配列ビュー[`mdspan`](mdspan.md)に対して、FortranやMatlab多次元配列と互換性のある列優先(column major)[レイアウトマッピング](LayoutMapping.md)を表現するポリシークラスである。
2020
21-
ポリシークラス名の由来は、多次元配列インデクスのうち最左次元が隣接配置（ストライド=1）されるところから来ている。
21+
`layout_left`は、[レイアウトマッピングポリシー要件](LayoutMappingPolicy.md)を満たす[トリビアル型](/reference/type_traits/is_trivial.md)である。
22+
23+
ポリシークラス名の由来は、多次元インデクスのうち最左次元が隣接配置（ストライド=1）され、インデクス次元の左から右の順にストライドが増大するところから来ている。
2224
2325
2426
## メンバ型

‎reference/mdspan/layout_right.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,11 @@ namespace std {
1616
* mapping[link mapping.md.nolink]
1717
1818
## 概要
19-
`layout_right`は、多次元配列ビュー[`mdspan`](mdspan.md)に対して、C/C++多次元配列と互換性のある行優先(row major)レイアウトマッピングを表現するポリシークラスである。
19+
`layout_right`は、多次元配列ビュー[`mdspan`](mdspan.md)に対して、C/C++多次元配列と互換性のある行優先(row major)[レイアウトマッピング](LayoutMapping.md)を表現するポリシークラスである。
2020
21-
ポリシークラス名の由来は、多次元配列インデクスのうち最右次元が隣接配置（ストライド=1）されるところから来ている。
21+
`layout_right`は、[レイアウトマッピングポリシー要件](LayoutMappingPolicy.md)を満たす[トリビアル型](/reference/type_traits/is_trivial.md)である。
22+
23+
ポリシークラス名の由来は、多次元インデクスのうち最右次元が隣接配置（ストライド=1）され、インデクス次元の右から左の順にストライドが増大するところから来ている。
2224
2325
2426
## メンバ型

‎reference/mdspan/layout_stride.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,9 @@ namespace std {
1616
* mapping[link mapping.md.nolink]
1717
1818
## 概要
19-
`layout_stride`は、多次元配列ビュー[`mdspan`](mdspan.md)に対して、次元毎に任意ストライド幅を指定したレイアウトマッピングを表現するポリシークラスである。
19+
`layout_stride`は、多次元配列ビュー[`mdspan`](mdspan.md)に対して、次元毎に任意ストライド幅を指定した[レイアウトマッピング](LayoutMapping.md)を表現するポリシークラスである。
20+
21+
`layout_stride`は、[レイアウトマッピングポリシー要件](LayoutMappingPolicy.md)を満たす[トリビアル型](/reference/type_traits/is_trivial.md)である。
2022
2123
2224
## メンバ型

‎reference/mdspan/mdspan.md‎

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@ namespace std {
1414
class mdspan;
1515
}
1616
```
17+
* Extents[link extents.md]
18+
* LayoutPolicy[link LayoutMappingPolicy.md]
19+
* AccessorPolicy[link AccessorPolicy.md]
1720
* layout_right[link layout_right.md]
1821
* default_accessor[link default_accessor.md]
1922
@@ -31,8 +34,8 @@ namespace std {
3134
### 説明専用メンバ変数
3235
`mdspan`クラスは、下記の説明専用メンバ変数を保持する。
3336
34-
- `acc_` : `accessor_type`型の要素アクセサ
35-
- `map_` : `mapping_type`型のレイアウトマッピング
37+
- `acc_` : `accessor_type`型の[要素アクセサ](AccessorPolicy.md)
38+
- `map_` : `mapping_type`型の[レイアウトマッピング](LayoutMapping.md)
3639
- `ptr_` : `data_handle_type`型のメモリブロックへのハンドル（ポインタ）
3740
3841
@@ -41,7 +44,7 @@ namespace std {
4144
- `Extents`は[`extents`](extents.md)の特殊化であり、かつ
4245
- [`is_same_v`](/reference/type_traits/is_same.md)`<ElementType, typename AccessorPolicy::element_type>`が`true`であること。
4346
44-
`LayoutPolicy`はレイアウトマッピングポリシー要件を満たし、かつ`AccessorPolicy`はアクセサポリシー要件を満たすこと。
47+
`LayoutPolicy`は[レイアウトマッピングポリシー要件](LayoutMappingPolicy.md)を満たし、かつ`AccessorPolicy`は[アクセサポリシー要件](AccessorPolicy.md)を満たすこと。
4548
4649
4750
## メンバ関数
@@ -83,29 +86,29 @@ namespace std {
8386
8487
| 名前 | 説明 | 対応バージョン |
8588
|------|------|----------------|
86-
| `is_always_unique()` | `mapping_type::is_always_unique()` | C++23 |
87-
| `is_always_exhaustive()` | `mapping_type::is_always_exhaustive()` | C++23 |
88-
| `is_always_strided()` | `mapping_type::is_always_strided()` | C++23 |
89-
| `is_unique()` | `map_.is_unique()` | C++23 |
90-
| `is_exhaustive()` | `map_.is_exhaustive()` | C++23 |
91-
| `is_strided()` | `map_.is_strided()` | C++23 |
92-
| `stride(rank_type r)` | `map_.stride(r)` | C++23 |
89+
| `is_always_unique()` | [`mapping_type::is_always_unique()`](LayoutMapping.md) | C++23 |
90+
| `is_always_exhaustive()` | [`mapping_type::is_always_exhaustive()`](LayoutMapping.md) | C++23 |
91+
| `is_always_strided()` | [`mapping_type::is_always_strided()`](LayoutMapping.md) | C++23 |
92+
| `is_unique()` | [`map_.is_unique()`](LayoutMapping.md) | C++23 |
93+
| `is_exhaustive()` | [`map_.is_exhaustive()`](LayoutMapping.md) | C++23 |
94+
| `is_strided()` | [`map_.is_strided()`](LayoutMapping.md) | C++23 |
95+
| `stride(rank_type r)` | [`map_.stride(r)`](LayoutMapping.md) | C++23 |
9396
9497
9598
## メンバ型
9699
97100
| 名前 | 説明 | 対応バージョン |
98101
|------|------|----------------|
99102
| `extents_type` | 多次元配列サイズ型[`Extents`](extents.md) | C++23 |
100-
| `layout_type` | レイアウトマッピングポリシー`LayoutPolicy` | C++23 |
101-
| `accessor_type` | アクセサポリシー`AccessorPolicy` | C++23 |
102-
| `mapping_type` | レイアウトマッピング`LayoutPolicy::mapping<Extents>` | C++23 |
103+
| `layout_type` | [レイアウトマッピングポリシー型`LayoutPolicy`](LayoutMappingPolicy.md) | C++23 |
104+
| `accessor_type` | [アクセサポリシー型`AccessorPolicy`](AccessorPolicy.md) | C++23 |
105+
| `mapping_type` | [レイアウトマッピング型`LayoutPolicy::mapping<Extents>`](LayoutMapping.md) | C++23 |
103106
| `element_type` | 要素型`ElementType` | C++23 |
104107
| `value_type` | 要素の値型[`remove_cv_t`](/reference/type_traits/remove_cvref.md)`<ElementType>` | C++23 |
105108
| `size_type` | [`Extents::size_type`](extents.md) | C++23 |
106109
| `rank_type` | [`Extents::rank_type`](extents.md) | C++23 |
107-
| `pointer` | `AccessorPolicy::pointer` | C++23 |
108-
| `reference` | `AccessorPolicy::reference` | C++23 |
110+
| `pointer` | [`AccessorPolicy::pointer`](AccessorPolicy.md) | C++23 |
111+
| `reference` | [`AccessorPolicy::reference`](AccessorPolicy.md) | C++23 |
109112
110113
111114
## 非メンバ（*Hidden friends*）関数

‎working_style.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ C++11以降対応については対応バージョンを明記します。バー
7171
| derived class | 派生クラス |
7272
| direct base class | 直接基底クラス |
7373
| delegate | 委譲 |
74+
| dynamic extent | (std::mdspanの) 動的要素数 |
7475
| effects | 効果 |
7576
| emplace | 直接構築 |
7677
| empty | 空 |
@@ -94,6 +95,8 @@ C++11以降対応については対応バージョンを明記します。バー
9495
| move | (std::move 的な意味で)ムーブ |
9596
| move assignment | ムーブ代入 |
9697
| move constructor | ムーブコンストラクタ |
98+
| multidimensional index | 多次元インデクス |
99+
| multidimensional index space | 多次元インデクス空間 |
97100
| mutable iterator | 可変イテレータ |
98101
| non-virtual base class | 非仮想基底クラス |
99102
| note | 注 |
@@ -117,6 +120,7 @@ C++11以降対応については対応バージョンを明記します。バー
117120
| rvalue reference | 右辺値参照 |
118121
| sequence container(s) | シーケンスコンテナ |
119122
| signed | 符号付き |
123+
| static extent | (std::mdspanの) 静的要素数 |
120124
| stop request | 停止要求 |
121125
| stop state | 停止状態 |
122126
| Spurious Failure | 見かけ上の失敗<br/> [https://togetter.com/li/430770](https://togetter.com/li/430770) |

0 commit comments

Comments
 (0)