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

From cppreference.com
< cpp‎ | string‎ | basic string
 
 
 
std::basic_string
Member functions
Element access
Iterators
Capacity
basic_string::reserve
Operations
Search
Constants
Deduction guides (C++17)
Non-member functions
I/O
Comparison
(until C++20)(until C++20)(until C++20)(until C++20)(until C++20)(C++20)
Numeric conversion
(C++11)(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)(C++11)
(C++11)
(C++11)
Helper classes
 
(1)
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)
(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 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().

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.

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

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

See also

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