CopperSpice API  1.7.2
QScopedPointer< T, Cleanup > Class Template Reference

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

Inheritance diagram for QScopedPointer< T, Cleanup >:
QScopedArrayPointer< T, Cleanup >

Public Methods

 QScopedPointer (QScopedPointer< T, Cleanup > &&other)
 
 QScopedPointer (T *p=nullptr)
 
 ~QScopedPointer ()
 
T * data () const
 
bool isNull () const
 
 operator RestrictedBool () const
 
bool operator! () const
 
T & operator* () const
 
T * operator-> () const
 
QScopedPointer< T, Cleanup > & operator= (QScopedPointer< T, Cleanup > &&other)
 
void reset (T *other=nullptr)
 
void swap (QScopedPointer< T, Cleanup > &other)
 
T * take ()
 

Detailed Description

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

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

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 the object pointed to will be deleted when the current scope disappears.

Consider this function which does heap allocations, and have 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;
}

With QScopedPointer the code can be simplified to the following.

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:
QWidget *const p = new QWidget();
// is equivalent to:
const QWidget *p = new QWidget();
// is equivalent to:

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

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:
// 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:

Forward Declared Pointers

Classes which are forward declared can be used within QScopedPointer. However, the destructor of the forward declared class must be available when a QScopedPointer is constructor. This means all classes containing a QScopedPointer which point 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 will not implicitly generate them
};
See also
QSharedPointer

Constructor & Destructor Documentation

template<typename T , typename Cleanup = QScopedPointerDeleter<T>>
QScopedPointer< T, Cleanup >::QScopedPointer ( T *  p = nullptr)
inlineexplicit

Constructs this QScopedPointer instance and sets its pointer to p.

template<typename T , typename Cleanup = QScopedPointerDeleter<T>>
QScopedPointer< T, Cleanup >::~QScopedPointer ( )
inline

Destroys this QScopedPointer object.

template<typename T , typename Cleanup = QScopedPointerDeleter<T>>
QScopedPointer< T, Cleanup >::QScopedPointer ( QScopedPointer< T, Cleanup > &&  other)
inline

Move constructs a new QScopedPointer from other.

Method Documentation

template<typename T , typename Cleanup = QScopedPointerDeleter<T>>
T * QScopedPointer< T, Cleanup >::data ( ) const
inline

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

template<typename T , typename Cleanup = QScopedPointerDeleter<T>>
bool QScopedPointer< T, Cleanup >::isNull ( ) const
inline

Returns true if this object is holding a pointer that is null.

template<typename T , typename Cleanup = QScopedPointerDeleter<T>>
QScopedPointer< T, Cleanup >::operator RestrictedBool ( ) const
inline

Returns true if this object is not null. This function is suitable for use in if-constructs.

if (scopedPointer) {
...
}
See also
isNull()
template<typename T , typename Cleanup = QScopedPointerDeleter<T>>
bool QScopedPointer< T, Cleanup >::operator! ( ) const
inline

Returns true if the pointer referenced by this object is null, otherwise returns false.

See also
isNull()
template<typename T , typename Cleanup = QScopedPointerDeleter<T>>
T & QScopedPointer< T, Cleanup >::operator* ( ) const
inline

Provides access to the scoped pointer's object. If the contained pointer is null, behavior is undefined.

See also
isNull()
template<typename T , typename Cleanup = QScopedPointerDeleter<T>>
T * QScopedPointer< T, Cleanup >::operator-> ( ) const
inline

Provides access to the scoped pointer's object. If the contained pointer is null, behavior is undefined.

See also
isNull()
template<typename T , typename Cleanup = QScopedPointerDeleter<T>>
QScopedPointer< T, Cleanup > & QScopedPointer< T, Cleanup >::operator= ( QScopedPointer< T, Cleanup > &&  other)
inline

Copy assigns from other and returns a reference to this object.

template<typename T , typename Cleanup = QScopedPointerDeleter<T>>
void QScopedPointer< T, Cleanup >::reset ( T *  other = nullptr)
inline

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 the destructor.

template<typename T , typename Cleanup = QScopedPointerDeleter<T>>
void QScopedPointer< T, Cleanup >::swap ( QScopedPointer< T, Cleanup > &  other)
inline

Swap this pointer with other.

template<typename T , typename Cleanup = QScopedPointerDeleter<T>>
T * QScopedPointer< T, Cleanup >::take ( )
inline

Returns the value of the pointer referenced by this object. The pointer of this QScopedPointer object will be reset to null.

Callers of this function take ownership of the pointer.