Movatterモバイル変換


[0]ホーム

URL:


cppreference.com
Namespaces
Variants
    Actions

      std::basic_string<CharT,Traits,Allocator>::reserve

      From cppreference.com
      <cpp‎ |string‎ |basic string
       
       
       
      std::basic_string
       
      (1)
      void reserve( size_type new_cap=0);
      (until C++20)
      constexprvoid reserve( size_type new_cap);
      (since C++20)
      void reserve();
      (2)(since C++20)
      (deprecated in C++20)
      (removed in C++26)
      1) Informs astd::basic_string object of a planned change in size, so that it can manage the storage allocation appropriately.
      • Ifnew_cap is greater than the currentcapacity(), new storage is allocated, andcapacity() is made equal or greater thannew_cap.
      • Ifnew_cap is less than the currentcapacity(), this is a non-binding shrink request.
      • Ifnew_cap is less than the currentsize(), this is a non-binding shrink-to-fit request equivalent toshrink_to_fit()(since C++11).
      (until C++20)
      • Ifnew_cap is less than or equal to the currentcapacity(), there is no effect.
      (since C++20)
      If a capacity change takes place, all iterators and references, including 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 tosize().

      Contents

      [edit]Parameters

      new_cap - new capacity of the string

      [edit]Return value

      (none)

      [edit]Exceptions

      Throwsstd::length_error ifnew_cap is greater thanmax_size().

      May throw any exceptions thrown bystd::allocator_traits<Allocator>::allocate(), such asstd::bad_alloc.

      If an exception is thrown for any reason, this function has no effect (strong exception safety guarantee).

      [edit]Complexity

      At most linear in thesize() of the string.

      [edit]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 factorauto 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: 152) After reserve(101): 1013) Capacity: 2024) Capacity: 4045) Capacity: 8086) Capacity: 16167) After shrink_to_fit: 809

      [edit]Defect reports

      The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

      DRApplied toBehavior as publishedCorrect behavior
      LWG 847C++98there was no exception safety guaranteeadded strong exception safety guarantee

      [edit]See also

      returns the number of characters that can be held in currently allocated storage
      (public member function)[edit]
      changes the number of characters stored
      (public member function)[edit]
      Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/string/basic_string/reserve&oldid=171095"

      [8]ページ先頭

      ©2009-2025 Movatter.jp