QScopedPointer Class | Qt Core 6.8.3
Description: The QScopedPointer class stores a pointer to a dynamically allocated object, and deletes it upon destruction.

- Qt 6.8
- Qt Core
- C++ Classes
- QScopedPointer
- Qt 6.8.3 Reference Documentation

# QScopedPointer Class

template <typename T, typename Cleanup = QScopedPointerDeleter<T>> class QScopedPointer

The QScopedPointer class stores a pointer to a dynamically allocated object, and deletes it upon destruction. More...

Header: | `#include <QScopedPointer>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Core)` `target_link_libraries(mytarget PRIVATE Qt6::Core)`
qmake: | `QT += core`
Inherited By: | QScopedArrayPointer

- List of all members, including inherited members
- Deprecated members

Note: All functions in this class are reentrant.

## Public Functions

| QScopedPointer(T *p = nullptr)
| ~QScopedPointer()
T * | data() const
T * | get() const
bool | isNull() const
void | reset(T *other = nullptr)
bool | operator bool() const
bool | operator!() const
T & | operator*() const
T * | operator->() const

## Related Non-Members

bool | operator!=(const QScopedPointer<T, Cleanup> &lhs, const QScopedPointer<T, Cleanup> &rhs)
bool | operator!=(const QScopedPointer<T, Cleanup> &lhs, int)
bool | operator!=(int, const QScopedPointer<T, Cleanup> &rhs)
bool | operator==(const QScopedPointer<T, Cleanup> &lhs, const QScopedPointer<T, Cleanup> &rhs)
bool | operator==(const QScopedPointer<T, Cleanup> &lhs, int)
bool | operator==(int, const QScopedPointer<T, Cleanup> &rhs)

## Detailed Description

Managing heap allocated objects manually is hard and error prone, with the common result that code leaks memory and is hard to maintain. QScopedPointer is a small utility class that heavily simplifies this by assigning stack-based memory ownership to heap allocations, more generally called resource acquisition is initialization(RAII).

QScopedPointer guarantees that the object pointed to will get deleted when the current scope disappears.

Consider this function which does heap allocations, and has various exit points:

     void myFunction(bool useSubClass)
     {
         MyClass *p = useSubClass ? new MyClass() : new MySubClass;
         QIODevice *device = handsOverOwnership();

         if (m_value > 3) {
             delete p;
             delete device;
             return;
         }

         try {
             process(device);
         }
         catch (...) {
             delete p;
             delete device;
             throw;
         }

         delete p;
         delete device;
     }

It's encumbered by the manual delete calls. With QScopedPointer, the code can be simplified to:

     void myFunction(bool useSubClass)
     {
         // assuming that MyClass has a virtual destructor
         QScopedPointer<MyClass> p(useSubClass ? new MyClass() : new MySubClass);
         QScopedPointer<QIODevice> device(handsOverOwnership());

         if (m_value > 3)
             return;

         process(device);
     }

The code the compiler generates for QScopedPointer is the same as when writing it manually. Code that makes use of delete are candidates for QScopedPointer usage (and if not, possibly another type of smart pointer such as QSharedPointer). QScopedPointer intentionally has no copy constructor or assignment operator, such that ownership and lifetime is clearly communicated.

The const qualification on a regular C++ pointer can also be expressed with a QScopedPointer:

         const QWidget *const p = new QWidget();
         // is equivalent to:
         const QScopedPointer<const QWidget> p(new QWidget());

         QWidget *const p = new QWidget();
         // is equivalent to:
         const QScopedPointer<QWidget> p(new QWidget());

         const QWidget *p = new QWidget();
         // is equivalent to:
         QScopedPointer<const QWidget> p(new QWidget());

### Custom Cleanup Handlers

Arrays as well as pointers that have been allocated with `malloc` must not be deleted using `delete`. QScopedPointer's second template parameter can be used for custom cleanup handlers.

The following custom cleanup handlers exist:

- QScopedPointerDeleter - the default, deletes the pointer using `delete`
- QScopedPointerArrayDeleter - deletes the pointer using `delete []`. Use this handler for pointers that were allocated with `new []`.
- QScopedPointerPodDeleter - deletes the pointer using `free()`. Use this handler for pointers that were allocated with `malloc()`.
- QScopedPointerDeleteLater - deletes a pointer by calling `deleteLater()` on it. Use this handler for pointers to QObject's that are actively participating in a QEventLoop.

