< cpp‎ | memory
Dynamic memory management
Uninitialized storage
(deprecated since c++17)
(deprecated since c++17)
(deprecated since c++17)
Garbage collection support
C Library
Low level memory management
Defined in header <memory>

    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 owns and manages another object through a pointer and disposes of that object when the unique_ptr goes out of scope.

The object is disposed of using the associated deleter when either of the following happens:

  • the managing unique_ptr object is destroyed
  • the managing unique_ptr object is assigned another pointer via operator= or reset().

The object is disposed of using a potentially user-supplied deleter by calling get_deleter()(ptr). The default deleter uses the delete operator, which destroys the object and deallocates 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:

1) Manages a single object (e.g. allocated with new)
2) Manages a dynamically-allocated array of objects (e.g. allocated with 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


[edit] Notes

Only non-const unique_ptr can transfer the ownership of the managed object to another unique_ptr. If an object's lifetime is managed by a const std::unique_ptr, it is limited to the scope in which the pointer was created.

std::unique_ptr is commonly used to manage the lifetime of objects, including:

  • 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). Note that if T is a class template specialization, use of unique_ptr as an operand, e.g. !p requires T's parameters to be complete due to ADL.

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;

[edit] 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

[edit] Member functions

constructs a new unique_ptr
(public member function) [edit]
destructs the managed object if such is present
(public member function) [edit]
assigns the unique_ptr
(public member function) [edit]
returns a pointer to the managed object and releases the ownership
(public member function) [edit]
replaces the managed object
(public member function) [edit]
swaps the managed objects
(public member function) [edit]
returns a pointer to the managed object
(public member function) [edit]
returns the deleter that is used for destruction of the managed object
(public member function) [edit]
checks if there is an associated managed object
(public member function) [edit]
Single-object version, unique_ptr<T>
dereferences pointer to the managed object
(public member function) [edit]
Array version, unique_ptr<T[]>
provides indexed access to the managed array
(public member function) [edit]

[edit] Non-member functions

creates a unique pointer that manages a new object
(function template) [edit]
compares to another unique_ptr or with nullptr
(function template) [edit]
specializes the std::swap algorithm
(function template) [edit]

[edit] Helper classes

hash support for std::unique_ptr
(class template specialization) [edit]

[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
        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


f(const Foo&)
destroying p2...