CKTIS / C++
std::basic_string::reserve — capacity versus size
`reserve(n)` makes room for future elements without changing how many exist. `resize(n)` changes the element count in both strings and vectors.
Version: ISO C++23; implementation support may vary
Syntax
ISO C++23 member declarations (excerpts):
// <string>, in std::basic_string<CharT, Traits, Allocator>
constexpr void reserve(size_type n);
void reserve(); // Deprecated since C++20
constexpr void resize(size_type n);
constexpr void resize(size_type n, CharT c);
// <vector>, in std::vector<T, Allocator>
constexpr void reserve(size_type n);
constexpr void resize(size_type n);
constexpr void resize(size_type n, const T& value);std::basic_string::reserve is declared in <string> and is available on std::string. In C++23, after a successful s.reserve(n), capacity() >= n while size() and contents are unchanged. n is a minimum total capacity, not a count of extra characters. If n <= capacity(), there is no reallocation and capacity stays the same. Otherwise, the string reallocates and may get more capacity than requested.
std::vector::reserve(n) in <vector> follows the same capacity rule without creating elements. Reallocation invalidates existing pointers, references, and iterators to elements, as well as the past-the-end iterator. A vector guarantees that subsequent insertions will not reallocate until an insertion would exceed its capacity. Do not assume that guarantee for string modifiers.
Use resize(n) when you need exactly n elements: shrinking removes trailing elements and growing adds new ones. The overloads s.resize(n, c) and v.resize(n, value) fill new positions with the supplied value. Spare capacity does not extend the element index range: write to elements only at i < size(). For a string, s[s.size()] refers to the null terminator, not an extra character in the string.
For std::basic_string::reserve(n), n > max_size() throws std::length_error, and an allocator exception such as std::bad_alloc can propagate. If an exception is thrown, the string is unchanged. The separate no-argument s.reserve() is a non-binding shrink request, deprecated since C++20 but still present in C++23. Use s.shrink_to_fit() to make that request; a reduction is not guaranteed.
Examples
#include <iostream>
#include <string>
#include <vector>
int main() {
std::string s = "hi";
std::vector<int> v{1, 2};
s.reserve(64);
v.reserve(64);
std::cout << std::boolalpha;
std::cout << "string reserve: " << static_cast<unsigned int>(s.size()) << ' '
<< (s.capacity() >= 64) << ' ' << s << '\n';
std::cout << "vector reserve: " << static_cast<unsigned int>(v.size()) << ' '
<< (v.capacity() >= 64) << ' ' << v[0] << ' ' << v[1] << '\n';
s.resize(4, '!');
v.resize(4, 9);
std::cout << "string resize: " << static_cast<unsigned int>(s.size())
<< ' ' << s << '\n';
std::cout << "vector resize: " << static_cast<unsigned int>(v.size())
<< ' ' << v[2] << ' ' << v[3] << '\n';
}Result
string reserve: 2 true hi vector reserve: 2 true 1 2 string resize: 4 hi!! vector resize: 4 9 9
After `reserve(64)`, both containers still have two elements. The program checks only the lower bound on capacity; `resize` is what adds two elements to each container.
Related lessons
- C++ · Lesson 5 · Advanced · Version: 3
Sources
- C++23 working draft N4950 — [string.capacity], [string.require], [string.access], [vector.capacity], [depr.string.capacity]
- C++ working draft — Capacity [string.capacity]
- C++ working draft — Capacity [vector.capacity]
- C++ working draft — General requirements [string.require]
- P2870R0 — Remove basic_string::reserve() From C++26