Long live PRI*Qdatatypes

Qt defines some integral datatypes (qsizetype, qintptr, quintptr,
qptrdiff) not in terms of the corresponding language datatypes (resp.
make_signed_t<size_t>, intptr_t, uintptr_t, ptrdiff_t) but as "integer
types with the same bit size of the corresponding language type" (and of
course the corret correct signedness for the target type).

This makes the Qt datatypes not printable via printf-like formatted
output, incl. qDebug, qWarning, QString::asprintf and so on; that's
because there isn't a format modifier that would universally work
with the Qt definitions.

For instance, on a 32 bit platform, ptrdiff_t may be a typedef for long,
while qptrdiff is a typedef for _int_ instead. Both long and int would
indeed be 32 bits, but they still are different types, and this means
that the ptrdiff_t-specific 't' length modifier would be wrong for
qptrdiff:

  qptrdiff p;
  printf("%td", p); // WARNING: -Wformat: wanted long, got int

Similarly, not using 't' breaks on 64 bits, and so on and so forth.
There isn't a way out, short of inserting casts on every print
statement.

So, let's adopt the same solution C/C++ use for their own integer
typedefs: the PRIx macros. This allows one to always use the correct
formatting specifier without the need of a cast.

I'm not adding the macros for the qintXX datatypes, as they already
exist in the Standard Library.

[ChangeLog][QtCore][QtGlobal] A series of PRIxQTDATATYPE macros have
been added. They make it possible to print some Qt type aliases
(qsizetype, qintptr, etc.) via a formatted output facility such as
printf() or qDebug() without raising formatting warnings and without
the need of a type cast.

Change-Id: I473226a661868aed9514d793c8e6e4d391ab5055
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@qt.io>

1 files changed, 83 insertions, 0 deletions

diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp
index 2d5e647739..a0a8d8c395 100644
--- a/src/corelib/global/qglobal.cpp
+++ b/src/corelib/global/qglobal.cpp
@@ -826,10 +826,29 @@ static_assert(sizeof(qint64) == 8, "Internal error, qint64 is misdefined");
 
     Note that qintptr is signed. Use quintptr for unsigned values.
 
+    In order to print values of this type by using formatted-output
+    facilities such as \c{printf()}, qDebug(), QString::asprintf() and
+    so on, you can use the \c{PRIdQINTPTR} and \c{PRIiQINTPTR}
+    macros as format specifiers. They will both print the value as a
+    base 10 number.
+
+    \code
+    qintptr p = 123;
+    printf("The pointer is %" PRIdQINTPTR "\n", p);
+    \endcode
+
     \sa qptrdiff, qint32, qint64
 */
 
 /*!
+    \macro PRIdQINTPTR
+    \macro PRIiQINTPTR
+    \since 6.2
+
+    See qintptr.
+*/
+
+/*!
     \typedef quintptr
     \relates <QtGlobal>
 
@@ -844,10 +863,36 @@ static_assert(sizeof(qint64) == 8, "Internal error, qint64 is misdefined");
 
     Note that quintptr is unsigned. Use qptrdiff for signed values.
 
+    In order to print values of this type by using formatted-output
+    facilities such as \c{printf()}, qDebug(), QString::asprintf() and
+    so on, you can use the following macros as format specifiers:
+
+    \list
+    \li \c{PRIuQUINTPTR}: prints the value as a base 10 number.
+    \li \c{PRIoQUINTPTR}: prints the value as a base 8 number.
+    \li \c{PRIxQUINTPTR}: prints the value as a base 16 number, using lowercase \c{a-f} letters.
+    \li \c{PRIXQUINTPTR}: prints the value as a base 16 number, using uppercase \c{A-F} letters.
+    \endlist
+
+    \code
+    quintptr p = 123u;
+    printf("The pointer value is 0x%" PRUXQUINTPTR "\n", p);
+    \endcode
+
     \sa qptrdiff, quint32, quint64
 */
 
 /*!
+    \macro PRUoQUINTPTR
+    \macro PRIuQUINTPTR
+    \macro PRIxQUINTPTR
+    \macro PRIXQUINTPTR
+    \since 6.2
+
+    See quintptr.
+*/
+
+/*!
     \typedef qptrdiff
     \relates <QtGlobal>
 
@@ -860,10 +905,29 @@ static_assert(sizeof(qint64) == 8, "Internal error, qint64 is misdefined");
 
     Note that qptrdiff is signed. Use quintptr for unsigned values.
 
+    In order to print values of this type by using formatted-output
+    facilities such as \c{printf()}, qDebug(), QString::asprintf() and
+    so on, you can use the \c{PRIdQPTRDIFF} and \c{PRIiQPTRDIFF}
+    macros as format specifiers. They will both print the value as a
+    base 10 number.
+
+    \code
+    qptrdiff d = 123;
+    printf("The difference is %" PRIdQPTRDIFF "\n", d);
+    \endcode
+
     \sa quintptr, qint32, qint64
 */
 
 /*!
+    \macro PRIdQPTRDIFF
+    \macro PRIiQPTRDIFF
+    \since 6.2
+
+    See qptrdiff.
+*/
+
+/*!
     \typedef qsizetype
     \relates <QtGlobal>
     \since 5.10
@@ -875,10 +939,29 @@ static_assert(sizeof(qint64) == 8, "Internal error, qint64 is misdefined");
 
     Note that qsizetype is signed. Use \c size_t for unsigned values.
 
+    In order to print values of this type by using formatted-output
+    facilities such as \c{printf()}, qDebug(), QString::asprintf() and
+    so on, you can use the \c{PRIdQSIZETYPE} and \c{PRIiQSIZETYPE}
+    macros as format specifiers. They will both print the value as a
+    base 10 number.
+
+    \code
+    qsizetype s = 123;
+    printf("The size is %" PRIdQSIZETYPE "\n", s);
+    \endcode
+
     \sa qptrdiff
 */
 
 /*!
+    \macro PRIdQSIZETYPE
+    \macro PRIiQSIZETYPE
+    \since 6.2
+
+    See qsizetype.
+*/
+
+/*!
     \enum QtMsgType
     \relates <QtGlobal>