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

出自cppreference.com
 
C++
 
字符串庫
 
std::basic_string
 
void reserve( size_type new_cap = 0 );
(1) (C++20 前) 
constexpr void reserve( size_type new_cap );
(C++20 起) 
void reserve();
(2) (C++20 起)
(C++20 棄用)
(C++26 移除)
1) 告知 std::basic_string 對象大小的有計劃更改，使得它能準確地管理存儲分配。
  • 如果 new_cap 大於當前 capacity()，那麼分配新存儲，並使 capacity() 大於或等於 new_cap。
  • 如果 new_cap 小於當前 capacity()，那麼這是非強制的收縮請求。
  • 如果 new_cap 小於當前 size()，那麼這是非強制的收縮到適合（shrink-to-fit）請求，等價於 shrink_to_fit()(C++11 起)。
 (C++20 前)
  • 如果 new_cap 小於或等於當前 capacity()，那麼沒有效果。
 (C++20 起)
如果容量有更改，那麼所有迭代器與引用（包含尾後迭代器）都會失效。
2) 非強制的收縮到適合請求。調用後 capacity() 擁有大於或等於 size() 的未指定值。

參數

new_cap - 字符串的新容量

返回值

（無）

異常

如果 new_cap 大於 max_size()，那麼就會拋出 std::length_error。

可能拋出任何 std::allocator_traits<Allocator>::allocate() 拋出的異常，如 std::bad_alloc。

如果因為任何原因拋出了異常，那麼此函數無效果（強異常安全保證）。

複雜度

至多與字符串的 size() 成線性。

示例

運行此代碼
#include <cassert>
#include <iostream>
#include <string>

int main()
{
    std::string s;
    std::cout << "1) 起初: " << s.capacity() << '\n';
    
    const std::string::size_type new_cap{101u};
    s.reserve(new_cap);
    assert(s.capacity() >= new_cap);
    std::cout << "2) reserve(" << new_cap << ") 之后: " << s.capacity() << '\n';
    
    // 观察容量增长因子
    auto cap{s.capacity()};
    for (int check{}; check != 4; ++check)
    {
        while (cap == s.capacity())
            s += '$';
        cap = s.capacity();
        std::cout << (3) + check << ") 容量: " << cap << '\n';
    }
    
//  s.reserve(); // C++20/26 中弃用/移除，应使用:
    s.shrink_to_fit();
    std::cout << "7) shrink_to_fit 之后: " << s.capacity() << '\n';
}

可能的輸出： 

1) 起初: 15
2) reserve(101) 之后: 101
3) 容量: 202
4) 容量: 404
5) 容量: 808
6) 容量: 1616
7) shrink_to_fit 之后: 809

缺陷報告

下列更改行為的缺陷報告追溯地應用於以前出版的 C++ 標準。

缺陷報告 應用於 出版時的行為 正確行為
LWG 847 C++98 沒有異常安全保證 添加強異常安全保證

參閱

 返回當前對象分配的存儲空間能保存的字符數量
(公開成員函數) [編輯]
更改存儲的字符數
(公開成員函數) [編輯]