最終更新日時: 2025年09月07日 14時40分09秒 (JST)
Raclamusi が更新

履歴 編集

function template
<memory>

# std::allocator::allocate_at_least(C++23)

    namespace std {
      [[nodiscard]] constexpr allocation_result<T*>
        allocate_at_least(size_t n); // (1) C++23
    }

## 概要

指定した要素数以上のメモリを確保する。

多くのメモリアロケータはメモリ確保時に指定されたサイズちょうどではなく、少し大きなサイズを確保する。この関数は、確保されたメモリへのポインタに加えて、実際に確保されたメモリサイズを取得できる。

## 適格要件

- 型`T`が不完全型ではないこと

## 戻り値

確保された配列の先頭要素へのポインタを`ptr`、`n`以上である実際に確保された要素数を`count`として、

    return allocation_result<T*>{ptr, count};

## 例外

- `std::numeric_limits<std::size_t>::max() / sizeof(T) < n`である場合、`std::bad_array_new_length`を送出する
- メモリを確保できなかった場合、`std::bad_alloc`を送出する

## 備考

- 配列のメモリは`::operator new`を呼び出すことで確保できるが、その関数がいつ・どれくらいの頻度で呼び出されるかは未規定
- この関数は配列オブジェクトの生存期間を開始するが、配列要素の生存期間は開始しない

## 例

    #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);
    }

### 出力例

    allocation count:4 bytes:16

## バージョン

### 言語

- C++23

### 処理系

- Clang: 19 ❌
- GCC: 14 ❌
- Visual C++: 2022 Update 10 ❌

## 関連項目

- `std::allocation_result`
- `std::allocator_traits::allocate_at_least()`

## 参照

- P0401R6 Providing size feedback in the Allocator interface