std::basic_string::reserve(3)

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

See also
            returns the number of characters that can be held in currently allocated
   capacity storage
            (public member function)
   resize changes the number of characters stored
            (public member function)