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

< cpp‎ | string‎ | basic string

| (1) |
void reserve( size_type new_cap = 0 ); |  | (C++20 前)
constexpr void reserve( size_type new_cap ); |  | (C++20 起)
void reserve(); | (2) | (C++20 起) (弃用)

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) 以无参数调用 `reserve` 是非强制的收缩到适合请求。此调用后， capacity() 拥有大于或等于 size() 的未指定值。 | (C++20 起)

### 参数

new_cap | - | string 的新容量

### 返回值

（无）

### 异常

若 `new_cap` 大于 max_size() 则抛出 std::length_error

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

### 复杂度

至多与 string 的 size() 成线性

### 示例

    #include <cassert>
    #include <string>

    int main()
    {
        std::string s;
        std::string::size_type new_capacity{ 100u };
        assert(new_capacity > s.capacity());

        s.reserve(new_capacity);
        assert(new_capacity <= s.capacity());
    }

### 参阅

capacity | 返回当前对象分配的存储空间能保存的字符数量 (公开成员函数)