std::basic_string<CharT,Traits,Allocator>::reserve
< cpp | string | basic string
void reserve( size_type new_cap = 0 ); |
(1) | (until C++20) |
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 thannew_cap
.
- If
|
(until C++20) |
|
(since C++20) |
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 than or equal to size().
|
(since C++20) |
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 <string> int main() { std::string s; std::string::size_type new_capacity{ 100u }; assert(new_capacity > s.capacity()); s.reserve(new_capacity); assert(new_capacity <= s.capacity()); }
See also
returns the number of characters that can be held in currently allocated storage (public member function) |