Long live qUtf16Printable()

QString::asprintf() has the ability to take a ushort* array as
obtained from QString::utf16() and insert that into the output
with an %ls conversion.

But no-one ever used this, because just passing QString::utf16()
to QString::asprintf() creates a warning about wchar_t* expected,
but ushort* provided.

The new qUtf16Printable() macro adds the necessary casts (via void*
to prevent any "type-punned pointer" warnings) to make
passing QString::utf16() to QString::asprintf() work silently.

This should greatly reduce the need to do a round-trip via utf-8
just to print the contents of a QString.

[ChangeLog][QtCore] Added qUtf16Printable().

Change-Id: I7ddd8d2b2a2191c9faa26aca95d49850d94b287c
Reviewed-by: Olivier Goffart (Woboq GmbH) <ogoffart@woboq.com>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

3 files changed, 37 insertions, 0 deletions

diff --git a/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp b/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp
index 6ff4f57945..ccf8399e0d 100644
--- a/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp
+++ b/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp
@@ -439,6 +439,11 @@ qWarning("%s: %s", qUtf8Printable(key), qUtf8Printable(value));
 //! [37]
 
 
+//! [qUtf16Printable]
+qWarning("%ls: %ls", qUtf16Printable(key), qUtf16Printable(value));
+//! [qUtf16Printable]
+
+
 //! [38]
 struct Point2D
 {
diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp
index c1ab2d69fa..9182529e08 100644
--- a/src/corelib/global/qglobal.cpp
+++ b/src/corelib/global/qglobal.cpp
@@ -3825,6 +3825,29 @@ int qrand()
 */
 
 /*!
+    \macro const wchar_t *qUtf16Printable(const QString &str)
+    \relates <QtGlobal>
+    \since 5.7
+
+    Returns \a str as a \c{const ushort *}, but cast to a \c{const wchar_t *}
+    to avoid warnings. This is equivalent to \a{str}.utf16() plus some casting.
+
+    The only useful thing you can do with the return value of this macro is to
+    pass it to QString::asprintf() for use in a \c{%ls} conversion. In particular,
+    the return value is \e{not} a valid \c{const wchar_t*}!
+
+    In general, the pointer will be invalid after the statement in which
+    qUtf16Printable() is used. This is because the pointer may have been
+    obtained from a temporary expression, which will fall out of scope.
+
+    Example:
+
+    \snippet code/src_corelib_global_qglobal.cpp qUtf16Printable
+
+    \sa qPrintable(), qDebug(), qInfo(), qWarning(), qCritical(), qFatal()
+*/
+
+/*!
     \macro Q_DECLARE_TYPEINFO(Type, Flags)
     \relates <QtGlobal>
 
diff --git a/src/corelib/global/qglobal.h b/src/corelib/global/qglobal.h
index 64d9f79faf..9b8029990c 100644
--- a/src/corelib/global/qglobal.h
+++ b/src/corelib/global/qglobal.h
@@ -687,6 +687,15 @@ Q_CORE_EXPORT bool qSharedBuild() Q_DECL_NOTHROW;
 #  define qUtf8Printable(string) QString(string).toUtf8().constData()
 #endif
 
+/*
+    Wrap QString::utf16() with enough casts to allow passing it
+    to QString::asprintf("%ls") without warnings.
+*/
+#ifndef qUtf16Printable
+#  define qUtf16Printable(string) \
+    static_cast<const wchar_t*>(static_cast<const void*>(QString(string).utf16()))
+#endif
+
 class QString;
 Q_CORE_EXPORT QString qt_error_string(int errorCode = -1);