Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
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 ); (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, in-
       cluding 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<Alloca-
       tor>::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  cur-
       rently allocated
	  capacity storage
		   (public member function)
	  resize   changes the number of characters stored
		   (public member function)

http://cppreference.com		  2022.07.31	 std::basic_string::reserve(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::wstring::reserve&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help