FreeBSD Manual Pages
std::basic_string::reserve(3) C++ Standard Libarystd::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 ); (since C++20) (1) (since C++20) void reserve(); (2) (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 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-bind- ing (until C++20) shrink-to-fit request equivalent to shrink_to_fit() (since C++11). * If new_cap is less than or equal to the current capacity(), there (since C++20) is no effect. If a capacity change takes place, all iterators and references, in- cluding 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<Alloca- tor>::allocate(), such as std::bad_alloc. If an exception is thrown for any reason, this function has no ef- fect (strong exception safety guarantee). 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; 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.capac- ity() << '\n'; // 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 << (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 retroac- tively to previously published C++ standards. DR Applied to Behavior as published Correct behavior LWG 847 C++98 there was no exception safety added strong exception safety guarantee guarantee See also returns the number of characters that can be held in cur- rently allocated capacity storage (public member function) resize changes the number of characters stored (public member function) http://cppreference.com 2024.06.10 std::basic_string::reserve(3)
NAME | Synopsis | Parameters | Return value | Exceptions | Complexity | Example | Possible output: | See also
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::u32string::reserve&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>