QSharedPointer Class

Member Function Documentation

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

This function was introduced in Qt 6.7.

See also owner_equal.

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

This function was introduced in Qt 6.7.

See also owner_before and owner_hash.

[noexcept, since 6.7] size_t QSharedPointer::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.

This function was introduced in Qt 6.7.

See also owner_equal.

QSharedPointer::QSharedPointer()

Creates a QSharedPointer that is null (the object is holding a reference to nullptr).

[noexcept] template <typename X> QSharedPointer::QSharedPointer(QSharedPointer<X> &&other)

Move-constructs a QSharedPointer instance, making it point at the same object that other was pointing to.

This constructor participates in overload resolution only if X* implicitly converts to T*.

[explicit] template <typename X> QSharedPointer::QSharedPointer(X *ptr)

Creates a QSharedPointer that points to ptr. The pointer ptr becomes managed by this QSharedPointer and must not be passed to another QSharedPointer object or deleted outside this object.

Since Qt 5.8, when the last reference to this QSharedPointer gets destroyed, ptr will be deleted by calling X's destructor (even if X is not the same as QSharedPointer's template parameter T). Previously, the destructor for T was called.

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

Creates a QSharedPointer by promoting the weak reference other to strong reference and sharing its pointer.

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

See also QWeakPointer::toStrongRef().

QSharedPointer::QSharedPointer(std::nullptr_t)

Creates a QSharedPointer that is null. This is equivalent to the QSharedPointer default constructor.

template <typename X, typename Deleter> QSharedPointer::QSharedPointer(X *ptr, Deleter d)

Creates a QSharedPointer that points to ptr. The pointer ptr becomes managed by this QSharedPointer and must not be passed to another QSharedPointer object or deleted outside this object.

The deleter parameter d specifies the custom deleter for this object. The custom deleter is called, instead of the operator delete(), when the strong reference count drops to 0. This is useful, for instance, for calling deleteLater() on a QObject instead:

    static void doDeleteLater(MyObject *obj)
    {
        obj->deleteLater();
    }

    void otherFunction()
    {
        QSharedPointer<MyObject> obj =
            QSharedPointer<MyObject>(new MyObject, doDeleteLater);

        // continue using obj
        obj.clear();    // calls obj->deleteLater();
    }

Note that the custom deleter function will be called with a pointer to type X, even if the QSharedPointer template parameter T is not the same.

It is also possible to specify a member function directly, as in:

    QSharedPointer<MyObject> obj =
        QSharedPointer<MyObject>(new MyObject, &QObject::deleteLater);

See also clear().

template <typename Deleter> QSharedPointer::QSharedPointer(std::nullptr_t, Deleter d)

Creates a QSharedPointer that is null. This is equivalent to the QSharedPointer default constructor.

The deleter parameter d specifies the custom deleter for this object. The custom deleter is called, instead of the operator delete(), when the strong reference count drops to 0.

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

Creates a QSharedPointer object that shares other's pointer.

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

[noexcept] QSharedPointer::QSharedPointer(QSharedPointer<T> &&other)

Move-constructs a QSharedPointer instance, making it point at the same object that other was pointing to.

QSharedPointer::~QSharedPointer()

Destroys this QSharedPointer object. If it is the last reference to the pointer stored, this will delete the pointer as well.

void QSharedPointer::clear()

Clears this QSharedPointer object, dropping the reference that it may have had to the pointer. If this was the last reference, then the pointer itself will be deleted.

template <typename X> QSharedPointer<X> QSharedPointer::constCast() const

Performs a const_cast from this pointer's type to X and returns a QSharedPointer that shares the reference. This function can be used for up- and for down-casting, but is more useful for up-casting.

See also isNull() and qSharedPointerConstCast().

[static] template <typename... Args> QSharedPointer<T> QSharedPointer::create(Args &&... args)

This is an overloaded function.

Creates a QSharedPointer object and allocates a new item of type T. The QSharedPointer internals and the object are allocated in one single memory allocation, which could help reduce memory fragmentation in a long-running application.

