home | help 
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 );	     (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-binding
     (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,  includ-
     ing 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<Allocator>::al-
     locate(),
	such as std::bad_alloc.

	If an exception is thrown for any reason, this function  has  no  effect
     (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.capacity()
     << '\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 be-
     havior
	LWG  847 C++98	    there was no exception safety	added strong ex-
     ception safety
			   guarantee			       guarantee

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)

http://cppreference.com 	   2024.06.10	   std::basic_string::reserve(3)
home | help