std::pmr::p...::new_object(3)

💖 std::pmr::polymorphic_allocator::new_object 💖

okay bestie, you're in the C++ Standard Libary manual, section 3, on the std::pmr::p...::new_object page — yes, that spelling is straight from the page, don't come for me. This one is a C++20 template cutie that hands you a freshly allocated and constructed object without you having to do the rebind dance. ✨

🎀 NAME 🎀

std::pmr::polymorphic_allocator::new_object - std::pmr::polymorphic_allocator::new_object

That's the whole NAME section, bestie. It's giving "I contain multitudes" but make it allocator. 💅

✨ Synopsis ✨

Here's the signature, with the cute little C++20 note included verbatim:

template< class U, class... CtorArgs >                   (since
C++20)
[[nodiscard]] U* new_object( CtorArgs&&... ctor_args );

This function allocates and constructs an object of type U. Slay. 🫶

Given alloc is a std::pmr::polymorphic_allocator<T>:

U* p = alloc.new_object<U>(std::forward<CtorArgs>(ctor_args)...);

is equivalent to

U* p = alloc.allocate_object<U>();
try
{
    alloc.construct(p, std::forward<CtorArgs>(ctor_args)...);
}
catch (...)
{
    alloc.deallocate_object(p);
    throw;
}

🍓 Parameters 🍓

• ctor_args — the arguments to forward to the constructor of U. That's it, that's the parameter. 🎀

🌸 Return value 🌸

A pointer to the allocated and constructed object. Not a pointer to vibes — a pointer to the actual object. 💖

🦋 Notes 🦋

This function was introduced for use with the fully-specialized allocator std::pmr::polymorphic_allocator<>, but it may be useful in any specialization as a shortcut to avoid having to rebind from std::pmr::polymorphic_allocator<T> to std::pmr::polymorphic_allocator<U>, and having to call allocate, construct, and deallocate individually. It's the convenience shortcut, iykyk.

Since U is not deduced, it must be provided as a template argument when calling this function. So yes, you actually have to type new_object<U>(...) — the compiler is not gonna guess your little heart out. 💀

💅 Exceptions 💅

May throw any exceptions thrown by the call to allocate_object or the constructor of U. So if either one is having a moment, this function can absolutely pass that moment along. 😭

🔥 See also 🔥

• allocate_bytes — allocate raw aligned memory from the underlying resource (C++20) (public member function)
• allocate_object — allocates raw memory suitable for an object or an array (C++20) (public member function)
• allocate — allocate memory (public member function)
• allocate — allocates uninitialized storage using the allocator [static] (public static member function of std::allocator_traits<Alloc>)
• allocate — allocates memory (public member function of std::pmr::memory_resource)

---

mwah 💋 — source: http://cppreference.com, version/date: 2024.06.10, footer page: std::pmr::p...::new_object(3). bye bestie! 🫶