SysTutorials

Linux Manual Pages › Section 3

stdallocatorallocate(3)

std::allocator<T>::allocate – std::allocator<T>::allocate

Synopsis

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

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