[Development] QRect::contains and undocumented(?) edge

[Tomi Pannila]

Hi Qt developers,



could you please explain how your method "QRect::contains(const QRect 
&r, bool proper)" at
https://code.qt.io/cgit/qt/qtbase.git/tree/src/corelib/tools/qrect.cpp?h=dev
satisfies your API design principles
1. Have clear and simple semantics
2. Be intuitive
3. Be easy to memorize
4. Lead to readable code
from https://wiki.qt.io/API_Design_Principles ?

More precisely, I'm talking about the edge related stuff, which is not 
documented properly in Qt documentation. The meaning of an edge is not 
defined(?).
What files make use of the edge property?
Wouldn't it be better to create a separate class for edged rectangles, 
if rectangles with edges are needed?
With separate class one could have custom edge sizes as a bonus.
It would also be good if in your documentation you would define 
mathematically what is meant by a rectangle.
Something like
"
For $x1 < 2$ and $y1 < y2$,
$$QRect(x1, x2, y1, y2) := \set{ (x, y) \in int^2  \quad |  \quad x1 \le 
x \le x2 \quad \text{and} \quad y1 \le y \le y2 }$$
"
could work together with mathjax, https://www.mathjax.org/ .

I can guess that x1 x2, with x2 < x1, is "allowed" in QRect due to 
easier manipulation of QRects in some cases (all ints) (references to 
such cases?),
but it flips the left accessor to actually right(?), hence making it 
illogical. Similarly for y1 and y2. I see the isValid method.
I mean, one could have "int left, top;" and "unsigned int width, 
height;" instead of "int x1, x2, y1, y2" to describe QRect.



Earlier I was browsing qcosmeticstroke.cpp where clip check with a point 
is multiple times checked(?) with
"
const QRect &cl = stroker->clip;
     if (x < cl.x() || x > cl.right() || y < cl.y() || y > cl.bottom())
         return;
"
https://code.qt.io/cgit/qt/qtbase.git/tree/src/gui/painting/qcosmeticstroker.cpp

I was expecting to see this kind of implementation, with negation, in 
QRect::contains. I was also thinking if performance in rendering
is so important that a call to QRect::contains cannot be made, and that 
for some reason QRect::contains cannot be made inline.
Perhaps there is a way to include an inline implementation of 
QRect::contains to QRect.h which could be used here?



At
https://doc-snapshots.qt.io/qt6-dev/qrect.html
something is mentioned about "historical reasons". No further arguments 
or links given. Perhaps this is the source of the confusion I have?
Are these historical reasons permanent or do you plan to move away from 
these historical reasons? What would go wrong if you abandon the 
historical reasons?
I'm aware that QRect has been illogical for a long time
https://www.qtcentre.org/threads/6561-what-are-the-historical-reasons-mentioned-in-the-QRect-class-reference



I have no commits in Qt. This is my first post to development mailing list.



Best Regards,
Tomi Pannila