Add QDebug::toString()

This template function streams the given object into a QDebug instance
that operates on a string, and then returns that string.

This function is useful for cases where you need the textual
representation of an object for debugging, but cannot use operator<<.
A good example of this is when writing tests where you want to provide
a useful failure message involving details about an object, but must
provide it in a string to e.g. QVERIFY2.

[ChangeLog][QtCore][QDebug] Added static template toString() function,
which streams the given object into a QDebug instance that operates on
a string, and then returns that string.

Fixes: QTBUG-82309
Change-Id: I8411394e899dedad19cec788d779a4515d52ba11
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>

src/corelib/doc/snippets/code/src_corelib_io_qdebug.cpp

@@ -93,3 +93,8 @@
     ba = QByteArray("a\0b", 3);
     qDebug() << ba               // prints: "\a\x00""b"
 //! [1]
+
+//! [toString]
+    QTRY_VERIFY2(list.isEmpty(), qPrintable(QString::fromLatin1(
+        "Expected list to be empty, but it has the following items: %1")).arg(QDebug::toString(list)));
+//! [toString]

src/corelib/doc/src/includes/qdebug-toString.qdocinc

@@ -0,0 +1,7 @@
+Streams \a object into a QDebug instance that operates on a string,
+and then returns that string.
+
+This function is useful for cases where you need the textual representation
+of an object for debugging, but cannot use \c {operator<<}. For example:
+
+\snippet code/src_corelib_io_qdebug.cpp toString

src/corelib/io/qdebug.cpp

@@ -713,6 +713,20 @@ QDebug &QDebug::resetFormat()
     \internal
 */
 
+/*!
+    \fn template <class T> QString QDebug::toString(const T &object)
+    \since 6.0
+
+    \include qdebug-toString.qdocinc
+*/
+
+/*!
+    \fn template <class T> QString QDebug::toString(const T *object)
+    \since 6.0
+
+    \include qdebug-toString.qdocinc
+*/
+
 /*!
     \fn template <class T> QDebug operator<<(QDebug debug, const QList<T> &list)
     \relates QDebug

src/corelib/io/qdebug.h

@@ -173,6 +173,24 @@ public:
 
     inline QDebug &operator<<(QTextStreamManipulator m)
     { stream->ts << m; return *this; }
+
+    template <typename T>
+    static QString toString(const T &object)
+    {
+        QString buffer;
+        QDebug stream(&buffer);
+        stream << object;
+        return buffer;
+    }
+
+    template <typename T>
+    static QString toString(const T *object)
+    {
+        QString buffer;
+        QDebug stream(&buffer);
+        stream << object;
+        return buffer;
+    }
 };
 
 Q_DECLARE_SHARED(QDebug)

tests/auto/corelib/io/qdebug/tst_qdebug.cpp

@@ -66,6 +66,7 @@ private slots:
     void resetFormat() const;
     void defaultMessagehandler() const;
     void threadSafety() const;
+    void toString() const;
 };
 
 void tst_QDebug::assignment() const
@@ -740,6 +741,28 @@ void tst_QDebug::threadSafety() const
     }
 }
 
+void tst_QDebug::toString() const
+{
+    // By reference.
+    {
+        MyPoint point(3, 4);
+        QString expectedString;
+        QDebug stream(&expectedString);
+        stream << point;
+        QCOMPARE(QDebug::toString(point), expectedString);
+    }
+
+    // By pointer.
+    {
+        QObject qobject;
+        qobject.setObjectName("test");
+        QString expectedString;
+        QDebug stream(&expectedString);
+        stream << &qobject;
+        QCOMPARE(QDebug::toString(&qobject), expectedString);
+    }
+}
+
 // Should compile: instentiation of unrelated operator<< should not cause cause compilation
 // error in QDebug operators (QTBUG-47375)
 class TestClassA {};