[vector.capacity]

# 23 Containers library [[containers]](./#containers)

## 23.3 Sequence containers [[sequences]](sequences#vector.capacity)

### 23.3.13 Class template vector [[vector]](vector#capacity)

#### 23.3.13.3 Capacity [vector.capacity]

[ð](#lib:capacity,vector)

`constexpr size_type capacity() const noexcept;
`

[1](#1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10118)

*Returns*: The total number of elements that the vector can hold
without requiring reallocation[.](#1.sentence-1)

[2](#2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10123)

*Complexity*: Constant time[.](#2.sentence-1)

[ð](#lib:reserve,vector)

`constexpr void reserve(size_type n);
`

[3](#3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10134)

*Preconditions*: T is *Cpp17MoveInsertable* into vector[.](#3.sentence-1)

[4](#4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10138)

*Effects*: A directive that informs avector of a planned change in size, so that it can manage the storage allocation accordingly[.](#4.sentence-1)

Afterreserve(),capacity() is greater or equal to the argument ofreserve if reallocation happens; and equal to the previous value ofcapacity() otherwise[.](#4.sentence-2)

Reallocation happens at this point if and only if the current capacity is less than the
argument ofreserve()[.](#4.sentence-3)

If an exception is thrown
other than by the move constructor of a non-*Cpp17CopyInsertable* type,
there are no effects[.](#4.sentence-4)

[5](#5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10157)

*Throws*: length_error if n > max_size()[.](#5.sentence-1)[197](#footnote-197 "reserve() uses Allocator​::​allocate() which can throw an appropriate exception.")

[6](#6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10166)

*Complexity*: It does not change the size of the sequence and takes at most linear
time in the size of the sequence[.](#6.sentence-1)

[7](#7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10171)

*Remarks*: Reallocation invalidates all the references, pointers, and iterators
referring to the elements in the sequence, as well as the past-the-end iterator[.](#7.sentence-1)

[*Note [1](#note-1)*:

If no reallocation happens, they remain valid[.](#7.sentence-2)

â *end note*]

No reallocation shall take place during insertions that happen
after a call to reserve() until an insertion would make the size of the vector
greater than the value of capacity()[.](#7.sentence-3)

[ð](#lib:shrink_to_fit,vector)

`constexpr void shrink_to_fit();
`

[8](#8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10190)

*Preconditions*: T is *Cpp17MoveInsertable* into vector[.](#8.sentence-1)

[9](#9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10194)

*Effects*: shrink_to_fit is a non-binding request to reducecapacity() to size()[.](#9.sentence-1)

[*Note [2](#note-2)*:

The request is non-binding to allow latitude for
implementation-specific optimizations[.](#9.sentence-2)

â *end note*]

It does not increase capacity(), but may reduce capacity() by causing reallocation[.](#9.sentence-3)

If an exception is thrown other than by the move constructor
of a non-*Cpp17CopyInsertable* T, there are no effects[.](#9.sentence-4)

[10](#10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10207)

*Complexity*: If reallocation happens,
linear in the size of the sequence[.](#10.sentence-1)

[11](#11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10212)

*Remarks*: Reallocation invalidates all the references, pointers, and iterators
referring to the elements in the sequence as well as the past-the-end iterator[.](#11.sentence-1)

[*Note [3](#note-3)*:

If no reallocation happens, they remain valid[.](#11.sentence-2)

â *end note*]

[ð](#lib:swap,vector)

`constexpr void swap(vector& x)
  noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
           allocator_traits<Allocator>::is_always_equal::value);
`

[12](#12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10229)

*Effects*: Exchanges the contents andcapacity() of*this with that of x[.](#12.sentence-1)

[13](#13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10237)

*Complexity*: Constant time[.](#13.sentence-1)

[ð](#lib:resize,vector)

`constexpr void resize(size_type sz);
`

[14](#14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10248)

*Preconditions*: T is*Cpp17MoveInsertable* and *Cpp17DefaultInsertable* into vector[.](#14.sentence-1)

[15](#15)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10253)

*Effects*: If sz < size(), erases the last size() - sz elements
from the sequence[.](#15.sentence-1)

Otherwise,
appends sz - size() default-inserted elements to the sequence[.](#15.sentence-2)

[16](#16)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10259)

*Remarks*: If an exception is thrown other than by the move constructor of a non-*Cpp17CopyInsertable*T, there are no effects[.](#16.sentence-1)

[ð](#lib:resize,vector_)

`constexpr void resize(size_type sz, const T& c);
`

[17](#17)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10271)

*Preconditions*: T is*Cpp17CopyInsertable* into vector[.](#17.sentence-1)

[18](#18)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10276)

*Effects*: If sz < size(), erases the last size() - sz elements
from the sequence[.](#18.sentence-1)

Otherwise,
appends sz - size() copies of c to the sequence[.](#18.sentence-2)

[19](#19)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L10282)

*Remarks*: If an exception is thrown, there are no effects[.](#19.sentence-1)

[197)](#footnote-197)[197)](#footnoteref-197)

reserve() uses Allocator​::​allocate() which
can throw an appropriate exception[.](#footnote-197.sentence-1)
