Defined in header <memory> | ||
---|---|---|
template< class T, class Deleter = std::default_delete<T> > class unique_ptr; | (1) | (since C++11) |
template < class T, class Deleter > class unique_ptr<T[], Deleter>; | (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_ptr
managing the object is destroyed -
unique_ptr
managing the object is assigned another pointer viaoperator=
orreset()
.
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 alternatively own no object, in which case it is called empty.
There are two versions of std::unique_ptr
:
new
)new[]
)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 |
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).
If T
is a derived class of some base B
, then std::unique_ptr<T>
is implicitly convertible to std::unique_ptr<B>
. The default deleter of the resulting std::unique_ptr<B>
will use operator delete for B
, leading to undefined behavior unless the destructor of B
is virtual. Note that std::shared_ptr
behaves differently: std::shared_ptr<B>
will use the operator delete for the type T
and the owned object will be deleted correctly even if the destructor of B
is not virtual.
Unlike std::shared_ptr
, std::unique_ptr
may manage an object through any custom handle type that satisfies NullablePointer
. This allows, for example, managing objects located in shared memory, by supplying a Deleter
that defines typedef boost::offset_ptr pointer;
Member types
Member type | Definition |
---|---|
pointer | std::remove_reference<Deleter>::type::pointer if that type exists, otherwise T* . Must satisfy NullablePointer |
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 |
Member functions
constructs a new unique_ptr (public member function) | |
(destructor)
| destructs the managed object if such is present (public member function) |
operator=
| 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, | |
operator*operator->
| dereferences pointer to the managed object (public member function) |
Array version, | |
provides indexed access to the managed array (public member function) |
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) |
Helper classes
(C++11) | hash support for std::unique_ptr (class template specialization) |
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
Please login to continue.