std::unique_ptr

From cppreference.com

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.

There are two versions of std::unique_ptr:

1) Manages the lifetime of a single object (e.g. allocated with new)

2) Manages the lifetime of a dynamically-allocated array of objects (e.g. allocated with new[])

unique_ptr is neither copyable nor copy-assignable, so two instances of unique_ptr cannot manage the same object. A non-const unique_ptr can transfer the ownership of the managed object to another unique_ptr. A const std::unique_ptr cannot be transferred, limiting the lifetime of the managed object to the scope in which the pointer was created. When the unique_ptr is destroyed, it disposes of the object through Deleter.

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)

[edit] Member types


Member type	Definition

pointer	std::remove_reference<D>::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


(constructor)	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

release	returns a pointer to the managed object and releases the ownership (public member function)

reset	replaces the managed object (public member function)

swap	swaps the managed objects (public member function)
Observers

get	returns a pointer to the managed object (public member function)

get_deleter	returns the deleter that is used for destruction of the managed object (public member function)

operator bool	checks if there is associated managed object (public member function)
Single-object version, unique_ptr<T>

operator* operator->	dereferences pointer to the managed object (public member function)
Array version, unique_ptr<T[]>

operator[]	provides indexed access to the managed array (public member function)

[edit] Non-member functions


operator== operator!= operator< operator<= operator> operator>=	compares to another `unique_ptr` or with nullptr (function template)

std::swap(std::unique_ptr) (C++11)	specializes the std::swap algorithm (function template)

[edit] Helper classes


std::hash<std::unique_ptr> (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 &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

Language
Concepts
Utilities library
Strings library
Containers library
Algorithms library
Iterators library
Numerics library
Input/output library
Localizations library
Regular expressions library (C++11)
Atomic operations library (C++11)
Thread support library (C++11)

std::unique_ptr

Contents

[edit] Notes

[edit] Member types

[edit] Member functions

Modifiers

Observers

Single-object version, unique_ptr<T>

Array version, unique_ptr<T[]>

[edit] Non-member functions

[edit] Helper classes

[edit] Example