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

来自cppreference.com
 
C++
 
字符串库
 
std::basic_string
 
<tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody>
(1)
void reserve( size_type new_cap = 0 );
 (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 - 字符串的新容量

返回值

See More

（无）

异常

如果 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 没有异常安全保证 添加强异常安全保证

参阅

 返回当前对象分配的存储空间能保存的字符数量
(公开成员函数) [编辑]
更改存储的字符数
(公开成员函数) [编辑]