|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
staticconstexprstd::allocation_result<pointer, size_type> allocate_at_least( Alloc& a, size_type n); | (since C++23) | |
allocate_at_least callsa.allocate_at_least(n) and returns its result if the call is well-formed, otherwise, it is equivalent toreturn{a.allocate(n), n};.
allocator_at_least tries to allocate a storage for at leastnvalue_type objects, and provides a fallback mechanism that allocates a storage for exactn objects.
Contents |
| a | - | an allocator used for allocating storage |
| n | - | the lower bound of number of objects to allocate storage for |
a.allocate_at_least(n) if it is well-formed.
Otherwise,std::allocation_result<pointer, size_type>{a.allocate(n), n}.
Throws what and when the selected allocation function throws.
Theallocate_at_least member function ofAllocator types are mainly provided for contiguous containers, e.g.std::vector andstd::basic_string, in order to reduce reallocation by making their capacity match the actually allocated size when possible. Becauseallocate_at_least provides a fallback mechanism, it can be directly used where appropriate.
Given an allocator objecta of typeAlloc, letresult denote the value returned fromstd::allocator_traits<Alloc>::allocate_at_least(a, n), the storage should be deallocated bya.deallocate(result.ptr, m) (typically called viastd::allocator_traits<Alloc>::deallocate(a, result.ptr, m)) in order to avoid memory leak.
The argumentm used in deallocation must be not less thann and not greater thanresult.count, otherwise, the behavior is undefined. Note thatn is always equal toresult.count if the allocator does not provideallocate_at_least, which means thatm is required to be equal ton.
| Feature-test macro | Value | Std | Feature |
|---|---|---|---|
__cpp_lib_allocate_at_least | 202302L | (C++23) | allocate_at_least etc. |
| This section is incomplete Reason: no example |
(C++23) | allocates uninitialized storage at least as large as requested size (public member function of std::allocator<T>)[edit] |
