19 General utilities library [utilities]

19.11 Smart pointers [smartptr]

19.11.1 Class template unique_­ptr [unique.ptr]

19.11.1.2 unique_­ptr for single objects [unique.ptr.single]

namespace std {
  template<class T, class D = default_delete<T>> class unique_ptr {
  public:
    using pointer      = see below;
    using element_type = T;
    using deleter_type = D;

    // [unique.ptr.single.ctor], constructors
    constexpr unique_ptr() noexcept;
    explicit unique_ptr(pointer p) noexcept;
    unique_ptr(pointer p, see below d1) noexcept;
    unique_ptr(pointer p, see below d2) noexcept;
    unique_ptr(unique_ptr&& u) noexcept;
    constexpr unique_ptr(nullptr_t) noexcept;
    template<class U, class E>
      unique_ptr(unique_ptr<U, E>&& u) noexcept;

    // [unique.ptr.single.dtor], destructor
    ~unique_ptr();

    // [unique.ptr.single.asgn], assignment
    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;

    // [unique.ptr.single.observers], observers
    add_lvalue_reference_t<T> operator*() const;
    pointer operator->() const noexcept;
    pointer get() const noexcept;
    deleter_type& get_deleter() noexcept;
    const deleter_type& get_deleter() const noexcept;
    explicit operator bool() const noexcept;

    // [unique.ptr.single.modifiers], modifiers
    pointer release() noexcept;
    void reset(pointer p = pointer()) noexcept;
    void swap(unique_ptr& u) noexcept;

    // disable copy from lvalue
    unique_ptr(const unique_ptr&) = delete;
    unique_ptr& operator=(const unique_ptr&) = delete;
  };
}
1
#
The default type for the template parameter D is default_­delete.
A client-supplied template argument D shall be a function object type, lvalue reference to function, or lvalue reference to function object type for which, given a value d of type D and a value ptr of type unique_­ptr<T, D>​::​pointer, the expression d(ptr) is valid and has the effect of disposing of the pointer as appropriate for that deleter.
2
#
If the deleter's type D is not a reference type, D shall satisfy the Cpp17Destructible requirements (Table 29).
3
#
If the qualified-id remove_­reference_­t<D>​::​pointer is valid and denotes a type ([temp.deduct]), then unique_­ptr<T, D>​::​pointer shall be a synonym for remove_­reference_­t<D>​::​pointer.
Otherwise unique_­ptr<T, D>​::​pointer shall be a synonym for element_­type*.
The type unique_­ptr<T, D>​::​pointer shall satisfy the Cpp17NullablePointer requirements (Table 30).
4
#
[ Example
:
Given an allocator type X (Table 33) and letting A be a synonym for allocator_­traits<X>, the types A​::​pointer, A​::​const_­pointer, A​::​void_­pointer, and A​::​const_­void_­pointer may be used as unique_­ptr<T, D>​::​pointer.
— end example
 ]

19.11.1.2.1 Constructors [unique.ptr.single.ctor]

