C++ Reference ยท Containers
std::vector::reserve, capacity and shrink_to_fit
Reference for vector size versus capacity: reserve, capacity, resize, shrink_to_fit, max_size, what the standard guarantees and what is implementation-defined.
A vector has two sizes. Its size is the number of elements it holds; its capacity is the number of elements it can hold before it must allocate a bigger buffer. reserve(n) asks for capacity of at least n without adding elements; capacity() reports it; shrink_to_fit() asks the vector to give back unused capacity.
Reserving matters for two reasons: it avoids repeated reallocations (each one moves every element), and it keeps iterators, pointers and references valid as long as the size stays within the reserved capacity. Do not confuse it with resize(n), which changes the size and creates or destroys elements.
std::vector<int> v; v.reserve(1000); // capacity >= 1000, size still 0
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Syntax
size_type capacity() const noexcept; size_type max_size() const noexcept; void reserve(size_type n); void shrink_to_fit(); void resize(size_type n); void resize(size_type n, const T& value);
| Name | Description |
|---|---|
n |
Requested capacity for reserve, or the new size for resize. |
value |
The value used for the extra elements when resize grows the vector. |
Returns: capacity() and max_size() return element counts; the other functions return nothing.
Errors / undefined behavior:
reserve(n)throwsstd::length_errorifn > max_size(), andstd::bad_allocif allocation fails. If it throws, the vector is unchanged.reservenever reduces capacity; a smallernis simply ignored.resizeto a larger size needsTto be default-constructible (or avalueto copy).
Usage notes
- Guaranteed:
capacity() >= size(); afterreserve(n),capacity() >= n; no reallocation happens while the size stays within capacity. Not guaranteed: the growth factor (commonly 2 in libstdc++ and 1.5 in MSVC) and the exact capacity aftershrink_to_fit(); print them only as "from this runner". - Do not reserve in a loop with a growing
n(reserve(size() + 1)): that can force a reallocation on every call, giving O(nยฒ). Let the automatic growth do its job, or reserve once. resizevsreserve:v.reserve(10); v[3] = 1;is undefined behavior (there is no element 3). Useresizeorassignto create elements.clear()does not free memory. To release it,v = {}, swap with an empty vector, orshrink_to_fit().shrink_to_fit()is non-binding. It may reallocate (invalidating iterators) or do nothing.- Strings behave the same:
std::stringhas the same size/capacity/reserve/shrink_to_fitpair, andstd::dequehasshrink_to_fitbut noreserve. - Memory: a vector of 1,000
ints with capacity 1,024 uses 4 KB. When you know the count, reserving exactly avoids both wasted space and moves. max_size()is a theoretical limit; allocation will normally fail long before.