unique_ptr Class

The latest version of this topic can be found at unique_ptr Class.

Stores a pointer to an owned object or array. The object/array is owned by no other unique_ptr. The object/array is destroyed when the unique_ptr is destroyed.

Syntax

class unique_ptr {  
   public:  
   unique_ptr();
   unique_ptr(nullptr_t Nptr);
   explicit unique_ptr(pointer Ptr);
   unique_ptr(pointer Ptr,  
   typename conditional<is_reference<Del>::value, Del,  
   typename add_reference<const Del>::type>::type Deleter);
   unique_ptr (pointer Ptr,  
   typename remove_reference<Del>::type&& Deleter);
   unique_ptr (unique_ptr&& Right);
   template <class T2, Class Del2>  
   unique_ptr(unique_ptr<T2, Del2>&& Right);
   unique_ptr(const unique_ptr& Right) = delete;  
   unique_ptr& operator=(const unique_ptr& Right) = delete;  
   };  

//Specialization for arrays:  
template <class T, class D>  
class unique_ptr<T[], D> {   public:          typedef pointer;  
    typedef T element_type;  
    typedef D deleter_type;  
    constexpr unique_ptr() noexcept;  
    template <class U>  
explicit unique_ptr(U p) noexcept;  
    template <class U>  
unique_ptr(U p, see below d) noexcept;  
    template <class U>  
unique_ptr(U p, see below d) noexcept;  
    unique_ptr(unique_ptr&& u) noexcept;  
    constexpr unique_ptr(nullptr_t) noexcept : unique_ptr() { }     template <class U, class E>  
unique_ptr(unique_ptr<U, E>&& u) noexcept;  
 ~unique_ptr();
unique_ptr& operator=(unique_ptr&& u) noexcept;  
    template <class U, class E>  
unique_ptr& operator=(unique_ptr<U, E>&& u) noexcept;  
    unique_ptr& operator=(nullptr_t) noexcept;  
    T& operator[](size_t i) const;

 
    pointer get() const noexcept;  
    deleter_type& get_deleter() noexcept;  
    const deleter_type& get_deleter() const noexcept;  
    explicit operator bool() const noexcept;  
    pointer release() noexcept;  
    void reset(pointer p = pointer()) noexcept;  
    void reset(nullptr_t = nullptr) noexcept;  
    template <class U>  
void reset(U p) noexcept = delete;  
    void swap(unique_ptr& u) noexcept;  // disable copy from lvalue unique_ptr(const unique_ptr&) = delete;  
    unique_ptr& operator=(const unique_ptr&) = delete;  
 };  
 }  

Parameters

Right
A unique_ptr.

Nptr
An rvalue of type std::nullptr_t.

Ptr
A pointer.

Deleter
A deleter function that is bound to a unique_ptr.

Exceptions

No exceptions are generated by unique_ptr.

Remarks

The unique_ptr class supersedes auto_ptr, and can be used as an element of STL containers.

Use the make_unique helper function to efficiently create new instances of unique_ptr.

unique_ptr uniquely manages a resource. Each unique_ptr object stores a pointer to the object that it owns or stores a null pointer. A resource can be owned by no more than one unique_ptr object; when a unique_ptr object that owns a particular resource is destroyed, the resource is freed. A unique_ptr object may be moved, but not copied; for more information, see Rvalue Reference Declarator: &&.

The resource is freed by calling a stored deleter object of type Del that knows how resources are allocated for a particular unique_ptr. The default deleter``default_delete``<T> assumes that the resource pointed to by ptr is allocated with new, and that it can be freed by calling delete _``Ptr. (A partial specialization unique_ptr<T[]>manages array objects allocated with new[], and has the default deleter``default_delete<T[]>, specialized to call delete[] ptr.)

The stored pointer to an owned resource, stored_ptr has type pointer. It is Del::pointer if defined, and T * if not. The stored deleter object stored_deleter occupies no space in the object if the deleter is stateless. Note that Del can be a reference type.

Members

Constructors

Typedefs

Member Functions

Operators

Requirements

Header: <memory>

Namespace: std

deleter_type

The type is a synonym for the template parameter Del.

typedef Del deleter_type;  

Remarks

The type is a synonym for the template parameter Del.

element_type

The type is a synonym for the template parameter Type.

typedef Type element_type;  

Remarks

The type is a synonym for the template parameter Ty.

unique_ptr::get

Returns stored_ptr.

pointer get() const;

Remarks

The member function returns stored_ptr.

unique_ptr::get_deleter

Returns a reference to stored_deleter.

Del& get_deleter();

const Del& get_deleter() const;

