Contains a pointer to an object and takes exclusive ownership. More...

Inheritance diagram for QScopedPointer< T, Deleter >:

Public Typedefs
using	deleter_type = typename std::unique_ptr< T, Deleter >::deleter_type

using	DeleterType = deleter_type

using	element_type = typename std::unique_ptr< T, Deleter >::element_type

using	ElementType = element_type

using	pointer = typename std::unique_ptr< T, Deleter >::pointer

using	Pointer = pointer

Public Methods
	QScopedPointer (Pointer p, Deleter d) noexcept

	QScopedPointer (Pointer p=nullptr) noexcept

	QScopedPointer (QScopedPointer< T, Deleter > &&other)

	QScopedPointer (std::unique_ptr< T, Deleter > &&p) noexcept

	~QScopedPointer ()

Pointer	data () const noexcept

Pointer	get () const noexcept

const Deleter &	get_deleter () const noexcept

Deleter &	get_deleter () noexcept

bool	isNull () const noexcept

	operator bool () const noexcept

bool	operator! () const noexcept

ElementType &	operator* () const noexcept

Pointer	operator-> () const noexcept

QScopedPointer &	operator= (QScopedPointer< T, Deleter > &&other)

Pointer	release () noexcept

void	reset (Pointer other=nullptr)

void	swap (QScopedPointer< T, Deleter > &other) noexcept

Pointer	take () noexcept

Related Functions
These are not member functions
bool	operator!= (const QScopedPointer< T, Deleter > &ptr1, std::nullptr_t)

bool	operator!= (const QScopedPointer< T1, Deleter1 > &ptr1, const QScopedPointer< T2, Deleter2 > &ptr2)

bool	operator!= (const QScopedPointer< T1, Deleter1 > &ptr1, const T2 *ptr2)

bool	operator!= (const T1 *ptr1, const QScopedPointer< T2, Deleter2 > &ptr2)

bool	operator!= (std::nullptr_t, const QScopedPointer< T, Deleter > &ptr2)

bool	operator< (const QScopedPointer< T1 > &ptr1, const QScopedPointer< T2 > ptr2)

bool	operator<= (const QScopedPointer< T1 > &ptr1, const QScopedPointer< T2 > ptr2)

bool	operator== (const QScopedPointer< T, Deleter > &ptr1, std::nullptr_t)

bool	operator== (const QScopedPointer< T1, Deleter1 > &ptr1, const QScopedPointer< T2, Deleter2 > &ptr2)

bool	operator== (const QScopedPointer< T1, Deleter1 > &ptr1, const T2 *ptr2)

bool	operator== (const T1 *ptr1, const QScopedPointer< T2, Deleter2 > &ptr2)

bool	operator== (std::nullptr_t, const QScopedPointer< T, Deleter > &ptr2)

bool	operator> (const QScopedPointer< T1 > &ptr1, const QScopedPointer< T2 > ptr2)

bool	operator>= (const QScopedPointer< T1 > &ptr1, const QScopedPointer< T2 > ptr2)

QScopedPointer< T >	QMakeScoped (Args &&...args)

QScopedPointer< T >	QMakeUnique (Args &&...args)

Detailed Description

template<typename T, typename Deleter = std::default_delete<T>>
class QScopedPointer< T, Deleter >

The QScopedPointer class contains a pointer to an object and takes exclusive ownership of the lifetime of the object.

There is no reference count for a QScopedPointer since no other smart pointers can point to the given object. Any pointer class which takes responsibility for the lifetime of the object it points to is considered a smart pointer.

When this smart pointer class is destroyed the object it points to will be deleted. This ensures the object is always destroyed when the pointer goes out of scope.

Example Using a Raw Pointer

The following is an example which shows why using a raw pointer can be complicated. Notice the code to delete both raw pointers must be duplicated in three different places.

