QWeakPointer Class | Qt Core | Qt 6.11.0
Description: The QWeakPointer class holds a weak reference to a shared pointer.

- Qt 6.11
- Qt Core
- C++ Classes
- QWeakPointer
- Qt 6.11.0 Reference Documentation

# QWeakPointer Class

template <typename T> class QWeakPointer

The QWeakPointer class holds a weak reference to a shared pointer. More...

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

- List of all members, including inherited members

Note: All functions in this class are reentrant.

## Public Functions

| QWeakPointer()
| QWeakPointer(const QSharedPointer<T> &other)
| QWeakPointer(const QWeakPointer<T> &other)
| ~QWeakPointer()
void | clear()
bool | isNull() const
QSharedPointer<T> | lock() const
`(since 6.7)` bool | owner_before(const QSharedPointer<X> &other) const
`(since 6.7)` bool | owner_before(const QWeakPointer<X> &other) const
`(since 6.7)` bool | owner_equal(const QSharedPointer<X> &other) const
`(since 6.7)` bool | owner_equal(const QWeakPointer<X> &other) const
`(since 6.7)` size_t | owner_hash() const
void | swap(QWeakPointer<T> &other)
QSharedPointer<T> | toStrongRef() const
| operator bool() const
bool | operator!() const
QWeakPointer<T> & | operator=(const QSharedPointer<T> &other)
QWeakPointer<T> & | operator=(const QWeakPointer<T> &other)

## Related Non-Members

QWeakPointer<X> | qWeakPointerCast(const QWeakPointer<T> &src)
bool | operator!=(const QSharedPointer<T> &ptr1, const QWeakPointer<X> &ptr2)
bool | operator!=(const QWeakPointer<T> &ptr1, const QSharedPointer<X> &ptr2)
bool | operator!=(const QWeakPointer<T> &lhs, int)
bool | operator!=(int, const QWeakPointer<T> &rhs)
bool | operator==(const QSharedPointer<T> &ptr1, const QWeakPointer<X> &ptr2)
bool | operator==(const QWeakPointer<T> &ptr1, const QSharedPointer<X> &ptr2)
bool | operator==(const QWeakPointer<T> &lhs, int)
bool | operator==(int, const QWeakPointer<T> &rhs)

## Detailed Description

The QWeakPointer is an automatic weak reference to a pointer in C++. It cannot 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's 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 doesn't guarantee that the pointed object remains valid.

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

See also QSharedPointer and QScopedPointer.

## Member Function Documentation

### QWeakPointer::QWeakPointer()

Creates a QWeakPointer that points to nothing.

### QWeakPointer::QWeakPointer(const QSharedPointer<T> &other)

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

If `T` is a derived type of the template parameter of this class, QWeakPointer will perform an automatic cast. Otherwise, you will get a compiler error.

### `[noexcept]` QWeakPointer::QWeakPointer(const QWeakPointer<T> &other)

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

If `T` is a derived type of the template parameter of this class, QWeakPointer will perform an automatic cast. Otherwise, you will get a compiler error.

### QWeakPointer::~QWeakPointer()

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

### void QWeakPointer::clear()

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

### bool QWeakPointer::isNull() const

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

Note that, due to the nature of weak references, the pointer that QWeakPointer references can become `nullptr` at any moment, so the value returned from this function can change from false to true from one call to the next.

### QSharedPointer<T> QWeakPointer::lock() const

Same as toStrongRef().

This function is provided for API compatibility with std::weak_ptr.

### `[noexcept, since 6.7]` template <typename X> bool QWeakPointer::owner_before(const QSharedPointer<X> &other) const

### `[noexcept, since 6.7]` template <typename X> bool QWeakPointer::owner_before(const QWeakPointer<X> &other) const

Returns `true` if and only if this smart pointer precedes other in an implementation-defined owner-based ordering. The ordering is such that two smart pointers are considered equivalent if they are both empty or if they both own the same object (even if their apparent type and pointer are different).

These functions were introduced in Qt 6.7.

See also owner_equal.

### `[noexcept, since 6.7]` template <typename X> bool QWeakPointer::owner_equal(const QSharedPointer<X> &other) const

### `[noexcept, since 6.7]` template <typename X> bool QWeakPointer::owner_equal(const QWeakPointer<X> &other) const

