public member function
<vector>

std::vector::reserve

void reserve (size_type n);
Request a change in capacity
Requests that the vector capacity be at least enough to contain n elements.

If n is greater than the current vector capacity, the function causes the container to reallocate its storage increasing its capacity to n (or greater).

In all other cases, the function call does not cause a reallocation and the vector capacity is not affected.

This function has no effect on the vector size and cannot alter its elements.

Parameters

n
Minimum capacity for the vector.
Note that the resulting vector capacity may be equal or greater than n.
Member type size_type is an unsigned integral type.

Return Value

none

If the size requested is greater than the maximum size (vector::max_size), a length_error exception is thrown.

If case of reallocation, the storage is allocated using the container's allocator, which may throw exceptions on failure (for the default allocator, bad_alloc is thrown if the allocation request does not succeed).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// vector::reserve
#include <iostream>
#include <vector>

int main ()
{
  std::vector<int>::size_type sz;

  std::vector<int> foo;
  sz = foo.capacity();
  std::cout << "making foo grow:\n";
  for (int i=0; i<100; ++i) {
    foo.push_back(i);
    if (sz!=foo.capacity()) {
      sz = foo.capacity();
      std::cout << "capacity changed: " << sz << '\n';
    }
  }

  std::vector<int> bar;
  sz = bar.capacity();
  bar.reserve(100);   // this is the only difference with foo above
  std::cout << "making bar grow:\n";
  for (int i=0; i<100; ++i) {
    bar.push_back(i);
    if (sz!=bar.capacity()) {
      sz = bar.capacity();
      std::cout << "capacity changed: " << sz << '\n';
    }
  }
  return 0;
}


Possible output:

making foo grow:
capacity changed: 1
capacity changed: 2
capacity changed: 4
capacity changed: 8
capacity changed: 16
capacity changed: 32
capacity changed: 64
capacity changed: 128
making bar grow:
capacity changed: 100

Complexity

If a reallocation happens, linear in vector size at most.

Iterator validity

If a reallocation happens, all iterators, pointers and references related to the container are invalidated.
Otherwise, they all keep referring to the same elements they were referring to before the call.

Data races

If a reallocation happens, the container and all its contained elements are modified.
Otherwise, the container is accessed, but not the contained elements: concurrently accessing or modifying them is safe.

Exception safety

If no reallocations happen or if the type of the elements has either a non-throwing move constructor or a copy constructor, there are no changes in the container in case of exception (strong guarantee).
Otherwise, the container is guaranteed to end in a valid state (basic guarantee).
The function throws length_error if n is greater than max_size.

See also

  • 9316991614 2018-02-25
  • 191841613 2018-02-25
  • 16411612 2018-02-25
  • 6081981611 2018-02-25
  • 1784561610 2018-02-25
  • 4651609 2018-02-25
  • 9348111608 2018-02-25
  • 2513771607 2018-02-25
  • 6478461606 2018-02-24
  • 4985791605 2018-02-24
  • 5637141604 2018-02-24
  • 282181603 2018-02-24
  • 6217941602 2018-02-24
  • 5076141601 2018-02-24
  • 714281600 2018-02-24
  • 6607141599 2018-02-24
  • 949041598 2018-02-24
  • 6809961597 2018-02-24
  • 671871596 2018-02-24
  • 7107821595 2018-02-24