void myFunction(bool useSubClass)
{
   MyClass *somePtr  = useSubClass ? new MyClass() : new MySubClass;
   QIODevice *device = handsOverOwnership();
 
   if (m_value > 3) {
      delete somePtr;
      delete device;
 
      return;
   }
 
   try {
      process(device);
 
   } catch (...) {
      delete somePtr;
      delete device;
      throw;
   }
 
   delete somePtr;
   delete device;
}

Example Using QScopedPointer

When a smart pointer is used instead of a raw pointer the source code can be simplified.

void myFunction(bool useSubClass)
{
   QScopedPointer<MyClass> somePtr(useSubClass ? new MyClass() : new MySubClass);
   QScopedPointer<QIODevice> device(handsOverOwnership());
 
   if (m_value > 3) }
      return;
   }
 
   process(device);
}

Destroying Objects

The purpose of a destructor is to clean up the resources owned by the object. Destroying a smart pointer object needs to do a bit more work. It is also responsible for releaseing the dynamic memory allocated to the object the smart pointer was pointing to. Most dynamically allocated objects are destroyed by simply calling the delete operator as shown below.

Widget *ptr = new Widget();
 
// do something
 
delete ptr;

When using a smart pointer which owns the object it is pointing to, users do not call delete directly. The destructor method is responsible for calling a method in a Deleter class which will release the memory allocated to the object. The exact call in the Deleter class must correspond to the way the object was created.

Allocation	Deleter Class	Destruction
new T()	std::default_delete<T>	Default Deleter class, calls operator delete()
new T[ ]	std::default_delete<T[ ]>	Default Deleter class, calls operator delete[ ]
malloc()	QMallocDeleter	Custom Deleter, calls free()

Custom Deleter Classes

QScopedPointer has a default Deleter class which is sufficient for most objects. If your application requires a custom Deleter class the name of this struct or class must be passed as the second template parameter to QScopedPointer.

// uses default object deleter
QScopedPointer<QWidget> ptr_A(new QWidget);
 
// uses default array deleter
QScopedPointer<int[]> ptr_B(new int[42]);
 
// uses a CopperSpice custom Deleter class
QScopedPointer<int, QMallocDeleter> ptr1(reinterpret_cast<int *>(malloc(42)));
 
 
// uses a custom deleter class supplied in your application
struct MyCustomDeleter
{
   void operator()(MyClass *ptr) const {
      myDeleteFunction(ptr);
   }
};
 
QScopedPointer<MyClass, MyCustomDeleter> ptr_D(new MyClass);

Custom Deleters

The syntax for using a custom deleter with QScoperedPointer has been modified. This change applies to any build of CopperSpice using the source code from SHA b5769a6 or later.

// original code
QScopedPointer<int, QScopedPointerPodDeleter> ptr1(reinterpret_cast<int *>(malloc(42)));
 
struct MyCustomDeleter
{
   static inline void cleanup(MyClass *ptr) {
      myDeleteFunction(ptr);
   }
};
 
// using a custom deleter
QScopedPointer<MyClass, MyCustomDeleter> ptr2(new MyClass);
 
 
// new syntax
QScopedPointer<int, QMallocDeleter> ptr3(reinterpret_cast<int *>(malloc(42)));
 
struct MyCustomDeleter
{
   void operator()(MyClass *ptr) const {
      myDeleteFunction(ptr);
   }
};
 
// using a custom deleter
QScopedPointer<MyClass, MyCustomDeleter> ptr4(new MyClass);

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 constructed. All classes containing a QScopedPointer which point to a forward declared class must have non-inline constructors, destructors, and assignment operators.

class MyPrivateClass;                               // forward declaration
 
class MyClass
{
   public:
      MyClass();
      inline ~MyClass() {}                          // will *not* compile, destructor can not be inline
 
      MyClass(const MyClass &) = delete;
      MyClass & operator=(const MyClass &) = delete;
 
   private:
      QScopedPointer<MyPrivateClass> privatePtr;
 };

See also: QSharedPointer