std::allocate_at_least
Defined in header <memory> |
||
---|---|---|
template< class Alloc > [[nodiscard]] constexpr std::allocation_result< typename std::allocator_traits<Alloc>::pointer> allocate_at_least( Alloc& a, std::size_t n ); |
(since C++23) |
std::allocate_at_least
calls a.allocate_at_least(n)
and returns its result if the call is well-formed, otherwise, it is equivalent to return {a.allocate(n), n};
.
For an Allocator a
, std::allocator_at_least
tries to allocate a storage for at least n
Alloc::value_type
objects, and provides a fallback mechanism (like those provided by std::allocator_traits
) that allocates a storage for exact n
objects.
Parameters
a | - | an allocator used for allocating storage |
n | - | the lower bound of number of objects to allocate storage for |
Return value
a.allocate_at_least(n)
if it is well-formed, otherwise, {a.allocate(n), n}
.
Exceptions
Throws what and when the selected allocation function throws.
Notes
The allocate_at_least
member function of Allocator types are mainly provided for contiguous containers, e.g. std::vector
and std::basic_string
, in order to reduce reallocation by making their capacity match the actually allocated size when possible. Because std::allocate_at_least
provides a fallback mechanism, it can be directly used where appropriate.
Given an allocator object a
of type Alloc
, let result
denote the value returned from std::allocate_at_least(a, n)
, the storage should be deallocated by a.deallocate(result.ptr, m)
(typically called via std::allocator_traits<Alloc>::deallocate(a, result.ptr, m)
) in order to avoid memory leak.
The argument m
used in deallocation must be not less than n
and not greater than result.count
, otherwise, the behavior is undefined. Note that n
is always equal to result.count
if the allocator does not support allocate_at_least
, which means that m
is required to be equal to n
.
Feature testing macro: __cpp_lib_allocate_at_least
.
Example
See also
(C++23)
|
allocates uninitialized storage at least as large as requested size (public member function of std::allocator<T> ) |
(C++11)
|
provides information about allocator types (class template) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/memory/allocate_at_least