|
|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| (1) | ||
void reserve( size_type new_cap=0); | (until C++20) | |
constexprvoid reserve( size_type new_cap); | (since C++20) | |
void reserve(); | (2) | (since C++20) (deprecated in C++20) (removed in C++26) |
std::basic_string object of a planned change in size, so that it can manage the storage allocation appropriately.
| (until C++20) |
| (since C++20) |
Contents |
| new_cap | - | new capacity of the string |
(none)
Throwsstd::length_error ifnew_cap is greater thanmax_size().
May throw any exceptions thrown bystd::allocator_traits<Allocator>::allocate(), such asstd::bad_alloc.
If an exception is thrown for any reason, this function has no effect (strong exception safety guarantee).
At most linear in thesize() of the string.
#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 factorauto 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';}
Possible output:
1) Initially: 152) After reserve(101): 1013) Capacity: 2024) Capacity: 4045) Capacity: 8086) Capacity: 16167) After shrink_to_fit: 809
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 |
| returns the number of characters that can be held in currently allocated storage (public member function)[edit] | |
| changes the number of characters stored (public member function)[edit] |