This function will attempt to call a constructor for type T that can accept all the arguments passed (args). Arguments will be perfectly-forwarded.

T *QSharedPointer::data() const

Returns the value of the pointer referenced by this object.

Note: do not delete the pointer returned by this function or pass it to another function that could delete it, including creating QSharedPointer or QWeakPointer objects.

template <typename X> QSharedPointer<X> QSharedPointer::dynamicCast() const

Performs a dynamic cast from this pointer's type to X and returns a QSharedPointer that shares the reference. If this function is used to up-cast, then QSharedPointer will perform a dynamic_cast, which means that if the object being pointed by this QSharedPointer is not of type X, the returned object will be null.

Note: the template type X must have the same const and volatile qualifiers as the template of this object, or the cast will fail. Use constCast() if you need to drop those qualifiers.

See also qSharedPointerDynamicCast().

T *QSharedPointer::get() const

Same as data().

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

bool QSharedPointer::isNull() const

Returns true if this object refers to nullptr.

template <typename X> QSharedPointer<X> QSharedPointer::objectCast() const

Performs a qobject_cast() from this pointer's type to X and returns a QSharedPointer that shares the reference. If this function is used to up-cast, then QSharedPointer will perform a qobject_cast, which means that if the object being pointed by this QSharedPointer is not of type X, the returned object will be null.

Note: the template type X must have the same const and volatile qualifiers as the template of this object, or the cast will fail. Use constCast() if you need to drop those qualifiers.

See also qSharedPointerObjectCast().

void QSharedPointer::reset()

Same as clear(). For std::shared_ptr compatibility.

void QSharedPointer::reset(T *t)

Resets this QSharedPointer object to point to t instead. Equivalent to:

    QSharedPointer<T> other(t); this->swap(other);

template <typename Deleter> void QSharedPointer::reset(T *t, Deleter deleter)

Resets this QSharedPointer object to point to t instead, with the Deleter deleter. Equivalent to:

    QSharedPointer<T> other(t, deleter); this->swap(other);

template <typename X> QSharedPointer<X> QSharedPointer::staticCast() const

Performs a static cast from this pointer's type to X and returns a QSharedPointer that shares the reference. This function can be used for up- and for down-casting, but is more useful for up-casting.

Note: the template type X must have the same const and volatile qualifiers as the template of this object, or the cast will fail. Use constCast() if you need to drop those qualifiers.

See also dynamicCast(), constCast(), and qSharedPointerCast().

[noexcept] void QSharedPointer::swap(QSharedPointer<T> &other)

Swaps this shared pointer instance with other. This function is very fast and never fails.

QWeakPointer<T> QSharedPointer::toWeakRef() const

Returns a weak reference object that shares the pointer referenced by this object.

See also QWeakPointer::QWeakPointer().

bool QSharedPointer::operator bool() const

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

    if (sharedptr) { ... }

See also isNull().

bool QSharedPointer::operator!() const

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

    if (!sharedptr) { ... }

See also isNull().

T &QSharedPointer::operator*() const

Provides access to the shared pointer's members.

If the contained pointer is nullptr, behavior is undefined.

See also isNull().

T *QSharedPointer::operator->() const

Provides access to the shared pointer's members.

If the contained pointer is nullptr, behavior is undefined.

See also isNull().

[noexcept] QSharedPointer<T> &QSharedPointer::operator=(QSharedPointer<T> &&other)

Move-assigns other to this QSharedPointer instance.

[noexcept] template <typename X> QSharedPointer<T> &QSharedPointer::operator=(QSharedPointer<X> &&other)

Move-assigns other to this QSharedPointer instance.

This assignment operator participates in overload resolution only if X* implicitly converts to T*.

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

Makes this object share other's pointer. The current pointer reference is discarded and, if it was the last, the pointer will be deleted.

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

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

Promotes other to a strong reference and makes this object share a reference to the pointer referenced by it. The current pointer reference is discarded and, if it was the last, the pointer will be deleted.

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