CopperSpice API  1.7.2
QWeakPointer< T > Class Template Reference

Holds a weak reference to a shared pointer. More...

Public Typedefs

typedef const value_typeconst_pointer
 
typedef const value_typeconst_reference
 
typedef qptrdiff difference_type
 
typedef T element_type
 
typedef value_typepointer
 
typedef value_typereference
 
typedef T value_type
 

Public Methods

 QWeakPointer ()
 
 QWeakPointer (const QSharedPointer< T > &other)
 
 QWeakPointer (const QWeakPointer< T > &other)
 
template<class X >
 QWeakPointer (const QWeakPointer< X > &other)
 
 ~QWeakPointer ()
 
void clear ()
 
T * data () const
 
bool isNull () const
 
 operator RestrictedBool () const
 
bool operator! () const
 
template<class X >
bool operator!= (const QSharedPointer< X > &other) const
 
template<class X >
bool operator!= (const QWeakPointer< X > &other) const
 
QWeakPointer< T > & operator= (const QSharedPointer< T > &other)
 
QWeakPointer< T > & operator= (const QWeakPointer< T > &other)
 
template<class X >
QWeakPointer< T > & operator= (const QWeakPointer< X > &other)
 
template<class X >
bool operator== (const QSharedPointer< X > &other) const
 
template<class X >
bool operator== (const QWeakPointer< X > &other) const
 
QSharedPointer< T > toStrongRef () const
 

Friends

template<class X >
class QPointer
 
template<class X >
class QSharedPointer
 

Related Functions

These are not member functions

bool operator!= (const QSharedPointer< T > &ptr1, const QWeakPointer< T > &ptr2)
 
bool operator!= (const QWeakPointer< T > &ptr1, const QSharedPointer< X > &ptr2)
 
bool operator== (const QSharedPointer< T > &ptr1, const QWeakPointer< T > &ptr2)
 
bool operator== (const QWeakPointer< T > &ptr1, const QSharedPointer< T > &ptr2)
 
QSharedPointer< X > qSharedPointerCast (const QWeakPointer< T > &other)
 
QSharedPointer< X > qSharedPointerConstCast (const QWeakPointer< T > &other)
 
QSharedPointer< X > qSharedPointerDynamicCast (const QWeakPointer< T > &other)
 
QSharedPointer< X > qSharedPointerObjectCast (const QWeakPointer< T > &other)
 
QWeakPointer< X > qWeakPointerCast (const QWeakPointer< T > &other)
 

Detailed Description

template<class T>
class QWeakPointer< T >

The QWeakPointer class holds a weak reference to a shared pointer. It can not be used to dereference the pointer directly, but it can be used to verify if the pointer has been deleted or not in another context.

QWeakPointer objects can only be created by assignment from a QSharedPointer.

It is important to note that QWeakPointer provides no automatic casting operators to prevent mistakes from happening. Even though QWeakPointer tracks a pointer, it should not be considered a pointer itself, since it does not guarantee that the pointed object remains valid.

Therefore, to access the pointer which QWeakPointer is tracking you must first promote it to QSharedPointer and verify if the resulting object is or is not null. QSharedPointer guarantees the object is not deleted. So if you obtain a non-null object you may use the pointer. Refer to QWeakPointer::toStrongRef() for an example.

QWeakPointer also provides the QWeakPointer::data() method which returns the tracked pointer without ensuring if it remains valid. This function is provided if you can guarantee by external means that the object will not get deleted or if you only need the pointer value. T) and the cost of creating a QSharedPointer using toStrongRef() is too high.

That function can also be used to obtain the tracked pointer for QWeakPointers that can not be promoted to QSharedPointer, such as those created directly from a QObject pointer (not via QSharedPointer).

See also
QSharedPointer, QScopedPointer

Member Typedef Documentation

template<class T >
QWeakPointer< T >::const_pointer

Typedef for const T *.

template<class T >
QWeakPointer< T >::const_reference

Typedef for T &.

template<class T >
QWeakPointer< T >::difference_type

Typedef for integral type used to represent the distance between two elements.

template<class T >
QWeakPointer< T >::element_type

Typedef for T.

template<class T >
QWeakPointer< T >::pointer

Typedef for T *.

template<class T >
QWeakPointer< T >::reference

Typedef for T &.

template<class T >
QWeakPointer< T >::value_type

