Increase the capacity of the vector (the total number of elements that the vector can hold without requiring reallocation) to a value that's greater or equal tonew_cap. Ifnew_cap is greater than the currentcapacity(), new storage is allocated, otherwise the function does nothing.

reserve() does not change the size of the vector.

Ifnew_cap is greater thancapacity(), all iterators (including theend() iterator) and all references to the elements are invalidated. Otherwise, no iterators or references are invalidated.

After a call toreserve(), insertions will not trigger reallocation unless the insertion would make the size of the vector greater than the value ofcapacity().

[edit]Parameters

[edit]Return value

(none)

[edit]Exceptions

• std::length_error ifnew_cap> max_size().
• Any exception thrown byAllocator::allocate() (typicallystd::bad_alloc).

If an exception is thrown, this function has no effect (strong exception guarantee).

[edit]Complexity

At most linear in thesize() of the container.

[edit]Notes

Correctly usingreserve() can prevent unnecessary reallocations, but inappropriate uses ofreserve() (for instance, calling it before everypush_back() call) may actually increase the number of reallocations (by causing the capacity to grow linearly rather than exponentially) and result in increased computational complexity and decreased performance. For example, a function that receives an arbitrary vector by reference and appends elements to it should usuallynot callreserve() on the vector, since it does not know of the vector's usage characteristics.

When inserting a range, the range version ofinsert() is generally preferable as it preserves the correct capacity growth behavior, unlikereserve() followed by a series ofpush_back()s.

reserve() cannot be used to reduce the capacity of the container; to that endshrink_to_fit() is provided.

[edit]Example

#include <cstddef>#include <iostream>#include <new>#include <vector> // minimal C++11 allocator with debug outputtemplate<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>&){returntrue;} template<class T,class U>bool operator!=(const NAlloc<T>&,const NAlloc<U>&){returnfalse;} int main(){constexprint 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 @ 0xa6f840deallocating 128 bytes @ 0xa6f840 not using reserve: size() == capacity() == 0allocating 4 bytes @ 0xa6f840 size() == capacity() == 1allocating 8 bytes @ 0xa6f860deallocating 4 bytes @ 0xa6f840 size() == capacity() == 2allocating 16 bytes @ 0xa6f840deallocating 8 bytes @ 0xa6f860 size() == capacity() == 4allocating 32 bytes @ 0xa6f880deallocating 16 bytes @ 0xa6f840 size() == capacity() == 8allocating 64 bytes @ 0xa6f8b0deallocating 32 bytes @ 0xa6f880 size() == capacity() == 16allocating 128 bytes @ 0xa6f900deallocating 64 bytes @ 0xa6f8b0 deallocating 128 bytes @ 0xa6f900

[edit]Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

[edit]See also

• In other languages

• Česky
• Deutsch
• Español
• Français
• Italiano
• 日本語
• Português
• Русский
• 中文