|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Member functions | ||||
(until C++20) | ||||
allocator::allocate | ||||
(C++23) | ||||
(until C++20) | ||||
(until C++20) | ||||
(until C++20) | ||||
| Non-member functions | ||||
(until C++20) |
| (1) | ||
pointer allocate( size_type n,constvoid* hint=0); | (until C++17) | |
T* allocate(std::size_t n,constvoid* hint); | (since C++17) (deprecated) (removed in C++20) | |
| (2) | ||
T* allocate(std::size_t n); | (since C++17) (until C++20) | |
constexpr T* allocate(std::size_t n); | (since C++20) | |
Allocatesn* sizeof(T) bytes of uninitialized storage by calling::operator new(std::size_t)or::operator new(std::size_t,std::align_val_t)(since C++17), but it is unspecified when and how this function is called. The pointerhint may be used to provide locality of reference: the allocator, if supported by the implementation, will attempt to allocate the new memory block as close as possible tohint.
Then, this function creates an array of typeT[n] in the storage and starts its lifetime, but does not start lifetime of any of its elements.
Use of this function is ill-formed ifT is anincomplete type.
In order to use this function in a constant expression, the allocated storage must be deallocated within the evaluation of the same expression. | (since C++20) |
Contents |
| n | - | the number of objects to allocate storage for |
| hint | - | pointer to a nearby memory location |
Pointer to the first element of an array ofn 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. | (since C++11) |
Throwsstd::bad_alloc if allocation fails.
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() and before construction of elements, pointer arithmetic ofT* is well-defined within the allocated array, but the behavior is undefined if elements are accessed.
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 578 | C++98 | hint was required to be either0 or a pointer previously returned from allocate()and not yet passed todeallocate() | not required |
| LWG 3190 | C++11 | allocate() might allocate storage of wrong size | throwsstd::bad_array_new_length instead |
[static] | allocates uninitialized storage using the allocator (public static member function of std::allocator_traits<Alloc>)[edit] |
