< cpp‎ | string‎ | basic string
Member functions
Element access
Deduction guides (C++17)
Non-member functions
(until C++20)(until C++20)(until C++20)(until C++20)(until C++20)(C++20)
Numeric conversion
Helper classes
  1. 1.0 1.1 1.2 1.3 Not available in libstdc++ C++98 mode.
void reserve( size_type new_cap = 0 );
(until C++20)
constexpr void reserve( size_type new_cap );
(since C++20)
void reserve();
(2) (since C++20)
1) Informs a std::basic_string object of a planned change in size, so that it can manage the storage allocation appropriately.
  • If new_cap is greater than the current capacity(), new storage is allocated, and capacity() is made equal or greater than new_cap.
  • If new_cap is less than the current capacity(), this is a non-binding shrink request.
  • If new_cap is less than the current size(), this is a non-binding shrink-to-fit request equivalent to shrink_to_fit() (since C++11).
(until C++20)
  • If new_cap is less than or equal to the current capacity(), there is no effect.
(since C++20)
If a capacity change takes place, all iterators and references, including the past-the-end iterator, are invalidated.
2) A non-binding shrink-to-fit request. After this call, capacity() has an unspecified value greater than or equal to size().


[edit] Parameters

new_cap - new capacity of the string

[edit] Return value


[edit] Exceptions

Throws std::length_error if new_cap is greater than max_size().

May throw any exceptions thrown by std::allocator_traits<Allocator>::allocate(), such as std::bad_alloc.

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

[edit] Complexity

At most linear in the size() of the string.

[edit] Example

#include <cassert>
#include <iostream>
#include <string>
int main()
    std::string s;
    const std::string::size_type new_capacity{100u};
    std::cout << "Before: " << s.capacity() << '\n';
    std::cout << "After:  " << s.capacity() << '\n';
    assert(new_capacity <= s.capacity());
    // observing the capacity growth factor
    auto cap{s.capacity()};
    for (int check{}; check != 4; ++check)
        while (cap == s.capacity())
            s += '$';
        cap = s.capacity();
        std::cout << "New capacity: " << cap << '\n';
    // s.reserve(); // deprecated in C++20, use:
    std::cout << "After:  " << s.capacity() << '\n';

Possible output:

Before: 15
After:  100
New capacity: 200
New capacity: 400
New capacity: 800
New capacity: 1600
After:  801

[edit] Defect reports

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

DR Applied to Behavior as published Correct behavior
LWG 847 C++98 there was no exception safety guarantee added strong exception safety guarantee

[edit] See also

returns the number of characters that can be held in currently allocated storage
(public member function) [edit]
changes the number of characters stored
(public member function) [edit]