🔗
constexpr unique_ptr() noexcept; constexpr unique_ptr(nullptr_t) noexcept;
1
#
Requires: D shall satisfy the Cpp17DefaultConstructible requirements (Table 24), and that construction shall not throw an exception.
2
#
Effects: Constructs a unique_­ptr object that owns nothing, value-initializing the stored pointer and the stored deleter.
3
#
Ensures: get() == nullptr.
get_­deleter() returns a reference to the stored deleter.
4
#
Remarks: If is_­pointer_­v<deleter_­type> is true or is_­default_­constructible_­v<deleter_­type> is false, this constructor shall not participate in overload resolution.
🔗
explicit unique_ptr(pointer p) noexcept;
5
#
Requires: D shall satisfy the Cpp17DefaultConstructible requirements (Table 24), and that construction shall not throw an exception.
6
#
Effects: Constructs a unique_­ptr which owns p, initializing the stored pointer with p and value-initializing the stored deleter.
7
#
Ensures: get() == p.
get_­deleter() returns a reference to the stored deleter.
8
#
Remarks: If is_­pointer_­v<deleter_­type> is true or is_­default_­constructible_­v<deleter_­type> is false, this constructor shall not participate in overload resolution.
If class template argument deduction ([over.match.class.deduct]) would select the function template corresponding to this constructor, then the program is ill-formed.
🔗
unique_ptr(pointer p, see below d1) noexcept; unique_ptr(pointer p, see below d2) noexcept;
9
#
The signature of these constructors depends upon whether D is a reference type.
If D is a non-reference type A, then the signatures are:
unique_ptr(pointer p, const A& d) noexcept;
unique_ptr(pointer p, A&& d) noexcept;
10
#
If D is an lvalue reference type A&, then the signatures are:
unique_ptr(pointer p, A& d) noexcept;
unique_ptr(pointer p, A&& d) = delete;
11
#
If D is an lvalue reference type const A&, then the signatures are:
unique_ptr(pointer p, const A& d) noexcept;
unique_ptr(pointer p, const A&& d) = delete;
12
#
Requires: For the first constructor, if D is not a reference type, D shall satisfy the Cpp17CopyConstructible requirements and such construction shall not exit via an exception.
For the second constructor, if D is not a reference type, D shall satisfy the Cpp17MoveConstructible requirements and such construction shall not exit via an exception.
13
#
Effects: Constructs a unique_­ptr object which owns p, initializing the stored pointer with p and initializing the deleter from std​::​forward<decltype(d)>(d).
14
#
Remarks: These constructors shall not participate in overload resolution unless is_­constructible_­v<D, decltype(d)> is true.
15
#
Ensures: get() == p.
get_­deleter() returns a reference to the stored deleter.
If D is a reference type then get_­deleter() returns a reference to the lvalue d.
16
#
Remarks: If class template argument deduction ([over.match.class.deduct]) would select a function template corresponding to either of these constructors, then the program is ill-formed.
17
#
[ Example
: 
D d;
unique_ptr<int, D> p1(new int, D());        // D must be Cpp17MoveConstructible
unique_ptr<int, D> p2(new int, d);          // D must be Cpp17CopyConstructible
unique_ptr<int, D&> p3(new int, d);         // p3 holds a reference to d
unique_ptr<int, const D&> p4(new int, D()); // error: rvalue deleter object combined
                                            // with reference deleter type
— end example
 ]
🔗
unique_ptr(unique_ptr&& u) noexcept;
18
#
Requires: If D is not a reference type, D shall satisfy the Cpp17MoveConstructible requirements (Table 25).
Construction of the deleter from an rvalue of type D shall not throw an exception.
19
#
Effects: Constructs a unique_­ptr from u.
If D is a reference type, this deleter is copy constructed from u's deleter; otherwise, this deleter is move constructed from u's deleter.
[ Note
:
The construction of the deleter can be implemented with std​::​forward<D>.
— end note
 ]
20
#
Ensures: get() yields the value u.get() yielded before the construction.
u.get() == nullptr.
get_­deleter() returns a reference to the stored deleter that was constructed from u.get_­deleter().
If D is a reference type then get_­deleter() and u.get_­deleter() both reference the same lvalue deleter.
🔗
template<class U, class E> unique_ptr(unique_ptr<U, E>&& u) noexcept;
21
#
Requires: If E is not a reference type, construction of the deleter from an rvalue of type E shall be well-formed and shall not throw an exception.
Otherwise, E is a reference type and construction of the deleter from an lvalue of type E shall be well-formed and shall not throw an exception.
22
#
Remarks: This constructor shall not participate in overload resolution unless:
  • (22.1)
    unique_­ptr<U, E>​::​pointer is implicitly convertible to pointer,
  • (22.2)
    U is not an array type, and
  • (22.3)
    either D is a reference type and E is the same type as D, or D is not a reference type and E is implicitly convertible to D.
23
#
Effects: Constructs a unique_­ptr from u.
If E is a reference type, this deleter is copy constructed from u's deleter; otherwise, this deleter is move constructed from u's deleter.
[ Note
:
The deleter constructor can be implemented with std​::​forward<E>.
— end note
 ]
24
#
Ensures: get() yields the value u.get() yielded before the construction.
u.get() == nullptr.
get_­deleter() returns a reference to the stored deleter that was constructed from u.get_­deleter().

