NAME

std::basic_string::reserve - std::basic_string::reserve

Synopsis

void reserve( size_type new_cap = 0 ); (until C++20)
constexpr void reserve( size_type new_cap ); (1) (since C++20)
void reserve(); (2) (since C++20)
(deprecated)

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 (until C++20)
non-binding shrink-to-fit request
equivalent to shrink_to_fit()
(since C++11).
* If new_cap is less than or equal to the current capacity(), (since C++20)
there is no effect.

If a capacity change takes place, all iterators and references, including the
past-the-end iterator, are invalidated.

2) A call to reserve with no argument is a non-binding shrink-to-fit
request. After this call, capacity() has an unspecified value greater (since C++20)
than or equal to size().

Parameters

new_cap - new capacity of the string

Return value

(none)

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.

Complexity

At most linear in the size() of the string

Example

// Run this code

#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";

s.reserve(new_capacity);
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:
s.shrink_to_fit();
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