table of contents
std::basic_string::reserve(3) | C++ Standard Libary | std::basic_string::reserve(3) |
NAME¶
std::basic_string::reserve - std::basic_string::reserve
Synopsis¶
void reserve( size_type new_cap = 0 ); (until C++20)
constexpr 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 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 (until C++20)
non-binding shrink-to-fit request
equivalent to shrink_to_fit()
(since C++11).
* If new_cap is less than or equal to the current capacity(), (since
C++20)
there is no effect.
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
(since C++20)
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.
Complexity¶
At most linear in the size() of the string
Example¶
// Run this code
#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
See also¶
returns the number of characters that can be held in currently
allocated
capacity storage
(public member function)
resize changes the number of characters stored
(public member function)
2022.07.31 | http://cppreference.com |