Returns `true` if and only if this smart pointer and other share ownership.

These functions were introduced in Qt 6.7.

See also owner_before and owner_hash.

### `[noexcept, since 6.7]` size_t QWeakPointer::owner_hash() const

Returns a owner-based hash value for this smart pointer object. Smart pointers that compare equal (as per `owner_equal`) will have an identical owner-based hash.

These function were introduced in Qt 6.7.

See also owner_equal.

### `[noexcept]` void QWeakPointer::swap(QWeakPointer<T> &other)

Swaps this weak pointer instance with other. This operation is very fast and never fails.

### QSharedPointer<T> QWeakPointer::toStrongRef() const

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 hasn't, this function increases the reference count to the shared object, thus ensuring that it will not get deleted.

Since this function 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:

     QWeakPointer<int> weakref;

     // ...

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

See also QSharedPointer::QSharedPointer().

### QWeakPointer::operator bool() const

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

     if (weakref) { /*...*/ }

Note that, due to the nature of weak references, the pointer that QWeakPointer references can become `nullptr` at any moment, so the value returned from this function can change from true to false from one call to the next.

See also isNull().

### bool QWeakPointer::operator!() const

Returns `true` if this object refers to `nullptr`. This function is suitable for use in `if-constructs`, like:

     if (!weakref) { /*...*/ }

Note that, due to the nature of weak references, the pointer that QWeakPointer references can become `nullptr` at any moment, so the value returned from this function can change from false to true from one call to the next.

See also isNull().

### QWeakPointer<T> &QWeakPointer::operator=(const QSharedPointer<T> &other)

Makes this object share other's pointer. The current pointer reference is discarded but is not deleted.

If `T` is a derived type of the template parameter of this class, QWeakPointer will perform an automatic cast. Otherwise, you will get a compiler error.

### `[noexcept]` QWeakPointer<T> &QWeakPointer::operator=(const QWeakPointer<T> &other)

Makes this object share other's pointer. The current pointer reference is discarded but is not deleted.

If `T` is a derived type of the template parameter of this class, QWeakPointer will perform an automatic cast. Otherwise, you will get a compiler error.

## Related Non-Members

### template <typename X, typename T> QWeakPointer<X> qWeakPointerCast(const QWeakPointer<T> &src)

Returns a weak pointer to the pointer held by src, 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.

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

Returns `true` if ptr1 and ptr2 refer to distinct pointers.

If ptr2's template parameter is different from ptr1's, QSharedPointer will attempt to perform an automatic `static_cast` to ensure that the pointers being compared are equal. If ptr2's template parameter is not a base or a derived type from ptr1's, you will get a compiler error.

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

Returns `true` if ptr1 and ptr2 refer to distinct pointers.

If ptr2's template parameter is different from ptr1's, QSharedPointer will attempt to perform an automatic `static_cast` to ensure that the pointers being compared are equal. If ptr2's template parameter is not a base or a derived type from ptr1's, you will get a compiler error.

### template <typename T> bool operator!=(const QWeakPointer<T> &lhs, int)

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

See also QWeakPointer::isNull().

### template <typename T> bool operator!=(int, const QWeakPointer<T> &rhs)

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

See also QWeakPointer::isNull().

### template <typename T, typename X> bool operator==(const QSharedPointer<T> &ptr1, const QWeakPointer<X> &ptr2)

Returns `true` if ptr1 and ptr2 refer to the same pointer.

If ptr2's template parameter is different from ptr1's, QSharedPointer will attempt to perform an automatic `static_cast` to ensure that the pointers being compared are equal. If ptr2's template parameter is not a base or a derived type from ptr1's, you will get a compiler error.

### template <typename T, typename X> bool operator==(const QWeakPointer<T> &ptr1, const QSharedPointer<X> &ptr2)

Returns `true` if ptr1 and ptr2 refer to the same pointer.

If ptr2's template parameter is different from ptr1's, QSharedPointer will attempt to perform an automatic `static_cast` to ensure that the pointers being compared are equal. If ptr2's template parameter is not a base or a derived type from ptr1's, you will get a compiler error.

### template <typename T> bool operator==(const QWeakPointer<T> &lhs, int)

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

See also QWeakPointer::isNull().

### template <typename T> bool operator==(int, const QWeakPointer<T> &rhs)

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

See also QWeakPointer::isNull().