19.11.1.2.2 Destructor [unique.ptr.single.dtor]

🔗
~unique_ptr();
1
#
Requires: The expression get_­deleter()(get()) shall be well-formed, shall have well-defined behavior, and shall not throw exceptions.
[ Note
:
The use of default_­delete requires T to be a complete type.
— end note
 ]
2
#
Effects: If get() == nullptr there are no effects.
Otherwise get_­deleter()(get()).

19.11.1.2.3 Assignment [unique.ptr.single.asgn]

🔗
unique_ptr& operator=(unique_ptr&& u) noexcept;
1
#
Requires: If D is not a reference type, D shall satisfy the Cpp17MoveAssignable requirements (Table 27) and assignment of the deleter from an rvalue of type D shall not throw an exception.
Otherwise, D is a reference type; remove_­reference_­t<D> shall satisfy the Cpp17CopyAssignable requirements and assignment of the deleter from an lvalue of type D shall not throw an exception.
2
#
Effects: Calls reset(u.release()) followed by get_­deleter() = std​::​forward<D>(u.get_­deleter()).
3
#
Returns: *this.
4
#
Ensures: u.get() == nullptr.
🔗
template<class U, class E> unique_ptr& operator=(unique_ptr<U, E>&& u) noexcept;
5
#
Requires: If E is not a reference type, assignment of the deleter from an rvalue of type E shall be well-formed and shall not throw an exception.
Otherwise, E is a reference type and assignment of the deleter from an lvalue of type E shall be well-formed and shall not throw an exception.
6
#
Remarks: This operator shall not participate in overload resolution unless:
  • (6.1)
    unique_­ptr<U, E>​::​pointer is implicitly convertible to pointer, and
  • (6.2)
    U is not an array type, and
  • (6.3)
    is_­assignable_­v<D&, E&&> is true.
7
#
Effects: Calls reset(u.release()) followed by get_­deleter() = std​::​forward<E>(u.get_­deleter()).
8
#
Returns: *this.
9
#
Ensures: u.get() == nullptr.
🔗
unique_ptr& operator=(nullptr_t) noexcept;
10
#
Effects: As if by reset().
11
#
Ensures: get() == nullptr.
12
#
Returns: *this.

19.11.1.2.4 Observers [unique.ptr.single.observers]

🔗
add_lvalue_reference_t<T> operator*() const;
1
#
Requires: get() != nullptr.
2
#
Returns: *get().
🔗
pointer operator->() const noexcept;
3
#
Requires: get() != nullptr.
4
#
Returns: get().
5
#
[ Note
:
The use of this function typically requires that T be a complete type.
— end note
 ]
🔗
pointer get() const noexcept;
6
#
Returns: The stored pointer.
🔗
deleter_type& get_deleter() noexcept; const deleter_type& get_deleter() const noexcept;
7
#
Returns: A reference to the stored deleter.
🔗
explicit operator bool() const noexcept;
8
#
Returns: get() != nullptr.

19.11.1.2.5 Modifiers [unique.ptr.single.modifiers]

🔗
pointer release() noexcept;
1
#
Ensures: get() == nullptr.
2
#
Returns: The value get() had at the start of the call to release.
🔗
void reset(pointer p = pointer()) noexcept;
3
#
Requires: The expression get_­deleter()(get()) shall be well-formed, shall have well-defined behavior, and shall not throw exceptions.
4
#
Effects: Assigns p to the stored pointer, and then if and only if the old value of the stored pointer, old_­p, was not equal to nullptr, calls get_­deleter()(old_­p).
[ Note
:
The order of these operations is significant because the call to get_­deleter() may destroy *this.
— end note
 ]
5
#
Ensures: get() == p.
[ Note
:
The postcondition does not hold if the call to get_­deleter() destroys *this since this->get() is no longer a valid expression.
— end note
 ]
🔗
void swap(unique_ptr& u) noexcept;
6
#
Requires: get_­deleter() shall be swappable and shall not throw an exception under swap.
7
#
Effects: Invokes swap on the stored pointers and on the stored deleters of *this and u.