FreeBSD Manual Pages
std::vector::reserve(3) C++ Standard Libary std::vector::reserve(3) NAME std::vector::reserve - std::vector::reserve Synopsis void reserve( size_type new_cap ); (until C++20) constexpr void reserve( size_type new_cap ); (since C++20) Increase the capacity of the vector (the total number of elements that the vector can hold without requiring reallocation) to a value that's greater or equal to new_cap. If new_cap is greater than the current capacity(), new storage is allocated, otherwise the function does nothing. reserve() does not change the size of the vector. If new_cap is greater than capacity(), all iterators, including the past-the-end iterator, and all references to the elements are invalidated. Other- wise, no iterators or references are invalidated. Parameters new_cap - new capacity of the vector, in number of elements Type requirements - T must meet the requirements of MoveInsertable. Return value (none) Exceptions * std::length_error if new_cap > max_size(). * any exception thrown by Allocator::allocate() (typically std::bad_alloc) If an exception is thrown, this function has no effect (strong ex- ception guarantee). If T's move constructor is not noexcept and T is not CopyInsertable into *this, vector will use the throwing move constructor. If it (since C++11) throws, the guarantee is waived and the effects are unspecified. Complexity At most linear in the size() of the container. Notes Correctly using reserve() can prevent unnecessary reallocations, but inappropriate uses of reserve() (for instance, calling it before every push_back() call) may actually increase the number of reallocations (by causing the capac- ity to grow linearly rather than exponentially) and result in increased computa- tional complexity and decreased performance. For example, a function that receives an arbitrary vector by reference and appends elements to it should usually not call re- serve() on the vector, since it does not know of the vector's usage characteris- tics. When inserting a range, the range version of insert() is generally preferable as it preserves the correct capacity growth behavior, unlike reserve() followed by a series of push_back()s. reserve() cannot be used to reduce the capacity of the container; to that end shrink_to_fit() is provided. Example // Run this code #include <cstddef> #include <iostream> #include <new> #include <vector> // minimal C++11 allocator with debug output template <class Tp> struct NAlloc { typedef Tp value_type; NAlloc() = default; template <class T> NAlloc(const NAlloc<T>&) {} Tp* allocate(std::size_t n) { n *= sizeof(Tp); Tp* p = static_cast<Tp*>(::operator new(n)); std::cout << "allocating " << n << " bytes @ " << p << '\n'; return p; } void deallocate(Tp* p, std::size_t n) { std::cout << "deallocating " << n*sizeof*p << " bytes @ " << p << "\n\n"; ::operator delete(p); } }; template <class T, class U> bool operator==(const NAlloc<T>&, const NAlloc<U>&) { return true; } template <class T, class U> bool operator!=(const NAlloc<T>&, const NAlloc<U>&) { return false; } int main() { constexpr int max_elements = 32; std::cout << "using reserve: \n"; { std::vector<int, NAlloc<int>> v1; v1.reserve( max_elements ); // reserves at least max_elements * sizeof(int) bytes for(int n = 0; n < max_elements; ++n) v1.push_back(n); } std::cout << "not using reserve: \n"; { std::vector<int, NAlloc<int>> v1; for(int n = 0; n < max_elements; ++n) { if(v1.size() == v1.capacity()) { std::cout << "size() == capacity() == " << v1.size() << '\n'; } v1.push_back(n); } } } Possible output: using reserve: allocating 128 bytes @ 0xa6f840 deallocating 128 bytes @ 0xa6f840 not using reserve: size() == capacity() == 0 allocating 4 bytes @ 0xa6f840 size() == capacity() == 1 allocating 8 bytes @ 0xa6f860 deallocating 4 bytes @ 0xa6f840 size() == capacity() == 2 allocating 16 bytes @ 0xa6f840 deallocating 8 bytes @ 0xa6f860 size() == capacity() == 4 allocating 32 bytes @ 0xa6f880 deallocating 16 bytes @ 0xa6f840 size() == capacity() == 8 allocating 64 bytes @ 0xa6f8b0 deallocating 32 bytes @ 0xa6f880 size() == capacity() == 16 allocating 128 bytes @ 0xa6f900 deallocating 64 bytes @ 0xa6f8b0 deallocating 128 bytes @ 0xa6f900 See also returns the number of elements that can be held in currently allocated capacity storage (public member function) max_size returns the maximum possible number of elements (public member function) resize changes the number of elements stored (public member function) shrink_to_fit reduces memory usage by freeing unused memory (C++11) (public member function) http://cppreference.com 2022.07.31 std::vector::reserve(3)
NAME | Synopsis | Parameters | Type requirements | Return value | Exceptions | Complexity | Notes | Example | Possible output: | See also
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::vector::reserve&sektion=3&manpath=FreeBSD+Ports+15.0>