std::hive<T,Allocator>::reserve
void reserve( size_type new_cap );
|
(since C++26) | |
Increase the capacity of the hive (the total number of elements that the hive 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(), reserved blocks are allocated, otherwise the function does nothing.
reserve() does not change the size of the hive.
After a call to reserve(), capacity() >= new_cap is true.
Parameters
| new_cap | - | new capacity of the hive, in number of elements |
Exceptions
- std::length_error if
new_cap >= max_size. - Any exception thrown by
Allocator::allocate()(typically std::bad_alloc).
Complexity
Linear in the number of reserved blocks allocated.
Notes
Correctly using reserve() can prevent unnecessary reallocations, but inappropriate uses of reserve() may actually increase the number of reallocations and result in increased computational complexity and decreased performance. For example, a function that receives an arbitrary hive by reference and appends elements to it should usually not call reserve() on the hive, since it does not know of the hive's usage characteristics.
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 insert()s.
reserve() cannot be used to reduce the capacity of the container; to that end shrink_to_fit() and trim_capacity() are provided.