[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::propagate_on_container_swap::value || allocator_traits::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)