std::unique_ptr
| Defined in header <memory>
|
||
| template< class T, |
(1) | (since C++11) |
| template < class T, |
(2) | (since C++11) |
std::unique_ptr is a smart pointer that retains sole ownership of an object through a pointer and destroys that object when the unique_ptr goes out of scope. No two unique_ptr instances can manage the same object.
The object is destroyed and its memory deallocated when either of the following happens:
-
unique_ptrmanaging the object is destroyed -
unique_ptrmanaging the object is assigned another pointer via operator= or reset().
The object is destroyed using a potentially user-supplied deleter by calling Deleter(ptr). The deleter calls the destructor of the object and dispenses the memory.
A unique_ptr may also own no objects, in which case it is called empty.
There are two versions of std::unique_ptr:
The class satisfies the requirements of MoveConstructible and MoveAssignable, but not the requirements of either CopyConstructible or CopyAssignable.
| Type requirements | ||
-Deleter must be FunctionObject or lvalue reference to a FunctionObject or lvalue reference to function, callable with an argument of type unique_ptr<T, Deleter>::pointer
|
Contents |
[edit] Notes
Only non-const unique_ptr can transfer the ownership of the managed object to another unique_ptr. The lifetime of an object managed by const std::unique_ptr is limited to the scope in which the pointer was created.
Typical uses of std::unique_ptr include:
- providing exception safety to classes and functions that handle objects with dynamic lifetime, by guaranteeing deletion on both normal exit and exit through exception
- passing ownership of uniquely-owned objects with dynamic lifetime into functions
- acquiring ownership of uniquely-owned objects with dynamic lifetime from functions
- as the element type in move-aware containers, such as std::vector, which hold pointers to dynamically-allocated objects (e.g. if polymorphic behavior is desired)
std::unique_ptr may be constructed for an incomplete type T, such as to facilitate the use as a handle in the Pimpl idiom. If the default deleter is used, T must be complete at the point in code where the deleter is invoked, which happens in the destructor, move assignment operator, and reset member function of std::unique_ptr. (Conversely, std::shared_ptr can't be constructed from a raw pointer to incomplete type, but can be destroyed where T is incomplete.)
[edit] Member types
| Member type | Definition |
| pointer | std::remove_reference<Deleter>::type::pointer if that type exists, otherwise T* |
| element_type | T, the type of the object managed by this unique_ptr
|
| deleter_type | Deleter, the function object or lvalue reference to function or to function object, to be called from the destructor
|
[edit] Member functions
constructs a new unique_ptr (public member function) | |
| destructs the managed object if such is present (public member function) | |
assigns the unique_ptr (public member function) | |
Modifiers | |
| returns a pointer to the managed object and releases the ownership (public member function) | |
| replaces the managed object (public member function) | |
| swaps the managed objects (public member function) | |
Observers | |
| returns a pointer to the managed object (public member function) | |
| returns the deleter that is used for destruction of the managed object (public member function) | |
| checks if there is associated managed object (public member function) | |
Single-object version,
| |
| dereferences pointer to the managed object (public member function) | |
Array version,
| |
| provides indexed access to the managed array (public member function) | |
[edit] Non-member functions
| (C++14) |
creates a unique pointer that manages a new object (function template) |
compares to another unique_ptr or with nullptr (function template) | |
| (C++11) |
specializes the std::swap algorithm (function template) |
[edit] Helper classes
| (C++11) |
hash support for std::unique_ptr (class template specialization) |
[edit] Example
#include <iostream> #include <memory> struct Foo { Foo() { std::cout << "Foo::Foo\n"; } ~Foo() { std::cout << "Foo::~Foo\n"; } void bar() { std::cout << "Foo::bar\n"; } }; void f(const Foo &) { std::cout << "f(const Foo&)\n"; } int main() { std::unique_ptr<Foo> p1(new Foo); // p1 owns Foo if (p1) p1->bar(); { std::unique_ptr<Foo> p2(std::move(p1)); // now p2 owns Foo f(*p2); p1 = std::move(p2); // ownership returns to p1 std::cout << "destroying p2...\n"; } if (p1) p1->bar(); // Foo instance is destroyed when p1 goes out of scope }
Output:
Foo::Foo Foo::bar f(const Foo&) destroying p2... Foo::bar Foo::~Foo