211 lines
6.6 KiB
Markdown
211 lines
6.6 KiB
Markdown
[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)
|