std::allocator<T>::allocate

	(1)
pointer allocate( size_type n, const void * hint = 0 );			(until C++17)
T* allocate( std::size_t n, const void * hint);			(since C++17) (deprecated) (removed in C++20)
		(2)
T* allocate( std::size_t n );				(since C++17) (until C++20)
[[nodiscard]] constexpr 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.

Use of this function is ill-formed if T is an incomplete 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)

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_array_new_length if std::numeric_limits<std::size_t>::max() / sizeof(T) < n.

(since C++11)

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])

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 3190	C++11	`allocate` might allocate storage of wrong size	throws `bad_array_new_length` instead

Language
Standard Library Headers
Freestanding and hosted implementations
Named requirements
Language support library
Concepts library (C++20)
Diagnostics library
Utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Input/output library
Localizations library
Regular expressions library (C++11)
Atomic operations library (C++11)
Thread support library (C++11)
Filesystem library (C++17)
Technical Specifications

Member functions
allocator::allocator
allocator::~allocator
allocator::address (until C++20)
allocator::allocate
allocator::deallocate
allocator::max_size (until C++20)
allocator::construct (until C++20)
allocator::destroy (until C++20)
Non-member functions
operator==operator!= (until C++20)