Remarks

The member function returns a reference to stored_deleter.

unique_ptr operator=

Assigns the address of the provided unique_ptr to the current one.

unique_ptr& operator=(
    unique_ptr&& right);

template <class U, Class Del2>  
unique_ptr& operator=(
    unique_ptr<Type, Del>&& right);

unique_ptr& operator=(
    pointer-type);

Parameters

A unique_ptr reference used to assign the value of to the current unique_ptr.

Remarks

The member functions call reset(`` right``.release()) and move right``.stored_deleter to stored_deleter, then return *this.

pointer

A synonym for Del::pointer if defined, otherwise Type *.

typedef T1 pointer;  

Remarks

The type is a synonym for Del::pointer if defined, otherwise Type *.

unique_ptr::release

Releases ownership of the returned stored pointer to the caller and sets the stored pointer value to nullptr.

pointer release();

Remarks

Use release to take over ownership of the raw pointer stored by the unique_ptr. The caller is responsible for deletion of the returned pointer. The unique-ptr is set to the empty default-constructed state. You can assign another pointer of compatible type to the unique_ptr after the call to release.

Example

This example shows how the caller of release is responsible for the object returned:

// stl_release_unique.cpp  
// Compile by using: cl /W4 /EHsc stl_release_unique.cpp  
#include <iostream>  
#include <memory>  
  
struct Sample {  
   int content_;  
   Sample(int content) : content_(content) {  
      std::cout << "Constructing Sample(" << content_ << ")" << std::endl;  
   }  
   ~Sample() {  
      std::cout << "Deleting Sample(" << content_ << ")" << std::endl;  
   }  
};  
  
void ReleaseUniquePointer() {  
   // Use make_unique function when possible.    
   auto up1 = std::make_unique<Sample>(3);  
   auto up2 = std::make_unique<Sample>(42);  
  
   // Take over ownership from the unique_ptr up2 by using release  
   auto ptr = up2.release();  
   if (up2) {  
      // This statement does not execute, because up2 is empty.  
      std::cout << "up2 is not empty." << std::endl;  
   }  
   // We are now responsible for deletion of ptr.  
   delete ptr;  
   // up1 deletes its stored pointer when it goes out of scope.     
}  
  
int main() {  
   ReleaseUniquePointer();  
}  

Computer output:

Constructing Sample
(3)  
Constructing Sample
(42)  
Deleting Sample
(42)  
Deleting Sample
(3)  
  

unique_ptr::reset

Takes ownership of the pointer parameter, and then deletes the original stored pointer. If the new pointer is the same as the original stored pointer, reset deletes the pointer and sets the stored pointer to nullptr.

void reset(pointer ptr = pointer());

void reset(nullptr_t ptr);

Parameters

Remarks

Use reset to change the stored pointer owned by the unique_ptr to ptr and then delete the original stored pointer. If the unique_ptr was not empty, reset invokes the deleter function returned by get_deleter on the original stored pointer.

Because reset first stores the new pointer ptr, and then deletes the original stored pointer, it's possible for reset to immediately delete ptr if it is the same as the original stored pointer.

unique_ptr::swap

Exchanges pointers between two unique_ptr objects.

void swap(unique_ptr& right);

Parameters

right
A unique_ptr used to swap pointers.

Remarks

The member function swaps stored_ptr with right.stored_ptr and stored_deleter with right.stored_deleter.

unique_ptr::unique_ptr

There are seven constructors for unique_ptr.

unique_ptr();

unique_ptr(nullptr_t);

explicit unique_ptr(
    pointer ptr);

unique_ptr(
    Type* ptr,  
    typename conditional<
    is_reference<Del>::value, 
    Del, 
    typename add_reference<const Del>::type>::type _Deleter);

unique_ptr(
    pointer ptr,  
    typename remove_reference<Del>::type&& _Deleter);

unique_ptr(
    unique_ptr&& right);

template <class Ty2, Class Del2>  
unique_ptr(
 unique_ptr<Ty2, Del2>&& right);

Parameters

Remarks

The first two constructors construct an object that manages no resource. The third constructor stores ptr in stored_ptr. The fourth constructor stores ptr in stored_ptr and deleter in stored_deleter.

The fifth constructor stores ptr in stored_ptr and moves deleter into stored_deleter. The sixth and seventh constructors store right.reset() in stored_ptr and moves right.get_deleter() into stored_deleter.

unique_ptr ~unique_ptr

The destructor for unique_ptr, destroys a unique_ptr object.

~unique_ptr();

Remarks

The destructor calls get_deleter()(stored_ptr).

See Also

<memory>