{"title":"std::unique_ptr","description":null,"content":"`std::unique_ptr` is the standard library's RAII wrapper for a heap-allocated `T` with exclusive ownership: one pointer owns the object, and when that pointer goes out of scope, the object is deleted. It replaces the raw `new`/`delete` pair you saw earlier in this section with a type the compiler keeps honest. This chapter covers what `unique_ptr` is, how to construct and move it, the operations it exposes, custom deleters, and the array specialisation. Sibling chapters cover `std::shared_ptr`, `std::weak_ptr`, `std::make_unique`, and the rest of the smart-pointer story.\n\n---\n\n# Why unique_ptr Exists\n\nManual `new` and `delete` are a long-running source of bugs. Forget the `delete` and memory leaks. Run `delete` twice and the heap is corrupted. Throw an exception between the `new` and the `delete` and the cleanup never happens. The RAII chapter framed the general idea; `std::unique_ptr` is the concrete tool the standard library provides for the most common case: \"one object allocated on the heap, freed exactly once\".\n\nA leaky function that looks innocent at first glance.\n\n\n```cpp\n#include \n#include \n#include \n\nclass Order {\npublic:\n Order(std::string id, double total) : id_(std::move(id)), total_(total) {\n std::cout << \"Order \" << id_ << \" constructed\" << std::endl;\n }\n ~Order() {\n std::cout << \"Order \" << id_ << \" destroyed\" << std::endl;\n }\n double total() const { return total_; }\n\nprivate:\n std::string id_;\n double total_;\n};\n\nvoid validate(double total) {\n if (total < 0.0) throw std::runtime_error(\"negative total\");\n}\n\nvoid process(double total) {\n Order* order = new Order(\"ORD-7\", total);\n validate(total); // may throw, leaking *order\n std::cout << \"Total: $\" << order->total() << std::endl;\n delete order; // never reached on a throw\n}\n\nint main() {\n try {\n process(89.97);\n process(-1.0);\n } catch (const std::exception& e) {\n std::cout << \"Failed: \" << e.what() << std::endl;\n }\n return 0;\n}\n```\n\n\nThe second call constructs an `Order`, then `validate` throws before `delete` runs, and the destructor never fires. The leak isn't a typo; the code has a clean `delete` at the bottom and still leaks. Any path that exits the function before that line, whether by `return`, by exception, or by a future maintainer adding an early `return`, leaks.\n\n`std::unique_ptr` fixes this by tying the deletion to a stack object's lifetime, so the cleanup follows the same rules as any local variable.\n\n\n```cpp\n#include \n#include \n#include \n#include \n\nclass Order {\npublic:\n Order(std::string id, double total) : id_(std::move(id)), total_(total) {\n std::cout << \"Order \" << id_ << \" constructed\" << std::endl;\n }\n ~Order() {\n std::cout << \"Order \" << id_ << \" destroyed\" << std::endl;\n }\n double total() const { return total_; }\n\nprivate:\n std::string id_;\n double total_;\n};\n\nvoid validate(double total) {\n if (total < 0.0) throw std::runtime_error(\"negative total\");\n}\n\nvoid process(double total) {\n std::unique_ptr order(new Order(\"ORD-7\", total));\n validate(total);\n std::cout << \"Total: $\" << order->total() << std::endl;\n}\n\nint main() {\n try {\n process(89.97);\n process(-1.0);\n } catch (const std::exception& e) {\n std::cout << \"Failed: \" << e.what() << std::endl;\n }\n return 0;\n}\n```\n\n\nBoth runs destroy the `Order`. The throw path triggers stack unwinding, which destroys the local `unique_ptr`, whose destructor runs `delete` on the owned `Order`. The cleanup is no longer a separate line that can be skipped; it's wired into the local variable's lifetime.\n\n---\n\n# Constructing a unique_ptr\n\nThe simplest constructor takes a raw pointer to a heap-allocated object and takes over ownership of it.\n\n\n```cpp\n#include \n#include \n#include \n\nclass Product {\npublic:\n Product(std::string name, double price) : name_(std::move(name)), price_(price) {}\n const std::string& name() const { return name_; }\n double price() const { return price_; }\n\nprivate:\n std::string name_;\n double price_;\n};\n\nint main() {\n std::unique_ptr p(new Product(\"Wireless Headphones\", 79.99));\n std::cout << p->name() << \" costs $\" << p->price() << std::endl;\n return 0;\n}\n```\n\n\nThe default constructor creates an empty `unique_ptr` that owns nothing. It compares equal to `nullptr` and converts to `false` in a boolean context.\n\n\n```cpp\n#include \n#include \n\nint main() {\n std::unique_ptr empty;\n if (!empty) {\n std::cout << \"owns nothing\" << std::endl;\n }\n\n std::unique_ptr nulled(nullptr);\n std::cout << \"nulled == nullptr: \" << (nulled == nullptr) << std::endl;\n return 0;\n}\n```\n\n\nTwo things about the raw-pointer constructor matter. First, it's `explicit`, so `std::unique_ptr p = new Product(...)` doesn't compile. The construction has to be spelled out. That's deliberate, because handing a raw pointer to a `unique_ptr` is the moment ownership transfers, and the language requires that to be explicit.\n\nSecond, once a raw pointer has been given to a `unique_ptr`, that same raw pointer must not be passed to another `unique_ptr`. Doing so creates two owners of the same heap object, and both will try to delete it. The result is a double-free, which corrupts the heap and usually crashes the program.\n\n\n```cpp\nProduct* raw = new Product(\"Mouse Pad\", 14.99);\nstd::unique_ptr a(raw);\nstd::unique_ptr b(raw); // wrong: both a and b will delete *raw\n```\n\n\nThe preferred way to construct a `unique_ptr` is `std::make_unique(args...)` (C++14), which forwards its arguments to `T`'s constructor and returns a `unique_ptr`. It avoids the explicit `new` entirely and is exception-safe in ways the raw constructor isn't. This chapter sticks with the raw-pointer constructor to keep the mechanics visible; a later lesson is dedicated to `make_unique` and the rationale.\n\n`std::unique_ptr` (with the default deleter) is the same size as `T*`. There is no extra allocation, no reference count, no atomic operation on construction or destruction. The overhead compared to a raw pointer is zero in both time and space.\n\n---\n\n# Move-Only Semantics\n\nA `unique_ptr` cannot be copied. The copy constructor and copy assignment operator are explicitly deleted. If two `unique_ptr` objects could point to the same heap object, both would try to delete it when they went out of scope, which is the double-free just described. The language prevents the bug at compile time.\n\n\n```cpp\n#include \n\nint main() {\n std::unique_ptr a(new int(42));\n std::unique_ptr b = a; // does not compile\n return 0;\n}\n```\n\n\nWith g++ this fails with a message like `use of deleted function 'std::unique_ptr<...>::unique_ptr(const std::unique_ptr<...>&)'`. The compiler refuses to copy.\n\nThe alternative is to **move**. Moving a `unique_ptr` transfers ownership: the source pointer becomes empty (a null `unique_ptr`), and the destination pointer takes over the owned object. Use `std::move` to mark the source as movable.\n\n\n```cpp\n#include \n#include \n#include \n\nint main() {\n std::unique_ptr a(new int(42));\n std::cout << \"a before move: \" << (a ? \"not null\" : \"null\") << std::endl;\n\n std::unique_ptr b = std::move(a);\n std::cout << \"a after move: \" << (a ? \"not null\" : \"null\") << std::endl;\n std::cout << \"b after move: \" << *b << std::endl;\n return 0;\n}\n```\n\n\nThe owned `int` was never copied. The pointer value moved from `a` to `b`, and `a` is now empty. When `b` goes out of scope, the `int` is deleted exactly once. When `a` goes out of scope, its destructor runs but finds nothing to delete, which is fine.\n\nThe diagram captures what happens on a move. Cyan boxes are stack-side `unique_ptr` objects, orange is the heap-allocated `Order`, and green marks the empty state.\n\n\n```mermaid\nflowchart LR\n subgraph Before[\"Before move\"]\n A1[unique_ptr a]:::cyan -->|owns| O1[Order on heap]:::orange\n B1[unique_ptr b
empty]:::green\n end\n\n subgraph After[\"After std::move(a) into b\"]\n A2[unique_ptr a
empty]:::green\n B2[unique_ptr b]:::cyan -->|owns| O2[Order on heap]:::orange\n end\n\n Before --> After\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\nThe heap object never moves. Only the ownership token, the pointer value, hops from `a` to `b`. After the move, `a` is in a valid but empty state. A new pointer can be assigned into it or it can go out of scope, but it shouldn't be dereferenced.\n\nA natural place this shows up is a factory function that builds an `Order` and hands ownership back to the caller.\n\n\n```cpp\n#include \n#include \n#include \n#include \n\nclass Order {\npublic:\n Order(std::string id, double total) : id_(std::move(id)), total_(total) {}\n const std::string& id() const { return id_; }\n double total() const { return total_; }\n\nprivate:\n std::string id_;\n double total_;\n};\n\nstd::unique_ptr createOrder(const std::string& customer, double total) {\n return std::unique_ptr(new Order(\"ORD-\" + customer, total));\n}\n\nint main() {\n std::unique_ptr order = createOrder(\"CUST-7\", 89.97);\n std::cout << order->id() << \" total $\" << order->total() << std::endl;\n return 0;\n}\n```\n\n\nNo `std::move` is needed in the `return` statement because the returned local is already an rvalue at that point, so the compiler picks the move constructor automatically. At the call site, `order` takes ownership; when `main` exits, the `Order` is destroyed.\n\n---\n\n# The Common Operations\n\nA `unique_ptr` behaves like a pointer at the use site: it overloads the operators that make pointers natural and adds a few member functions for the lifecycle operations.\n\n\n| Operation | What it does |\n|-----------|--------------|\n| `operator*` | Dereferences to a reference to the owned object |\n| `operator->` | Member access on the owned object |\n| `operator bool()` | `true` if the pointer owns an object, `false` if null |\n| `get()` | Returns the underlying raw pointer without giving up ownership |\n| `release()` | Returns the raw pointer and gives up ownership (caller becomes responsible for `delete`) |\n| `reset(p)` | Deletes the current object and takes ownership of `p` (defaults to `nullptr`) |\n| `swap(other)` | Swaps the owned pointers between two `unique_ptr` objects |\n\n\n`operator*` and `operator->` are the everyday operations. They make the smart pointer behave like a raw pointer at the use site.\n\n\n```cpp\n#include \n#include \n#include \n\nclass Product {\npublic:\n Product(std::string name, double price) : name_(std::move(name)), price_(price) {}\n const std::string& name() const { return name_; }\n double price() const { return price_; }\n\nprivate:\n std::string name_;\n double price_;\n};\n\nint main() {\n std::unique_ptr p(new Product(\"USB Cable\", 9.99));\n std::cout << p->name() << std::endl; // operator->\n std::cout << (*p).price() << std::endl; // operator*\n if (p) std::cout << \"p owns something\" << std::endl; // operator bool\n return 0;\n}\n```\n\n\n`get()`, `release()`, and `reset()` are the lifecycle controls. They show up for interactions with code that takes raw pointers, or for rebinding a smart pointer to a different object.\n\n\n```cpp\n#include \n#include \n\nvoid printValue(int* raw) {\n if (raw) std::cout << \"raw value: \" << *raw << std::endl;\n}\n\nint main() {\n std::unique_ptr p(new int(10));\n\n printValue(p.get()); // pass underlying pointer, ownership stays with p\n std::cout << \"still owns? \" << (p ? \"yes\" : \"no\") << std::endl;\n\n p.reset(new int(20)); // delete old object, own new one\n std::cout << \"after reset: \" << *p << std::endl;\n\n int* leaked = p.release(); // give up ownership; p is now empty\n std::cout << \"after release, p empty? \" << (p ? \"no\" : \"yes\") << std::endl;\n delete leaked; // caller is now responsible\n return 0;\n}\n```\n\n\nThree details are worth pinning down.\n\n`get()` is for passing the address to an API that wants a raw pointer. It does not transfer ownership. Don't call `delete` on what `get()` returns, because the `unique_ptr` will do that itself later, and a double-free will follow.\n\n`release()` is the opposite: it hands the raw pointer back and forgets about it. The `unique_ptr` will not delete that object anymore. The caller now owns it and must delete it, or pass it to another owner. `release()` is rare in modern code but useful when interoperating with C APIs that take ownership of a pointer.\n\n`reset()` deletes the currently owned object (if any) and takes over the new one passed in. Calling `reset()` with no argument is equivalent to `reset(nullptr)` and deletes whatever is owned, leaving the `unique_ptr` empty.\n\n---\n\n# A unique_ptr as a Class Member\n\nA common use of `unique_ptr` is as a member of another class. The owning class doesn't have to write a destructor; the `unique_ptr` member cleans up its owned object automatically when the owner is destroyed. This is the rule of zero in practice: when the only \"resource\" is something a smart pointer already manages, no destructor, copy constructor, or assignment operator is needed.\n\n\n```cpp\n#include \n#include \n#include \n\nclass Address {\npublic:\n Address(std::string street, std::string city)\n : street_(std::move(street)), city_(std::move(city)) {}\n void print() const {\n std::cout << street_ << \", \" << city_ << std::endl;\n }\n\nprivate:\n std::string street_;\n std::string city_;\n};\n\nclass Customer {\npublic:\n Customer(std::string name, std::unique_ptr

