home | help 
std::basic_...ng::capacity(3)  C++ Standard Libary std::basic_...ng::capacity(3)

NAME
     std::basic_string::capacity - std::basic_string::capacity

Synopsis
	size_type capacity() const;  (noexcept since C++11)
				     (constexpr since C++20)

	Returns the number of characters that the string has currently allocated
     space for.

Parameters
	(none)

Return value
	Capacity  of the currently allocated storage, i.e. the storage available
     for storing
	elements.

Complexity
	Constant.

Notes
	Memory locations obtained from the allocator but not available for stor-
     ing any
	element are not counted in the allocated storage.  Note  that  the  null
     terminator is
	not an element of the std::basic_string.

Example
     // Run this code

      #include <iomanip>
      #include <iostream>
      #include <string>

      void show_capacity(std::string const& s)
      {
	  std::cout  <<  std::quoted(s)  <<  " has capacity " << s.capacity() <<
     ".\n";
      }

      int main()
      {
	  std::string s{"Exemplar"};
	  show_capacity(s);

	  s += " is an example string.";
	  show_capacity(s);

	  s.clear();
	  show_capacity(s);

	  std::cout << "\nDemonstrate the capacity's growth policy."
		       "\nSize:  Capacity:  Ratio:\n" << std::left;

	  std::string g;
	  auto old_cap{g.capacity()};

	  for (int mark{}; mark != 5; ++mark)
	  {
	      while (old_cap == g.capacity())
		  g.push_back('.');

	      std::cout << std::setw( 7) << g.size()
			<< std::setw(11) << g.capacity()
			<<    std::setw(10)    <<    g.capacity()     /     sta-
     tic_cast<float>(old_cap) << '\n';

	      old_cap = g.capacity();
	  }
      }

Possible output:
      "Exemplar" has capacity 15.
      "Exemplar is an example string." has capacity 30.
      "" has capacity 30.

      Demonstrate the capacity's growth policy.
      Size:  Capacity:	Ratio:
      16     30 	2
      31     60 	2
      61     120	2
      121    240	2
      241    480	2

See also
	size	returns the number of characters
	length	(public member function)
	reserve reserves storage
		(public member function)

http://cppreference.com 	   2024.06.10	   std::basic_...ng::capacity(3)
home | help