std::vector<T,Allocator>::reserve

 

C++

コンパイラサポート

フリースタンディングとホスト

言語

標準ライブラリ

標準ライブラリヘッダー

名前付き要件

機能テストマクロ (C++20)

言語サポートライブラリ

コンセプトライブラリ (C++20)

診断ライブラリ

メモリ管理ライブラリ

メタプログラミングライブラリ (C++11)

汎用ユーティリティライブラリ

コンテナライブラリ

イテレータライブラリ

Rangesライブラリ (C++20)

アルゴリズムライブラリ

文字列ライブラリ

テキスト処理ライブラリ

数値ライブラリ

日付と時刻ライブラリ

入出力ライブラリ

ファイルシステムライブラリ (C++17)

並行サポートライブラリ (C++11)

実行制御ライブラリ (C++26)

Technical specifications (技術仕様)

シンボルインデックス

外部ライブラリ

 

コンテナライブラリ

シーケンス

array (C++11)

vector

vector<bool>

inplace_vector (C++26)

hive (C++26)

deque

forward_list (C++11)

list

連想

set

multiset

map

multimap

非順序連想

unordered_set (C++11)

unordered_multiset (C++11)

unordered_map (C++11)

unordered_multimap (C++11)

アダプタ

stack

queue

priority_queue

flat_set (C++23)

flat_multiset (C++23)

flat_map (C++23)

flat_multimap (C++23)

表示

span (C++20)

mdspan (C++23)

表

イテレータの無効化

メンバ関数テーブル

非メンバ関数テーブル

 

std::vector

メンバ型
メンバ関数
vector::vector vector::~vector vector::operator= vector::assign vector::assign_range (C++23)   vector::get_allocator 要素アクセス vector::operator[] vector::at vector::data vector::front vector::back イテレータ vector::beginvector::cbegin (C++11) vector::endvector::cend (C++11) vector::rbeginvector::crbegin (C++11) vector::rendvector::crend (C++11)	容量 vector::empty vector::size vector::max_size vector::reserve vector::capacity vector::shrink_to_fit (DR*) 変更 vector::clear vector::erase vector::insert vector::insert_range (C++23) vector::append_range (C++23) vector::emplace (C++11) vector::emplace_back (C++11) vector::push_back vector::pop_back vector::resize vector::swap
非メンバ関数
operator==operator<=> (C++20) swap(std::vector) erase(std::vector)erase_if(std::vector) (C++20)(C++20)	operator!=operator<operator>operator<=operator>= (C++20まで)(C++20まで)(C++20まで)(C++20まで)(C++20まで)
推論補助(C++17)

 

void reserve( size_type new_cap );		(C++20 以降 constexpr)

ベクトルの容量（再割り当てなしで保持できる要素の総数）を、new_cap以上になるように増やします。 new_capが現在のcapacity()より大きい場合、新しいストレージが割り当てられます。そうでない場合、関数は何も行いません。

reserve()はベクトルのサイズを変更しません。

new_capがcapacity()より大きい場合、すべてのイテレータ（end()イテレータを含む）と要素へのすべての参照が無効になります。それ以外の場合、イテレータや参照は無効になりません。

reserve()の呼び出し後、挿入によってベクトルのサイズがcapacity()の値より大きくなる場合を除き、挿入は再割り当てをトリガーしません。

パラメータ

new_cap	-	ベクトルの新しい容量（要素数）
型要件
- Tは、*thisへのMoveInsertableの要件を満たす必要があります。(C++11以降)

戻り値

(なし)

例外

• new_cap > max_size()の場合、std::length_error。
• Allocator::allocate()によってスローされる可能性のある例外（通常はstd::bad_alloc）。

例外がスローされた場合、この関数は効果がありません（強力な例外安全保証）。

Tのムーブコンストラクタがnoexceptではなく、かつTが*thisへのCopyInsertableでない場合、vectorは例外をスローするムーブコンストラクタを使用します。これが例外をスローした場合、保証は無効になり、効果は未定義になります。

(C++11以降)

計算量

コンテナのsize()に対して線形。

注釈