You can pass your own classes as handlers, provided that they have a public static function `void cleanup(T *pointer)`.

     // this QScopedPointer deletes its data using the delete[] operator:
     QScopedPointer<int, QScopedPointerArrayDeleter<int> > arrayPointer(new int[42]);

     // this QScopedPointer frees its data using free():
     QScopedPointer<int, QScopedPointerPodDeleter> podPointer(reinterpret_cast<int *>(malloc(42)));

     // this struct calls "myCustomDeallocator" to delete the pointer
     struct ScopedPointerCustomDeleter
     {
         static inline void cleanup(MyCustomClass *pointer)
         {
             myCustomDeallocator(pointer);
         }
     };

     // QScopedPointer using a custom deleter:
     QScopedPointer<MyCustomClass, ScopedPointerCustomDeleter> customPointer(new MyCustomClass);

### Forward Declared Pointers

Classes that are forward declared can be used within QScopedPointer, as long as the destructor of the forward declared class is available whenever a QScopedPointer needs to clean up.

Concretely, this means that all classes containing a QScopedPointer that points to a forward declared class must have non-inline constructors, destructors and assignment operators:

     class MyPrivateClass; // forward declare MyPrivateClass

     class MyClass
     {
     private:
         QScopedPointer<MyPrivateClass> privatePtr; // QScopedPointer to forward declared class

     public:
         MyClass(); // OK
         inline ~MyClass() {} // VIOLATION - Destructor must not be inline

     private:
         Q_DISABLE_COPY(MyClass) // OK - copy constructor and assignment operators
                                  // are now disabled, so the compiler won't implicitly
                                  // generate them.
     };

Otherwise, the compiler outputs a warning about not being able to destruct `MyPrivateClass`.

See also QSharedPointer.

## Member Function Documentation

### `[explicit noexcept]` QScopedPointer::QScopedPointer(T *p = nullptr)

Constructs this QScopedPointer instance and sets its pointer to p.

### QScopedPointer::~QScopedPointer()

Destroys this QScopedPointer object. Delete the object its pointer points to.

### `[noexcept]` T *QScopedPointer::data() const

Returns the value of the pointer referenced by this object. QScopedPointer still owns the object pointed to.

### `[noexcept]` T *QScopedPointer::get() const

Same as data().

### `[noexcept]` bool QScopedPointer::isNull() const

Returns `true` if this object refers to `nullptr`.

### `[noexcept(...)]` void QScopedPointer::reset(T *other = nullptr)

Deletes the existing object it is pointing to (if any), and sets its pointer to other. QScopedPointer now owns other and will delete it in its destructor.

Note: This function is noexcept when `noexcept(Cleanup::cleanup(std::declval<T *>()))` is `true`.

### `[explicit]` bool QScopedPointer::operator bool() const

Returns `true` if the contained pointer is not `nullptr`. This function is suitable for use in `if-constructs`, like:

     if (scopedPointer) {
         ...
     }

See also isNull().

### `[noexcept]` bool QScopedPointer::operator!() const

Returns `true` if this object refers to `nullptr`.

See also isNull().

### T &QScopedPointer::operator*() const

Provides access to the scoped pointer's object.

If the contained pointer is `nullptr`, behavior is undefined.

See also isNull().

### `[noexcept]` T *QScopedPointer::operator->() const

Provides access to the scoped pointer's object.

If the contained pointer is `nullptr`, behavior is undefined.

See also isNull().

## Related Non-Members

### `[noexcept]` bool operator!=(const QScopedPointer<T, Cleanup> &lhs, const QScopedPointer<T, Cleanup> &rhs)

Returns `true` if lhs and rhs refer to distinct pointers.

### `[noexcept]` bool operator!=(const QScopedPointer<T, Cleanup> &lhs, int)

Returns `true` if lhs refers to a valid (i.e. non-null) pointer.

See also QScopedPointer::isNull().

### `[noexcept]` bool operator!=(int, const QScopedPointer<T, Cleanup> &rhs)

Returns `true` if rhs refers to a valid (i.e. non-null) pointer.

See also QScopedPointer::isNull().

### `[noexcept]` bool operator==(const QScopedPointer<T, Cleanup> &lhs, const QScopedPointer<T, Cleanup> &rhs)

Returns `true` if lhs and rhs refer to the same pointer.

### `[noexcept]` bool operator==(const QScopedPointer<T, Cleanup> &lhs, int)

Returns `true` if lhs refers to `nullptr`.

See also QScopedPointer::isNull().

### `[noexcept]` bool operator==(int, const QScopedPointer<T, Cleanup> &rhs)

Returns `true` if rhs refers to `nullptr`.

See also QScopedPointer::isNull().