<memory> : C++23対応としてallocate_at_leastを追加 (close #1053)

Author: faithandbrave

lang/cpp23.md

@@ -128,7 +128,9 @@ C++23とは、2023年中に改訂される予定の、C++バージョンの通
 ### コンテナ
 - [`std::stack`](/reference/stack/stack.md)と[`std::queue`](/reference/queue/queue.md)に、イテレータのペアをとるコンストラクタを追加
 - `auto v = std::vector(v, alloc);`のようなアロケータ引数をともなう場合のクラステンプレートのテンプレート引数推論が動作しなかったため、各コンテナクラスのコンストラクタにおけるアロケータパラメータの型を`const Allocator&`から`const` [`std::type_identity_t`](/reference/type_traits/type_identity.md)`<Allocator>&`に修正
-- N要素のメモリアロケート時にアロケータが実際にどれくらいのメモリを確保したかを得られるインタフェースとして、[`std::allocator`](/reference/memory/allocator.md)クラスに、[`allocate_at_least()`](/reference/memory/allocator/allocate_at_least.md.nolink)メンバ関数を追加
+- N要素のメモリアロケート時にアロケータが実際にどれくらいのメモリを確保したかを得られるインタフェースとして、
+    - [`std::allocator`](/reference/memory/allocator.md)クラスに、[`allocate_at_least()`](/reference/memory/allocator/allocate_at_least.md)メンバ関数を追加
+    - [`std::allocate_at_least()`](/reference/memory/allocate_at_least.md)関数を追加
 - [`std::pair`](/reference/utility/pair.md)の転送コンストラクタにデフォルトテンプレート引数を追加することで、`{}`のような型推論ができない引数を渡した場合でも完全転送が行われるよう修正
 - 順序付き連想コンテナの要素削除の処理について、一時オブジェクトのコストを抑える拡張が行われた
     - [`std::map::erase()`](/reference/map/map/erase.md)

reference/memory.md

@@ -14,6 +14,8 @@
 |--------------------------------------------------|--------------------------------------------|-------|
 | [`allocator`](memory/allocator.md)             | メモリアロケータの標準実装(class template) | |
 | [`allocator_traits`](memory/allocator_traits.md) | アロケータクラスへの間接的なアクセス(class template) | C++11 |
+| [`allocation_result`](memory/allocation_result.md) | [`allocate_at_least()`](memory/allocate_at_least.md)関数の戻り値型 | C++23 |
+| [`allocate_at_least`](memory/allocate_at_least.md) | 指定した要素数以上のメモリを確保する | C++23 |
 | [`allocator_arg_t`](memory/allocator_arg_t.md) | アロケータを引数として渡す際の、オーバーロード解決のためのタグ(class) | C++11 |
 | [`allocator_arg`](memory/allocator_arg_t.md) | アロケータを引数として渡す際の、オーバーロード解決のためのタグ(constant value) | C++11 |
 | [`uses_allocator`](memory/uses_allocator.md) | 型`T`がアロケータを使用するか調べる | C++11 |

reference/memory/allocate_at_least.md

@@ -0,0 +1,70 @@
+# alloacte_at_least
+* memory[meta header]
+* std[meta namespace]
+* function template[meta id-type]
+* cpp23[meta cpp]
+
+```cpp
+namespace std {
+  template <class Allocator>
+  [[nodiscard] constexpr
+  allocation_result<typename allocator_traits<Allocator>::pointer>
+    allocate_at_least(Allocator& a, size_t n); // (1) C++23
+}
+```
+* allocation_result[link /reference/memory/allocation_result.md]
+* allocator_traits[link /reference/memory/allocator_traits.md]
+
+## 概要
+指定した要素数以上のメモリを確保する。
+
+多くのメモリアロケータはメモリ確保時に指定されたサイズちょうどではなく、少し大きなサイズを確保する。この関数は、確保されたメモリへのポインタに加えて、実際に確保されたメモリサイズを取得できる。
+
+
+## 戻り値
+式`a.allocate_at_least(n)`が妥当である場合、それを呼び出して返す。そうでなければ、`{a.allocate(n), n}`を返す。
+
+
+## 例
+```cpp example
+#include <iostream>
+#include <memory>
+
+int main() {
+  std::allocator<int> alloc;
+
+  std::allocation_result<int*> r = std::allocate_at_least(alloc, 3);
+  std::cout << "allocation count:" << r.count
+            << " bytes:" << sizeof(int) * r.count
+            << std::endl;
+
+  alloc.deallocate(r.ptr, r.count);
+}
+```
+* std::allocate_at_least[color ff0000]
+* std::allocator[link /reference/memory/allocator.md]
+* std::allocation_result[link /reference/memory/allocation_result.md]
+* alloc.deallocate[link /reference/memory/allocator/deallocate.md]
+
+### 出力例
+```
+allocation count:4 bytes:16
+```
+
+## バージョン
+### 言語
+- C++23
+
+### 処理系
+- [Clang](/implementation.md#clang): 19 [mark noimpl]
+- [GCC](/implementation.md#gcc): 14 [mark noimpl]
+- [Visual C++](/implementation.md#visual_cpp): 2022 Update 10 [mark noimpl]
+
+
+## 関連項目
+- [`std::allocation_result`](/reference/memory/allocation_result.md)
+- [`std::allocator`](allocator.md)`::`[`allocate_at_least()`](allocator/allocate_at_least.md)
+
+
+## 参照
+- [P0401R6 Providing size feedback in the Allocator interface](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p0401r6.html)

reference/memory/allocation_result.md

@@ -0,0 +1,42 @@
+# allocation_result
+* memory[meta header]
+* std[meta namespace]
+* class[meta id-type]
+* cpp23[meta cpp]
+
+```cpp
+namespace std {
+  template <class Pointer>
+  struct allocation_result {
+    Pointer ptr;
+    std::size_t count;
+  };
+}
+```
+
+## 概要
+`std::allocation_result`は、[`std::allocate_at_least()`](allocate_at_least.md)関数の戻り値型であり、以下の要素をもつ：
+
+| 変数名  | 説明 |
+|---------|------|
+| `ptr`   | 確保されたメモリの先頭を指すポインタ |
+| `count` | 実際に確保された要素数 |
+
+
+## バージョン
+### 言語
+- C++23
+
+### 処理系
+- [Clang](/implementation.md#clang): 19 [mark noimpl]
+- [GCC](/implementation.md#gcc): 14 [mark noimpl]
+- [Visual C++](/implementation.md#visual_cpp): 2022 Update 10 [mark noimpl]
+
+
+## 関連項目
+- [`std::allocate_at_least()`](allocate_at_least.md)
+- [`std::allocator`](allocator.md)`::`[`allocate_at_least()`](allocator/allocate_at_least.md)
+
+
+## 参照
+- [P0401R6 Providing size feedback in the Allocator interface](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p0401r6.html)

reference/memory/allocator.md

@@ -43,6 +43,7 @@ C++11から：
 | [`(destructor)`](allocator/op_destructor.md) | デストラクタ                              | |
 | [`operator=`](allocator/op_assign.md)     | 代入演算子                                   | |
 | [`allocate`](allocator/allocate.md)       | メモリを確保する                             | |
+| [`allocate_at_least`](allocator/allocate_at_least.md) | 指定した要素数以上のメモリを確保する | C++23 |
 | [`deallocate`](allocator/deallocate.md)   | メモリを解放する                             | |
 | [`address`](allocator/address.md)         | 変数のアドレスを取得する                     | C++17から非推奨<br/> C++20で削除 |
 | [`max_size`](allocator/max_size.md)       | 一度に確保可能なメモリの最大サイズを取得する | C++17から非推奨<br/> C++20で削除 |

reference/memory/allocator/allocate.md

@@ -59,6 +59,10 @@ int main()
 ```
 
 
+## 関連項目
+- [`allocate_at_least()`](allocate_at_least.md)
+
+
 ## 参照
 - [P0174R2 Deprecating Vestigial Library Parts in C++17](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0174r2.html)
 - [P0600R1 `[[nodiscard]]` in the Library](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0600r1.pdf)

reference/memory/allocator/allocate_at_least.md

@@ -0,0 +1,86 @@
+# alloacte_at_least
+* memory[meta header]
+* std[meta namespace]
+* allocator[meta class]
+* function template[meta id-type]
+* cpp23[meta cpp]
+
+```cpp
+namespace std {
+  [[nodiscard] constexpr allocation_result<T*>
+    allocate_at_least(size_t n); // (1) C++23
+}
+```
+* allocation_result[link /reference/memory/allocation_result.md]
+
+## 概要
+指定した要素数以上のメモリを確保する。
+
+多くのメモリアロケータはメモリ確保時に指定されたサイズちょうどではなく、少し大きなサイズを確保する。この関数は、確保されたメモリへのポインタに加えて、実際に確保されたメモリサイズを取得できる。
+
+
+## 適格要件
+- 型`T`が不完全型ではないこと
+
+
+## 戻り値
+確保された配列の先頭要素へのポインタを`ptr`、`n`以上である実際に確保された要素数を`count`として、
+
+```cpp
+return allocation_result<T*>{ptr, count};
+```
+* allocation_result[link /reference/memory/allocation_result.md]
+
+
+## 例外
+- [`std::numeric_limits`](/reference/limits/numeric_limits.md)`<`[`std::size_t`](/reference/cstddef/size_t.md)`>::`[`max()`](/reference/limits/numeric_limits/max.md) `/ sizeof(T) < n`である場合、[`std::bad_array_new_length`](/reference/new/bad_array_new_length.md)を送出する
+- メモリを確保できなかった場合、[`std::bad_alloc`](/reference/new/bad_alloc.md)を送出する
+
+
+## 備考
+- 配列のメモリは`::operator new`を呼び出すことで確保できるが、その関数がいつ・どれくらいの頻度で呼び出されるかは未規定
+- この関数は配列オブジェクトの生存期間を開始するが、配列要素の生存期間は開始しない
+
+
+## 例
+```cpp example
+#include <iostream>
+#include <memory>
+
+int main() {
+  std::allocator<int> alloc;
+
+  std::allocation_result<int*> r = alloc.allocate_at_least(3);
+  std::cout << "allocation count:" << r.count
+            << " bytes:" << sizeof(int) * r.count
+            << std::endl;
+
+  alloc.deallocate(r.ptr, r.count);
+}
+```
+* alloc.allocate_at_least[color ff0000]
+* std::allocation_result[link /reference/memory/allocation_result.md]
+* alloc.deallocate[link /reference/memory/allocator/deallocate.md]
+
+### 出力例
+```
+allocation count:4 bytes:16
+```
+
+## バージョン
+### 言語
+- C++23
+
+### 処理系
+- [Clang](/implementation.md#clang): 19 [mark noimpl]
+- [GCC](/implementation.md#gcc): 14 [mark noimpl]
+- [Visual C++](/implementation.md#visual_cpp): 2022 Update 10 [mark noimpl]
+
+
+## 関連項目
+- [`std::allocation_result`](/reference/memory/allocation_result.md)
+- [`std::allocate_at_least()`](/reference/memory/allocate_at_least.md)
+
+
+## 参照
+- [P0401R6 Providing size feedback in the Allocator interface](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p0401r6.html)

reference/memory/allocator/deallocate.md

@@ -13,8 +13,14 @@ constexpr void deallocate(pointer p, size_type n);      // C++20 から
 メモリを解放する。
 
 
-## 要件
-`p`は、[`allocate()`](allocate.md)によって確保されたポインタ値であること。`n`は、アロケートされた`p`のサイズと同じであること。
+## 事前条件
+- C++20まで
+    - `p`は、[`allocate()`](allocate.md)によって確保されたポインタ値であること。`n`は、アロケートされた`p`のサイズと同じであること
+- C++23以降
+    - `p`が[`allocate_at_least()`](allocate_at_least.md)によって確保されたポインタ値である場合、[`allocate_at_least()`](allocate_at_least.md)の戻り値を`ret`、その呼び出しで要求されたサイズを`req`として、
+        - `p`は`ret.ptr`と等しいこと
+        - `n`は`req <= n <= ret.count`となる値であること
+    - そうでなければ、`p`は、[`allocate()`](allocate.md)によって確保されたポインタ値であること。`n`は、アロケートされた`p`のサイズと同じであること
 
 
 ## 効果
@@ -51,3 +57,5 @@ int main()
 ## 参照
 - [C++14 サイズ付きデアロケーション](/lang/cpp14/sized_deallocation.md)
 - [P0784R7 More constexpr containers](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0784r7.html)
+- [P0401R6 Providing size feedback in the Allocator interface](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p0401r6.html)
+    - C++23で`allocate_at_least()`関数が導入されたことにより、この関数の事前条件として、渡される値にその関数の戻り値であることも考慮された