Details

Type: Bug

Status: Reported

Priority: P3: Somewhat important

Resolution: Unresolved

Affects Version/s: 5.15, 6.1

Fix Version/s: None

Component/s: Core: Other, Documentation

Labels:None
Description
Problem
The example code for QPoint::dotProduct() and QPointF::dotProduct() is as follows:
QPoint p( 3, 7); QPoint q(1, 4); int lengthSquared = QPoint::dotProduct(p, q); // lengthSquared becomes 25
The name "lengthSquared" is definitively wrong. In this special case, the result (25) is actually the squared distance between the two points. But in generic cases, dotProduct() returns the dot product of the two points interpreted as 2element vectors.
The dot product of two 2element vectors is defined as follows (source code of QPointF::dotProduct()):
return p1.xp * p2.xp + p1.yp * p2.yp;
As easily seen, the result is negative in 50% of all cases. This can not be a squared distance.
Suggestion
The dot product's most popular property is that it is equal to zero if the two vectors are perpendicular. So I suggest to replace the example code by the following:
QPoint p( 3, 7); QPoint q(1, 4); if (QPoint::dotProduct(p, q) == 0) { qDebug() << "Vectors p and q are perpendicular! (Or one of them is null.)"; } else { qDebug() << "Vectors p and q are not perpendicular."; }
Or simply by this:
QPoint p( 3, 7); QPoint q(1, 4); int dotProduct = QPoint::dotProduct(p, q); // Equivalent to int dotProduct = p.x() * q.x() + p.y() * q.y()