Thiago Macieira
2018-11-02 03:42:52 UTC
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
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