C++ Reference ยท Memory and Utilities
C++ placement new
Reference for C++ placement new: construct an object at an address you provide, alignment, manual destructor calls, std::construct_at and std::launder.
Placement new constructs an object in storage that already exists. It does not allocate anything. You give it an address, and it runs the constructor there and returns a pointer. Memory pools, containers such as std::vector, std::optional and std::variant all use this technique to separate storage from object lifetime.
You need #include <new>. Because no allocation happens, no matching delete exists: you must call the destructor yourself and manage the storage separately.
alignas(Widget) unsigned char buf[sizeof(Widget)]; Widget* w = new (buf) Widget(args); w->~Widget();
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Syntax
void* operator new(std::size_t, void* where) noexcept; // placement form, in <new> new (address) T(args) new (address) T{args} new (address) T[n] // array form (avoid: overhead is unspecified) std::construct_at(T* p, Args&&... args); // C++20, <memory>, constexpr std::destroy_at(T* p); // C++17 std::launder(T* p); // C++17
| Name | Description |
|---|---|
address |
Pointer to storage that is large enough and suitably aligned for T. |
args |
Constructor arguments. |
Returns: a pointer to the new object (T*). Errors: if the constructor throws, the exception propagates and the storage is left as it was (nothing to free). Insufficient size or wrong alignment is undefined behavior; the compiler cannot check it.
Usage notes
- Alignment: declare buffers with
alignas(T), for examplealignas(T) std::byte buf[sizeof(T)](std::aligned_storageis deprecated). A plainchar buf[N]is not guaranteed to be aligned. - Destruction: call
p->~T()(orstd::destroy_at(p)) before reusing or releasing the storage. For trivially destructible types nothing is required. - Lifetime ends when the storage is reused or released, or when the destructor starts. The pointer returned by placement
newis the one to use. std::launder: after you place a new object over an old one of the same type that hasconstor reference members, the old pointer may not name the new object; laundering the pointer fixes that. When you keep the pointer returned bynew, you do not need it.- Don't
deletea placement-new object. Deleting it would try to free memory you did not get fromnew. - Arrays:
new (p) T[n]may use extra bytes for a cookie, so you cannot know how much storage to give it. Construct elements in a loop instead. - Exceptions in loops: if the third constructor throws, destroy the first two before leaving, or you leak resources.
- Prefer
std::construct_atinconstexprcode; plain placementnewis not allowed in constant evaluation before C++26. - The standard algorithms
std::uninitialized_copy,std::uninitialized_fillandstd::uninitialized_default_constructdo this loop correctly, including cleanup on failure.