From cppreference.com
voidreserve(size_typenew_cap=0); (1)(until C++20)constexprvoidreserve(size_typenew_cap);(since C++20)voidreserve(); (2) (since C++20)
(deprecated in C++20)
(removed in C++26)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
, new storage is allocated, and
is made equal or greater than new_cap.
If new_cap is less than the current
, this is a non-binding shrink request.
If new_cap is less than the current
, this is a non-binding shrink-to-fit request equivalent to
(since C++11).
(until C++20)If new_cap is less than or equal to the current
, 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,
has an unspecified value greater than or equal to
.
Parameters
new_cap - new capacity of the string Return value
(none)
Exceptions
Throws
if new_cap is greater than
.
May throw any exceptions thrown by std::allocator_traits<Allocator>::allocate(), such as
.
If an exception is thrown for any reason, this function has no effect (
strong exception safety guarantee
).
Complexity
At most linear in the
of the string.
Example
Run this code
#include<cassert>#include<iostream>#include<string>intmain(){std::strings;std::cout<<"1) Initially: "<<s.capacity()<<'\n';conststd::string::size_typenew_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 factorautocap{s.capacity()};for(intcheck{};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';}Possible output:
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.
DR Applied to Behavior as published Correct behavior
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)