std::basic_string<CharT,Traits,Allocator>:: reserve

Parameters

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 .

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

Complexity

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

Example

#include <cassert>
#include <iostream>
#include <string>
 
int main()
{
    std::string s;
    std::cout << "1) Initially: " << s.capacity() << '\n';
 
    const std::string::size_type new_cap{101u};
    s.reserve(new_cap);
    assert(s.capacity() >= new_cap);
    std::cout << "2) After reserve(" << new_cap << "): " << s.capacity() << '\n';
 
    // 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 << (3) + check << ") Capacity: " << cap << '\n';
    }
 
//  s.reserve(); // deprecated/removed in C++20/26, use:
    s.shrink_to_fit();
    std::cout << "7) After shrink_to_fit: " << s.capacity() << '\n';
}

1) Initially: 15
2) After reserve(101): 101
3) Capacity: 202
4) Capacity: 404
5) Capacity: 808
6) Capacity: 1616
7) After shrink_to_fit: 809

Defect reports

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

See also