object::reserve

## `object::reserve`

Increase the capacity to at least a certain amount.

### Synopsis

    void
    reserve(
        std::size_t new_capacity);

### Description

This increases the `capacity()` to a value that is greater than or equal to `new_capacity`. If `new_capacity > capacity()`, new memory is allocated. Otherwise, the call has no effect. The number of elements and therefore the `size()` of the container is not changed.

If new memory is allocated, all iterators including any past-the-end iterators, and all references to the elements are invalidated. Otherwise, no iterators or references are invalidated.

### Complexity

Constant if no reallocation occurs. Otherwise, average case linear in `size()`, worst case quadratic in `size()`.

### Exception Safety

Strong guarantee. Calls to `memory_resource::allocate` may throw.

### Parameters

Name | Description
--- | ---
`new_capacity` | The new minimum capacity.

### Exceptions

Type | Thrown On
--- | ---
`boost::system::system_error` | `new_capacity >` `max_size()`.

Edit this page