std::allocator::allocate

From cppreference.com
< cpplrm; | memorylrm; | allocator
Dynamic memory management
Uninitialized storage
(C++17)
Garbage collection support
Miscellaneous
(C++20)
(C++11)
(C++11)
C Library
Low level memory management
std::allocator
Member functions
(until C++20)
allocator::allocate
(until C++20)
(until C++20)
Non-member functions
pointer allocate( size_type n, const void * hint = 0 );
(1) (until C++17)
T* allocate( std::size_t n, const void * hint);
(1) (since C++17)
(deprecated)
(removed in C++20)
(2)
T* allocate( std::size_t n );
(since C++17)
(until C++20)
[[nodiscard]] T* allocate( std::size_t n );
(since C++20)

Allocates n * 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 pointer hint 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 to hint.

Parameters

n - the number of objects to allocate storage for
hint - pointer to a nearby memory location

Return value

Pointer to the first byte of a memory block suitably aligned and sufficient to hold an array of n objects of type T.

Exceptions

Throws std::bad_alloc if allocation fails.

Notes

The "unspecified when and how" wording makes it possible to combine 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])

See also

[static]
allocates uninitialized storage using the allocator
(public static member function of std::allocator_traits)