reserve()を適切に使用すると、不要な再割り当てを防ぐことができます。しかし、reserve()を不適切に使用すると（例えば、すべてのpush_back()呼び出しの前にそれを呼び出すなど）、実際には再割り当ての回数が増加し（容量が指数関数的ではなく線形に増加するため）、計算量の増加とパフォーマンスの低下を招く可能性があります。例えば、任意のvectorを参照で受け取り、そのvectorに要素を追加する関数は、通常、vectorの使用特性を知らないため、vectorに対してreserve()を呼び出すべきではありません。

範囲を挿入する場合、範囲バージョンのinsert()は、reserve()とその後の多数のpush_back()とは異なり、正しい容量の増加動作を維持するため、一般的に好ましいです。

reserve()はコンテナの容量を減らすために使用することはできません。そのためにはshrink_to_fit()が提供されています。

例

このコードを実行

#include <cstddef>
#include <iostream>
#include <new>
#include <vector>
 
// minimal C++11 allocator with debug output
template<class Tp>
struct NAlloc
{
    typedef Tp value_type;
 
    NAlloc() = default;
    template<class T>
    NAlloc(const NAlloc<T>&) {}
 
    Tp* allocate(std::size_t n)
    {
        n *= sizeof(Tp);
        Tp* p = static_cast<Tp*>(::operator new(n));
        std::cout << "allocating " << n << " bytes @ " << p << '\n';
        return p;
    }
 
    void deallocate(Tp* p, std::size_t n)
    {
        std::cout << "deallocating " << n * sizeof *p << " bytes @ " << p << "\n\n";
        ::operator delete(p);
    }
};
 
template<class T, class U>
bool operator==(const NAlloc<T>&, const NAlloc<U>&) { return true; }
 
template<class T, class U>
bool operator!=(const NAlloc<T>&, const NAlloc<U>&) { return false; }
 
int main()
{
    constexpr int max_elements = 32;
 
    std::cout << "using reserve: \n";
    {
        std::vector<int, NAlloc<int>> v1;
        v1.reserve(max_elements); // reserves at least max_elements * sizeof(int) bytes
 
        for (int n = 0; n < max_elements; ++n)
            v1.push_back(n);
    }
 
    std::cout << "not using reserve: \n";
    {
        std::vector<int, NAlloc<int>> v1;
 
        for (int n = 0; n < max_elements; ++n)
        {
            if (v1.size() == v1.capacity())
                std::cout << "size() == capacity() == " << v1.size() << '\n';
            v1.push_back(n);
        }
    }
}

実行結果の例

using reserve: 
allocating 128 bytes @ 0xa6f840
deallocating 128 bytes @ 0xa6f840
 
not using reserve: 
size() == capacity() == 0
allocating 4 bytes @ 0xa6f840
 
size() == capacity() == 1
allocating 8 bytes @ 0xa6f860
deallocating 4 bytes @ 0xa6f840
 
size() == capacity() == 2
allocating 16 bytes @ 0xa6f840
deallocating 8 bytes @ 0xa6f860
 
size() == capacity() == 4
allocating 32 bytes @ 0xa6f880
deallocating 16 bytes @ 0xa6f840
 
size() == capacity() == 8
allocating 64 bytes @ 0xa6f8b0
deallocating 32 bytes @ 0xa6f880
 
size() == capacity() == 16
allocating 128 bytes @ 0xa6f900
deallocating 64 bytes @ 0xa6f8b0
 
deallocating 128 bytes @ 0xa6f900

不具合報告

以下の動作変更を伴う欠陥報告が、以前に公開されたC++標準に遡って適用されました。

DR	適用対象	公開された動作	正しい動作
LWG 329	C++98	挿入が ベクトルのサイズを 直近のreserve()呼び出しで指定されたサイズより大きくする場合、再割り当てが発生する可能性があります。	サイズが ベクトルの capacity()より大きくなった場合にのみトリガーされます。
LWG 2033	C++11	TはMoveInsertableである必要はありませんでした。	必要

関連情報

capacity	現在確保されているストレージに保持できる要素数を返す (public member function)
max_size	可能な最大要素数を返す (public メンバ関数)
resize	格納されている要素の数を変更する (公開メンバ関数)
shrink_to_fit (DR*)	未使用のメモリを解放してメモリ使用量を削減する (公開メンバ関数)