[Development] Another integer typedef OR how to prepare for 64-bit in Qt 5

[Thiago Macieira]

We have a lot of API that, for Qt 6, we've already decided to extend to 64-bit 
on 64-bit platforms, but keep as decently-sized 32-bit on 32-bit ones. We've 
already created the type we want for Qt 6 and that's "qsizetype": a signed 
integer the same size as size_t and ptrdiff_t. And a lot of new API already 
uses it, for example:
	https://doc.qt.io/qt-5/qstringview.html#at
	http://doc-snapshots.qt.io/qt5-dev/qcborarray.html#at

And internally, we can use decltype(), auto or one of the typedefs to make 
optimal use. Example:
struct ByteData
{
    QByteArray::size_type len;

But how do we begin porting our API? For example:
	https://doc.qt.io/qt-5/qstring.html#at
	https://doc.qt.io/qt-5/qbytearray.html#at

These two functions are declared as taking int parameters. Similarly,
	https://doc.qt.io/qt-5/qstring.html#indexOf
returns an int index.

This porting will take a lot of time, since the use of "int" is so pervasive 
in our code. And we can't change them to qsizetype right now, it would be a BC 
break.

What do we do?

Option 1: do nothing, wait for Qt 6 and do the change then
This is the simplest solution for now, but hardest in the future. It would 
mean finding all the issues in a very short amount of time and it would make 
merges across 5.15 and 6.0 very difficult.

Option 2: insert #if in our API, starting now
This works and is the same amount of work as almost all of the rest. But it's 
VERY ugly.

Option 3: use #if per class, starting now
For example, change QString to have:
#if QT_VERSION >= QT_VERSION_CHECK(6,0,0)
    typedef qsizetype size_type;
#else
    typedef int size_type;
#endif
And then change all uses in QString from "int" to size_type in the API.

This is the cleanest and follows the precedence of the Standard Library. But 
as a side-effect, we may have very long names in our code and they'll show up 
in the documentation too. This would also require adding such typedefs to 
classes that currently don't have them, like QPixmap and QImage.

Option 4: create a central #if and use this new type, starting now
Same as #3, but instead of per class, it would be central. Moreover, with one 
preprocessor trick (-Dnewinttype=int), we can fool qdoc into generating 
documentation as it is today. In Qt 6, once we decide we don't need Qt 5 
merging anymore, we can also do a global search-and-replace to qsizetype 
(optional).

Other options?

I think Option 4 is the best solution, among those that I listed.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center