std::unique_ptr
Defined in header <memory>
.
Declarations
template<
class T,
class Deleter = std::default_delete<T>
> class unique_ptr;
template <
class T,
class Deleter
> class unique_ptr<T[], Deleter>;
Description
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=
orreset()
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
:
- Manages a single object (e.g. allocated with
new
); - Manages a dynamically-allocated array of objects (e.g. allocated with
new[]
).
The class satisfies the requirements of MoveConstructible and MoveAssignable, but of neither CopyConstructible nor 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
.
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
; or another fancy pointer.
Feature-test macro | Value | Std | Comment |
---|---|---|---|
__cpp_lib_constexpr_memory | 202202L | (C++23) | constexpr std::unique_ptr |
Member types
pub | pointer | std::remove_reference<Deleter>::type::pointer if that type exists, otherwise T*. Must satisfy NullablePointer |
pub | element_type | T, the type of the object managed by this unique_ptr |
pub | deleter_type | Deleter, the function object or lvalue reference to function or to function object, to be called from the destructor |
Member functions
pub | (constructors) | constructs a new unique_ptr (function template) |
pub | (destructor) | destructs the managed object if such is present (function template) |
pub | operator= | assigns the unique_ptr (function template) |
Modifiers
pub | release | returns a pointer to the managed object and releases the ownership (function template) |
pub | reset | replaces the managed object (function template) |
pub | swap | swaps the managed objects (function template) |
Observers
pub | get | returns a pointer to the managed object (function template) |
pub | get_deleter | returns the deleter that is used for destruction of the managed object (function template) |
pub | operator bool | checks if there is an associated managed object (function template) |
Single-object version, unique_ptr<T>
pub | operator* operator-> | dereferences pointer to the managed object (function template) |
Array version, unique_ptr<T[]>
pub | operator[] | provides indexed access to the managed array (function template) |