|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Member functions | ||||
(until C++20) | ||||
allocator::allocate_at_least (C++23) | ||||
(until C++20) | ||||
(until C++20) | ||||
(until C++20) | ||||
| Non-member functions | ||||
(until C++20) |
constexprstd::allocation_result<T*,std::size_t> allocate_at_least(std::size_t n); | (since C++23) | |
Allocatescount* sizeof(T) bytes of uninitialized storage, wherecount is an unspecified integer value not less thann, by calling::operator new (possibly with an additionalstd::align_val_t argument), but it is unspecified when and how this function is called.
Then, this function creates an array of typeT[count] in the storage and starts its lifetime, but does not start lifetime of any of its elements.
In order to use this function in a constant expression, the allocated storage must be deallocated within the evaluation of the same expression.
Use of this function is ill-formed ifT is anincomplete type.
Contents |
| n | - | the lower bound of number of objects to allocate storage for |
std::allocation_result<T*>{p, count}, wherep points to the first element of an array ofcount objects of typeT whose elements have not been constructed yet.
Throwsstd::bad_array_new_length ifstd::numeric_limits<std::size_t>::max()/ sizeof(T)< n, orstd::bad_alloc if allocation fails.
allocate_at_least is 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.
The "unspecified when and how" wording makes it possible tocombine or optimize away heap allocations made by the standard library containers, even though such optimizations are disallowed for direct calls to::operator new. For example, this is implemented by libc++ ([1] and[2]).
After callingallocate_at_least and before construction of elements, pointer arithmetic ofT* is well-defined within the allocated array, but the behavior is undefined if elements are accessed.
| Feature-test macro | Value | Std | Feature |
|---|---|---|---|
__cpp_lib_allocate_at_least | 202302L | (C++23) | allocate_at_least etc. |
#include <memory>#include <print> int main(){conststd::size_t count{69};std::allocator<int> alloc;std::allocation_result res{alloc.allocate_at_least(count)};std::print("count: {}\n""res.ptr: {}\n""res.count: {}\n", count, res.ptr, res.count); /* construct, use, then destroy elements */ alloc.deallocate(res.ptr, res.count);}
Possible output:
count: 69res.ptr: 0x555a486a0960res.count: 96
(C++23) | records the address and the actual size of storage allocated byallocate_at_least(class template)[edit] |
[static](C++23) | allocates storage at least as large as the requested size via an allocator (public static member function of std::allocator_traits<Alloc>)[edit] |
