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>

2 files changed, 12 insertions, 0 deletions

diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qdebug.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qdebug.cpp
index 14e72e99dd..5154dc5d68 100644
--- a/src/corelib/doc/snippets/code/src_corelib_io_qdebug.cpp
+++ b/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]
diff --git a/src/corelib/doc/src/includes/qdebug-toString.qdocinc b/src/corelib/doc/src/includes/qdebug-toString.qdocinc
new file mode 100644
index 0000000000..4602a10511
--- /dev/null
+++ b/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