shippingAddress)\n : name_(std::move(name)), shipping_(std::move(shippingAddress)) {}\n\n void print() const {\n std::cout << name_ << \" ships to \";\n shipping_->print();\n }\n\nprivate:\n std::string name_;\n std::unique_ptr

shipping_;\n};\n\nint main() {\n auto addr = std::unique_ptr

(new Address(\"221B Baker St\", \"London\"));\n Customer c(\"Sherlock\", std::move(addr));\n c.print();\n return 0;\n}\n```\n\n\n`Customer` doesn't declare a destructor. The default destructor that the compiler synthesises destroys the members in reverse order of declaration, which calls the `unique_ptr` destructor, which deletes the `Address`. Adding a second resource later, like a credit card record, wrapped in another `unique_ptr`, doesn't require writing any destructor code.\n\n`Customer` itself is not copyable, because one of its members (`unique_ptr`) is not copyable. The compiler deletes the copy operations to keep ownership rules consistent. To pass a `Customer` around, move it. That's a feature, not a limitation: most domain objects with owned heap state are conceptually unique, and the compiler enforces it automatically.\n\n---\n\n# Custom Deleters\n\nNot every resource is freed with plain `delete`. A `unique_ptr` can be configured with a **custom deleter** that runs instead of `delete` when the smart pointer destroys its owned object. The deleter is the second template parameter of `unique_ptr`.\n\n\n```cpp\ntemplate>\nclass unique_ptr;\n```\n\n\n`std::default_delete` calls `delete` on the pointer. For other cleanup, pass a different deleter type.\n\nA common case is a C-style resource freed with a free function. C's `` returns a `FILE*` that must be released with `std::fclose`, not `delete`. Wrap it in a `unique_ptr` with a function-pointer deleter.\n\n\n```cpp\n#include \n#include \n#include \n\nint main() {\n std::unique_ptr log(\n std::fopen(\"orders.log\", \"w\"), &std::fclose);\n\n if (!log) {\n std::cout << \"could not open log\" << std::endl;\n return 1;\n }\n std::fputs(\"order ORD-7 placed\\n\", log.get());\n std::cout << \"wrote log entry\" << std::endl;\n return 0;\n // log's destructor calls std::fclose on the FILE*, not delete\n}\n```\n\n\n`decltype(&std::fclose)` spells out the type of the deleter (a function pointer). The second constructor argument is the actual deleter to use. When the `unique_ptr` is destroyed, it calls `std::fclose(file)` instead of `delete file`. Using a default-deleter `unique_ptr` here would call `delete` on a `FILE*`, which was never allocated with `new`, and the behaviour would be undefined.\n\nA cleaner option, especially for one-off custom cleanup, is a lambda. Wrapping it in a `unique_ptr` requires storing the lambda type, which is unique per lambda expression and not spellable directly. Use `decltype` on the lambda variable to get the type.\n\n\n```cpp\n#include \n#include \n#include \n\nclass Order {\npublic:\n Order(std::string id) : id_(std::move(id)) {\n std::cout << \"Order \" << id_ << \" constructed\" << std::endl;\n }\n const std::string& id() const { return id_; }\n\nprivate:\n std::string id_;\n};\n\nint main() {\n auto auditingDelete = [](Order* o) {\n std::cout << \"Auditing delete of \" << o->id() << std::endl;\n delete o;\n };\n\n std::unique_ptr p(\n new Order(\"ORD-7\"), auditingDelete);\n\n std::cout << \"Order ID: \" << p->id() << std::endl;\n return 0;\n}\n```\n\n\nThe lambda runs in place of plain `delete`. It logs the deletion and then frees the object. The same pattern works with a functor (a class with `operator()`), which is the option to use when the deleter needs to hold state across instances.\n\nThere's one consequence to know about. The deleter is part of the `unique_ptr`'s type. A `unique_ptr` (default deleter) is a different type from `unique_ptr`. They are not interchangeable in function signatures or containers. With the default deleter, the `unique_ptr` is one pointer wide; with a stateful custom deleter, it grows by the size of the deleter.\n\nA `unique_ptr` with a stateless deleter (function pointer, captureless lambda, empty functor) is essentially the same size as a raw pointer thanks to the empty base optimisation. A `unique_ptr` with a stateful deleter is larger by the size of the deleter.\n\n---\n\n# Arrays with unique_ptr\n\n`std::unique_ptr` has a specialisation for arrays, written `std::unique_ptr`. It calls `delete[]` instead of `delete` on destruction and supports `operator[]` for indexed access. Use it for a dynamically-sized C-style array; in most cases a `std::vector` is the better choice, but the array specialisation exists for cases that need the raw layout (interop with C APIs, fixed allocation patterns).\n\n\n```cpp\n#include \n#include \n\nint main() {\n std::unique_ptr stockLevels(new int[5]{10, 25, 3, 17, 42});\n\n for (int i = 0; i < 5; ++i) {\n std::cout << \"Slot \" << i << \": \" << stockLevels[i] << std::endl;\n }\n return 0;\n // delete[] runs automatically, not delete\n}\n```\n\n\nThe array specialisation does not provide `operator*` or `operator->` (there's no single object to dereference). Element access goes through `operator[]`. Indexing past the end is undefined behaviour, exactly as with a raw array.\n\nThe reason this specialisation exists is the mismatch between `delete` and `delete[]`. Calling plain `delete` on a pointer allocated with `new int[5]` is undefined behaviour. The array specialisation makes the right form of deletion automatic. Without it, a custom deleter would be required every time, which is what the specialisation already provides.\n\n---\n\n# When to Use unique_ptr\n\nA few common patterns make `unique_ptr` the obvious choice:\n\n- **Factory functions** that build an object on the heap and return ownership to the caller. The function signature `std::unique_ptr loadProduct(...)` makes the ownership transfer visible, and the caller decides what to do with the returned pointer (keep it, hand it to another owner, drop it).\n- **Class members that own a heap resource.** A `unique_ptr` member removes the need for a destructor; the default destructor cleans up correctly, and the rule of zero applies.\n- **Polymorphic ownership through a base-class pointer.** A container of `Order` subclasses (say `RetailOrder`, `WholesaleOrder`) uses `std::vector>`. The vector owns the base pointers; deleting through them works as long as `Order` has a virtual destructor.\n- **Replacing any raw `new`/`delete` pair.** A `new` followed somewhere by `delete` almost always wants to become a single `unique_ptr` (or its `make_unique` equivalent) instead.\n\nThe polymorphic-container pattern in code. It pulls together construction, move, and member-access operators.\n\n\n```cpp\n#include \n#include \n#include \n#include \n#include \n\nclass Order {\npublic:\n Order(std::string id) : id_(std::move(id)) {}\n virtual ~Order() = default;\n virtual void print() const = 0;\n const std::string& id() const { return id_; }\n\nprotected:\n std::string id_;\n};\n\nclass RetailOrder : public Order {\npublic:\n RetailOrder(std::string id, double total)\n : Order(std::move(id)), total_(total) {}\n void print() const override {\n std::cout << \"Retail \" << id_ << \" $\" << total_ << std::endl;\n }\n\nprivate:\n double total_;\n};\n\nclass WholesaleOrder : public Order {\npublic:\n WholesaleOrder(std::string id, int units, double unitPrice)\n : Order(std::move(id)), units_(units), unitPrice_(unitPrice) {}\n void print() const override {\n std::cout << \"Wholesale \" << id_ << \" \"\n << units_ << \" @ $\" << unitPrice_ << std::endl;\n }\n\nprivate:\n int units_;\n double unitPrice_;\n};\n\nint main() {\n std::vector> orders;\n orders.push_back(std::unique_ptr(new RetailOrder(\"ORD-1\", 49.99)));\n orders.push_back(std::unique_ptr(new WholesaleOrder(\"ORD-2\", 200, 4.50)));\n\n for (const auto& o : orders) {\n o->print();\n }\n return 0;\n // vector destructor destroys each unique_ptr, each runs delete via virtual destructor\n}\n```\n\n\nThe vector owns the smart pointers. Each smart pointer owns its concrete `Order`. When the vector is destroyed, every element's destructor runs, each `unique_ptr` calls `delete` on its owned object, and the virtual destructor on `Order` ensures the derived class's destructor runs correctly. No leaks, no manual deletes, and the ownership story is plain from the type alone.\n\n`Order` declares a virtual destructor on purpose. Deleting a derived object through a base pointer without a virtual destructor is undefined behaviour, and `unique_ptr` does exactly that internally. Whenever derived objects are stored through a base-class `unique_ptr`, the base class needs `virtual ~Base() = default;` (or an equivalent virtual destructor).","pageType":"cpp"}

std::unique_ptr

Get Premium