QSP/QWP: introduce owner_before, owner_equal, owner_hash

While at the moment we don't have aliasing support in QSharedPointer,
introduce owner-based comparisons and hashing. This also fulfills some
use cases in lieu of operator== for QWeakPointer (which got deprecated
by bb23a05905d7dc0e416a646e40592436daa939f2).

I'm using C++26/P1901's spelling of owner_equal, instead of
Boost.SmartPtr's spelling (owner_equal*s*). Given the niche use case,
the lack of interoperability with Qt's own containers, as well as the
Standard comparison objects' semantics (std::owner_less,
std::owner_equal), I don't think we should be giving these a Qt-ish name
as it would be pretty useless.

[ChangeLog][QtCore][QSharedPointer] Added owner_before, owner_equal,
owner_hash.
[ChangeLog][QtCore][QWeakPointer] Added owner_before, owner_equal,
owner_hash.

Done-with: Fabian Kosmale <fabian.kosmale@qt.io>
Change-Id: I8b792ae79f14cd518ba4a006edaa17786a8352a0
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>

3 files changed, 103 insertions, 0 deletions

diff --git a/src/corelib/tools/qsharedpointer.cpp b/src/corelib/tools/qsharedpointer.cpp
index 7ed3847182..6daf1e3fad 100644
--- a/src/corelib/tools/qsharedpointer.cpp
+++ b/src/corelib/tools/qsharedpointer.cpp
@@ -711,6 +711,49 @@
 */
 
 /*!
+    \fn template <class T> template <class X> bool QSharedPointer<T>::owner_before(const QSharedPointer<X> &other) const noexcept
+    \fn template <class T> template <class X> bool QSharedPointer<T>::owner_before(const QWeakPointer<X> &other) const noexcept
+    \fn template <class T> template <class X> bool QWeakPointer<T>::owner_before(const QSharedPointer<X> &other) const noexcept
+    \fn template <class T> template <class X> bool QWeakPointer<T>::owner_before(const QWeakPointer<X> &other) const noexcept
+    \since 6.7
+
+    Returns \c true if and only if this smart pointer precedes \a 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).
+
+    \sa owner_equal
+*/
+
+/*!
+    \fn template <class T> template <class X> bool QSharedPointer<T>::owner_equal(const QSharedPointer<X> &other) const noexcept
+    \fn template <class T> template <class X> bool QSharedPointer<T>::owner_equal(const QWeakPointer<X> &other) const noexcept
+    \fn template <class T> template <class X> bool QWeakPointer<T>::owner_equal(const QSharedPointer<X> &other) const noexcept
+    \fn template <class T> template <class X> bool QWeakPointer<T>::owner_equal(const QWeakPointer<X> &other) const noexcept
+
+    \since 6.7
+
+    Returns \c true if and only if this smart pointer and \a other
+    share ownership.
+
+    \sa owner_before, owner_hash
+*/
+
+/*!
+    \fn template <class T> size_t QSharedPointer<T>::owner_hash() const noexcept
+    \fn template <class T> size_t QWeakPointer<T>::owner_hash() const noexcept
+
+    \since 6.7
+
+    Returns a owner-based hash value for this smart pointer object.
+    Smart pointers that compare equal (as per \c{owner_equal}) will
+    have an identical owner-based hash.
+
+    \sa owner_equal
+*/
+
+/*!
     \fn template <class T> QWeakPointer<T>::QWeakPointer()
 
     Creates a QWeakPointer that points to nothing.
diff --git a/src/corelib/tools/qsharedpointer.h b/src/corelib/tools/qsharedpointer.h
index 2a60f3ca5e..116c9afa00 100644
--- a/src/corelib/tools/qsharedpointer.h
+++ b/src/corelib/tools/qsharedpointer.h
@@ -72,6 +72,19 @@ public:
 
     template <typename... Args>
     static inline QSharedPointer<T> create(Args &&... args);
+
+    // owner-based comparisons
+    template <typename X>
+    bool owner_before(const QSharedPointer<X> &other) const noexcept;
+    template <typename X>
+    bool owner_before(const QWeakPointer<X> &other) const noexcept;
+
+    template <typename X>
+    bool owner_equal(const QSharedPointer<X> &other) const noexcept;
+    template <typename X>
+    bool owner_equal(const QWeakPointer<X> &other) const noexcept;
+
+    size_t owner_hash() const noexcept;
 };
 
 template <class T>
@@ -108,6 +121,19 @@ public:
 
     QSharedPointer<T> toStrongRef() const;
     QSharedPointer<T> lock() const;
+
+    // owner-based comparisons
+    template <typename X>
+    bool owner_before(const QWeakPointer<X> &other) const noexcept;
+    template <typename X>
+    bool owner_before(const QSharedPointer<X> &other) const noexcept;
+
+    template <typename X>
+    bool owner_equal(const QWeakPointer<X> &other) const noexcept;
+    template <typename X>
+    bool owner_equal(const QSharedPointer<X> &other) const noexcept;
+
+    size_t owner_hash() const noexcept;
 };
 
 template <class T>
diff --git a/src/corelib/tools/qsharedpointer_impl.h b/src/corelib/tools/qsharedpointer_impl.h
index 5dfc4614f9..73e39f0b91 100644
--- a/src/corelib/tools/qsharedpointer_impl.h
+++ b/src/corelib/tools/qsharedpointer_impl.h
@@ -444,6 +444,23 @@ public:
 #undef DECLARE_TEMPLATE_COMPARE_SET
 #undef DECLARE_COMPARE_SET
 
+    template <typename X>
+    bool owner_before(const QSharedPointer<X> &other) const noexcept
+    { return std::less<>()(d, other.d); }
+    template <typename X>
+    bool owner_before(const QWeakPointer<X> &other) const noexcept
+    { return std::less<>()(d, other.d); }
+
+    template <typename X>
+    bool owner_equal(const QSharedPointer<X> &other) const noexcept
+    { return d == other.d; }
+    template <typename X>
+    bool owner_equal(const QWeakPointer<X> &other) const noexcept
+    { return d == other.d; }
+
+    size_t owner_hash() const noexcept
+    { return std::hash<Data *>()(d); }
+
 private:
     Q_NODISCARD_CTOR
     explicit QSharedPointer(Qt::Initialization) {}
@@ -684,6 +701,23 @@ public:
     friend bool operator!=(std::nullptr_t, const QWeakPointer &p)
     { return !p.isNull(); }
 
+    template <typename X>
+    bool owner_before(const QWeakPointer<X> &other) const noexcept
+    { return std::less<>()(d, other.d); }
+    template <typename X>
+    bool owner_before(const QSharedPointer<X> &other) const noexcept
+    { return std::less<>()(d, other.d); }
+
+    template <typename X>
+    bool owner_equal(const QWeakPointer<X> &other) const noexcept
+    { return d == other.d; }
+    template <typename X>
+    bool owner_equal(const QSharedPointer<X> &other) const noexcept
+    { return d == other.d; }
+
+    size_t owner_hash() const noexcept
+    { return std::hash<Data *>()(d); }
+
 private:
     friend struct QtPrivate::EnableInternalData;
     template <class X> friend class QSharedPointer;