Typedef for T.

Constructor & Destructor Documentation

template<class T >
QWeakPointer< T >::QWeakPointer ( )
inline

Creates a QWeakPointer that points to nothing.

template<class T >
QWeakPointer< T >::~QWeakPointer ( )
inline

Destroys this QWeakPointer object. The pointer referenced by this object will not be deleted.

template<class T >
QWeakPointer< T >::QWeakPointer ( const QWeakPointer< T > &  other)
inline

Creates a QWeakPointer that holds a weak reference to the pointer referenced by other.

template<class T >
QWeakPointer< T >::QWeakPointer ( const QSharedPointer< T > &  other)
inline

Creates a QWeakPointer that holds a weak reference to the pointer referenced by other.

template<class T >
template<class X >
QWeakPointer< T >::QWeakPointer ( const QWeakPointer< X > &  other)
inline

Creates a QWeakPointer that holds a weak reference to the pointer referenced by other.

If X inherits from the template parameter of this class, QWeakPointer will perform an automatic cast.

Method Documentation

template<class T >
void QWeakPointer< T >::clear ( )
inline

Clears this QWeakPointer object, dropping the reference that it may have had to the pointer.

template<class T >
T * QWeakPointer< T >::data ( ) const
inline

Returns the value of the pointer being tracked by this QWeakPointer, without ensuring that it can not get deleted. To have that guarantee, use toStrongRef(), which returns a QSharedPointer object. If this function can determine that the pointer has already been deleted, it returns 0.

It is ok to obtain the value of the pointer and using that value itself, like for example in debugging statements:

qDebug("Tracking %p", weakref.data());

However, dereferencing the pointer is only allowed if you can guarantee by external means that the pointer does not get deleted. For example, if you can be certain that no other thread can delete it, nor the functions that you may call.

If that is the case, then the following code is valid:

// this pointer must not be used in another thread
QWeakPointer<int> weakref = obtainReference();
Object *obj = weakref.data();
if (obj) {
// if the pointer was not deleted yet, we know it can not be
// deleted by our own code here nor the functions we call
otherFunction(obj);
}
See also
isNull(), toStrongRef()
template<class T >
bool QWeakPointer< T >::isNull ( ) const
inline

Returns true if this object is holding a reference to a null pointer.

De to the nature of weak references, the pointer that QWeakPointer references can become null at any moment, so the value returned from this method can change from false to true from one call to the next.

template<class T >
QWeakPointer< T >::operator RestrictedBool ( ) const
inline

Returns true if this object is not null. This method is suitable for use in if-constructs. Due to the nature of weak references, a QWeakPointer can become null at any moment.

if (weakRef) {
...
}
See also
isNull()
template<class T >
bool QWeakPointer< T >::operator! ( ) const
inline

Returns true if this object is null. This method is suitable for use in if-constructs. Due to the nature of weak references, a QWeakPointer can become null at any moment.

if (! weakref) {
...
}
See also
isNull()
template<class T >
template<class X >
bool QWeakPointer< T >::operator!= ( const QSharedPointer< X > &  other) const
inline

Returns true if other is not equal to this weak pointer, otherwise returns false.

template<class T >
template<class X >
bool QWeakPointer< T >::operator!= ( const QWeakPointer< X > &  other) const
inline

Returns true if other is not equal to this weak pointer, otherwise returns false.

template<class T >
QWeakPointer< T > & QWeakPointer< T >::operator= ( const QSharedPointer< T > &  other)
inline

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

template<class T >
QWeakPointer< T > & QWeakPointer< T >::operator= ( const QWeakPointer< T > &  other)
inline

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

template<class T >
template<class X >
QWeakPointer< T > & QWeakPointer< T >::operator= ( const QWeakPointer< X > &  other)
inline

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

template<class T >
template<class X >
bool QWeakPointer< T >::operator== ( const QSharedPointer< X > &  other) const
inline

Returns true if other is equal to this weak pointer, otherwise returns false.

template<class T >
template<class X >
bool QWeakPointer< T >::operator== ( const QWeakPointer< X > &  other) const
inline

Returns true if other is equal to this weak pointer, otherwise returns false.

template<class T >
QSharedPointer< T > QWeakPointer< T >::toStrongRef ( ) const
inline

