std::allocator::allocate(3)

✨ NAME ✨

okay so bestie, welcome to the std::allocator::allocate(3) page from the C++ Standard Libary manual 💅 the NAME section is literally std::allocator::allocate - std::allocator::allocate, and that’s it. iconic.

🌸 Synopsis 🌸

okay so here’s the synopsis, overload annotations and all 👀

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)
T* allocate( std::size_t n );                                      (2) (since C++17) (until C++20)
[[nodiscard]] constexpr T* allocate( std::size_t n );              (2) (since C++20)

This function 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 hint pointer 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.

Then, this function creates an array of type T[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 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 element of an array of n objects of type T whose elements have not been constructed yet. 💅

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

After calling allocate() and before construction of elements, pointer arithmetic of T* is well-defined within the allocated array, but the behavior is undefined if elements are accessed.

💀 Defect reports 💀

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

• LWG 578 — applied to C++98. Behavior as published: hint was required to be either 0 or a pointer previously returned from allocate() and not yet passed to deallocate(). Correct behavior: not required.
• LWG 3190 — applied to C++11. Behavior as published: allocate() might allocate storage of wrong size. Correct behavior: throws std::bad_array_new_length instead.

👑 See also 👑

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

okay that’s the whole page, mwah 💋 — source/version http://cppreference.com, date 2024.06.10, manual page std::allocator::allocate(3). ✨