Promotes this weak reference to a strong one and returns a QSharedPointer object holding that reference. When promoting to QSharedPointer, this function verifies if the object has been deleted already or not. If it has not, this method increases the reference count to the shared object, thus ensuring that it will not get deleted.

Since this method can fail to obtain a valid strong reference to the shared object, you should always verify if the conversion succeeded, by calling QSharedPointer::isNull() on the returned object.

For example, the following code promotes a QWeakPointer that was held to a strong reference and, if it succeeded, it prints the value of the integer that was held:

// ...
QSharedPointer<int> strong = weakref.toStrongRef();
if (strong) {
qDebug() << "The value is:" << *strong;
} else {
qDebug() << "The value has already been deleted";
}
See also
QSharedPointer::QSharedPointer()

Friends And Related Function Documentation

bool operator!= ( const QSharedPointer< T > &  ptr1,
const QWeakPointer< T > &  ptr2 
)
related

Returns true if ptr1 and ptr2 do not point to the same object.

bool operator!= ( const QWeakPointer< T > &  ptr1,
const QSharedPointer< X > &  ptr2 
)
related

Returns true if ptr1 and ptr2 do not point to the same object

bool operator== ( const QSharedPointer< T > &  ptr1,
const QWeakPointer< T > &  ptr2 
)
related

Returns true if ptr1 and ptr2 point to the same object.

bool operator== ( const QWeakPointer< T > &  ptr1,
const QSharedPointer< T > &  ptr2 
)
related

Returns true if ptr1 and ptr2 point to the same object.

QSharedPointer< X > qSharedPointerCast ( const QWeakPointer< T > &  other)
related

Returns a shared pointer to the pointer held by other, cast to type X. The types T and X must belong to one hierarchy for the static_cast to succeed.

The other object is converted first to a strong reference. If that conversion fails (because the object it's pointing to has already been deleted), this function returns a null QSharedPointer.

Note that X must have the same cv-qualifiers (const and volatile) that T has, or the code will fail to compile. Use qSharedPointerConstCast to cast away the constness.

See also
QWeakPointer::toStrongRef(), qSharedPointerDynamicCast(), qSharedPointerConstCast()
QSharedPointer< X > qSharedPointerConstCast ( const QWeakPointer< T > &  other)
related

Returns a shared pointer to the pointer held by other, cast to type X. The types T and X must belong to one hierarchy for the const_cast to succeed. The const and volatile differences between T and X are ignored.

The other object is converted first to a strong reference. If that conversion fails (because the object it's pointing to has already been deleted), this function returns a null QSharedPointer.

See also
QWeakPointer::toStrongRef(), qSharedPointerCast(), qSharedPointerDynamicCast()
QSharedPointer< X > qSharedPointerDynamicCast ( const QWeakPointer< T > &  other)
related

Returns a shared pointer to the pointer held by other, using a dynamic cast to type X to obtain an internal pointer of the appropriate type. If the dynamic_cast fails, the object returned will be null.

The other object is converted first to a strong reference. If that conversion fails (because the object it's pointing to has already been deleted), this function also returns a null QSharedPointer.

Note that X must have the same cv-qualifiers (const and volatile) that T has, or the code will fail to compile. Use qSharedPointerConstCast to cast away the constness.

See also
QWeakPointer::toStrongRef(), qSharedPointerCast(), qSharedPointerConstCast()
QSharedPointer< X > qSharedPointerObjectCast ( const QWeakPointer< T > &  other)
related

Returns a shared pointer to the pointer held by other, using a qobject_cast() to type X to obtain an internal pointer of the appropriate type. If the qobject_cast fails, the object returned will be null.

The other object is converted first to a strong reference. If that conversion fails (because the object it is pointing to has already been deleted), this method returns a null QSharedPointer. Note that X must have the same cv-qualifiers (const and volatile) that T has, or the code will fail to compile. Use qSharedPointerConstCast to cast away the constness.

See also
QWeakPointer::toStrongRef(), qSharedPointerCast(), qSharedPointerConstCast()
QWeakPointer< X > qWeakPointerCast ( const QWeakPointer< T > &  other)
related

Returns a weak pointer to the pointer held by other, cast to type X. The types T and X must belong to one hierarchy for the static_cast to succeed.

Note that X must have the same cv-qualifiers (const and volatile) that T has, or the code will fail to compile. Use qSharedPointerConstCast to cast away the constness.