1// Copyright (C) 2022 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qpoint.h"
5#include "qdatastream.h"
6
7#include <private/qdebug_p.h>
8#include <QtCore/qhashfunctions.h>
9
10QT_BEGIN_NAMESPACE
11
12/*!
13 \class QPoint
14 \inmodule QtCore
15 \ingroup painting
16 \reentrant
17
18 \brief The QPoint class defines a point in the plane using integer
19 precision.
20
21 A point is specified by a x coordinate and an y coordinate which
22 can be accessed using the x() and y() functions. The isNull()
23 function returns \c true if both x and y are set to 0. The
24 coordinates can be set (or altered) using the setX() and setY()
25 functions, or alternatively the rx() and ry() functions which
26 return references to the coordinates (allowing direct
27 manipulation).
28
29 Given a point \e p, the following statements are all equivalent:
30
31 \snippet code/src_corelib_tools_qpoint.cpp 0
32
33 A QPoint object can also be used as a vector: Addition and
34 subtraction are defined as for vectors (each component is added
35 separately). A QPoint object can also be divided or multiplied by
36 an \c int or a \c qreal.
37
38 In addition, the QPoint class provides the manhattanLength()
39 function which gives an inexpensive approximation of the length of
40 the QPoint object interpreted as a vector. Finally, QPoint objects
41 can be streamed as well as compared.
42
43 \sa QPointF, QPolygon
44*/
45
46
47/*****************************************************************************
48 QPoint member functions
49 *****************************************************************************/
50
51/*!
52 \fn QPoint::QPoint()
53
54 Constructs a null point, i.e. with coordinates (0, 0)
55
56 \sa isNull()
57*/
58
59/*!
60 \fn QPoint::QPoint(int xpos, int ypos)
61
62 Constructs a point with the given coordinates (\a xpos, \a ypos).
63
64 \sa setX(), setY()
65*/
66
67/*!
68 \fn bool QPoint::isNull() const
69
70 Returns \c true if both the x and y coordinates are set to 0,
71 otherwise returns \c false.
72*/
73
74/*!
75 \fn int QPoint::x() const
76
77 Returns the x coordinate of this point.
78
79 \sa setX(), rx()
80*/
81
82/*!
83 \fn int QPoint::y() const
84
85 Returns the y coordinate of this point.
86
87 \sa setY(), ry()
88*/
89
90/*!
91 \fn void QPoint::setX(int x)
92
93 Sets the x coordinate of this point to the given \a x coordinate.
94
95 \sa x(), setY()
96*/
97
98/*!
99 \fn void QPoint::setY(int y)
100
101 Sets the y coordinate of this point to the given \a y coordinate.
102
103 \sa y(), setX()
104*/
105
106/*!
107 \fn QPoint::transposed() const
108 \since 5.14
109
110 Returns a point with x and y coordinates exchanged:
111 \code
112 QPoint{1, 2}.transposed() // {2, 1}
113 \endcode
114
115 \sa x(), y(), setX(), setY()
116*/
117
118/*!
119 \fn int &QPoint::rx()
120
121 Returns a reference to the x coordinate of this point.
122
123 Using a reference makes it possible to directly manipulate x. For example:
124
125 \snippet code/src_corelib_tools_qpoint.cpp 1
126
127 \sa x(), setX()
128*/
129
130/*!
131 \fn int &QPoint::ry()
132
133 Returns a reference to the y coordinate of this point.
134
135 Using a reference makes it possible to directly manipulate y. For
136 example:
137
138 \snippet code/src_corelib_tools_qpoint.cpp 2
139
140 \sa y(), setY()
141*/
142
143
144/*!
145 \fn QPoint &QPoint::operator+=(const QPoint &point)
146
147 Adds the given \a point to this point and returns a reference to
148 this point. For example:
149
150 \snippet code/src_corelib_tools_qpoint.cpp 3
151
152 \sa operator-=()
153*/
154
155/*!
156 \fn QPoint &QPoint::operator-=(const QPoint &point)
157
158 Subtracts the given \a point from this point and returns a
159 reference to this point. For example:
160
161 \snippet code/src_corelib_tools_qpoint.cpp 4
162
163 \sa operator+=()
164*/
165
166/*!
167 \fn QPoint &QPoint::operator*=(float factor)
168
169 Multiplies this point's coordinates by the given \a factor, and
170 returns a reference to this point.
171
172 Note that the result is rounded to the nearest integer as points are held as
173 integers. Use QPointF for floating point accuracy.
174
175 \sa operator/=()
176*/
177
178/*!
179 \fn QPoint &QPoint::operator*=(double factor)
180
181 Multiplies this point's coordinates by the given \a factor, and
182 returns a reference to this point. For example:
183
184 \snippet code/src_corelib_tools_qpoint.cpp 5
185
186 Note that the result is rounded to the nearest integer as points are held as
187 integers. Use QPointF for floating point accuracy.
188
189 \sa operator/=()
190*/
191
192/*!
193 \fn QPoint &QPoint::operator*=(int factor)
194
195 Multiplies this point's coordinates by the given \a factor, and
196 returns a reference to this point.
197
198 \sa operator/=()
199*/
200
201/*!
202 \fn static int QPoint::dotProduct(const QPoint &p1, const QPoint &p2)
203 \since 5.1
204
205 \snippet code/src_corelib_tools_qpoint.cpp 16
206
207 Returns the dot product of \a p1 and \a p2.
208*/
209
210/*!
211 \fn bool QPoint::operator==(const QPoint &p1, const QPoint &p2)
212
213 Returns \c true if \a p1 and \a p2 are equal; otherwise returns
214 false.
215*/
216
217/*!
218 \fn bool QPoint::operator!=(const QPoint &p1, const QPoint &p2)
219
220 Returns \c true if \a p1 and \a p2 are not equal; otherwise returns \c false.
221*/
222
223/*!
224 \fn QPoint QPoint::operator+(const QPoint &p1, const QPoint &p2)
225
226 Returns a QPoint object that is the sum of the given points, \a p1
227 and \a p2; each component is added separately.
228
229 \sa QPoint::operator+=()
230*/
231
232/*!
233 \fn Point QPoint::operator-(const QPoint &p1, const QPoint &p2)
234
235 Returns a QPoint object that is formed by subtracting \a p2 from
236 \a p1; each component is subtracted separately.
237
238 \sa QPoint::operator-=()
239*/
240
241/*!
242 \fn QPoint QPoint::operator*(const QPoint &point, float factor)
243
244 Returns a copy of the given \a point multiplied by the given \a factor.
245
246 Note that the result is rounded to the nearest integer as points
247 are held as integers. Use QPointF for floating point accuracy.
248
249 \sa QPoint::operator*=()
250*/
251
252/*!
253 \fn QPoint QPoint::operator*(const QPoint &point, double factor)
254
255 Returns a copy of the given \a point multiplied by the given \a factor.
256
257 Note that the result is rounded to the nearest integer as points
258 are held as integers. Use QPointF for floating point accuracy.
259
260 \sa QPoint::operator*=()
261*/
262
263/*!
264 \fn QPoint QPoint::operator*(const QPoint &point, int factor)
265
266 Returns a copy of the given \a point multiplied by the given \a factor.
267
268 \sa QPoint::operator*=()
269*/
270
271/*!
272 \fn QPoint QPoint::operator*(float factor, const QPoint &point)
273 \overload
274
275 Returns a copy of the given \a point multiplied by the given \a factor.
276
277 Note that the result is rounded to the nearest integer as points
278 are held as integers. Use QPointF for floating point accuracy.
279
280 \sa QPoint::operator*=()
281*/
282
283/*!
284 \fn QPoint QPoint::operator*(double factor, const QPoint &point)
285 \overload
286
287 Returns a copy of the given \a point multiplied by the given \a factor.
288
289 Note that the result is rounded to the nearest integer as points
290 are held as integers. Use QPointF for floating point accuracy.
291
292 \sa QPoint::operator*=()
293*/
294
295/*!
296 \fn QPoint QPoint::operator*(int factor, const QPoint &point)
297 \overload
298
299 Returns a copy of the given \a point multiplied by the given \a factor.
300
301 \sa QPoint::operator*=()
302*/
303
304/*!
305 \fn QPoint QPoint::operator+(const QPoint &point)
306 \since 5.0
307
308 Returns \a point unmodified.
309*/
310
311/*!
312 \fn QPoint QPoint::operator-(const QPoint &point)
313 \overload
314
315 Returns a QPoint object that is formed by changing the sign of
316 both components of the given \a point.
317
318 Equivalent to \c{QPoint(0,0) - point}.
319*/
320
321/*!
322 \fn QPoint &QPoint::operator/=(qreal divisor)
323 \overload
324
325 Divides both x and y by the given \a divisor, and returns a reference to this
326 point. For example:
327
328 \snippet code/src_corelib_tools_qpoint.cpp 6
329
330 Note that the result is rounded to the nearest integer as points are held as
331 integers. Use QPointF for floating point accuracy.
332
333 \sa operator*=()
334*/
335
336/*!
337 \fn const QPoint QPoint::operator/(const QPoint &point, qreal divisor)
338
339 Returns the QPoint formed by dividing both components of the given \a point
340 by the given \a divisor.
341
342 Note that the result is rounded to the nearest integer as points are held as
343 integers. Use QPointF for floating point accuracy.
344
345 \sa QPoint::operator/=()
346*/
347
348/*!
349 \fn QPoint::toPointF() const
350 \since 6.4
351
352 Returns this point as a point with floating point accuracy.
353
354 \sa QPointF::toPoint()
355*/
356
357/*****************************************************************************
358 QPoint stream functions
359 *****************************************************************************/
360#ifndef QT_NO_DATASTREAM
361/*!
362 \fn QDataStream &operator<<(QDataStream &stream, const QPoint &point)
363 \relates QPoint
364
365 Writes the given \a point to the given \a stream and returns a
366 reference to the stream.
367
368 \sa {Serializing Qt Data Types}
369*/
370
371QDataStream &operator<<(QDataStream &s, const QPoint &p)
372{
373 if (s.version() == 1)
374 s << (qint16)p.x() << (qint16)p.y();
375 else
376 s << (qint32)p.x() << (qint32)p.y();
377 return s;
378}
379
380/*!
381 \fn QDataStream &operator>>(QDataStream &stream, QPoint &point)
382 \relates QPoint
383
384 Reads a point from the given \a stream into the given \a point
385 and returns a reference to the stream.
386
387 \sa {Serializing Qt Data Types}
388*/
389
390QDataStream &operator>>(QDataStream &s, QPoint &p)
391{
392 if (s.version() == 1) {
393 qint16 x, y;
394 s >> x; p.rx() = x;
395 s >> y; p.ry() = y;
396 }
397 else {
398 qint32 x, y;
399 s >> x; p.rx() = x;
400 s >> y; p.ry() = y;
401 }
402 return s;
403}
404
405#endif // QT_NO_DATASTREAM
406/*!
407 \fn int QPoint::manhattanLength() const
408
409 Returns the sum of the absolute values of x() and y(),
410 traditionally known as the "Manhattan length" of the vector from
411 the origin to the point. For example:
412
413 \snippet code/src_corelib_tools_qpoint.cpp 7
414
415 This is a useful, and quick to calculate, approximation to the
416 true length:
417
418 \snippet code/src_corelib_tools_qpoint.cpp 8
419
420 The tradition of "Manhattan length" arises because such distances
421 apply to travelers who can only travel on a rectangular grid, like
422 the streets of Manhattan.
423*/
424
425#ifndef QT_NO_DEBUG_STREAM
426QDebug operator<<(QDebug dbg, const QPoint &p)
427{
428 QDebugStateSaver saver(dbg);
429 dbg.nospace();
430 dbg << "QPoint" << '(';
431 QtDebugUtils::formatQPoint(debug&: dbg, point: p);
432 dbg << ')';
433 return dbg;
434}
435
436QDebug operator<<(QDebug dbg, const QPointF &p)
437{
438 QDebugStateSaver saver(dbg);
439 dbg.nospace();
440 dbg << "QPointF" << '(';
441 QtDebugUtils::formatQPoint(debug&: dbg, point: p);
442 dbg << ')';
443 return dbg;
444}
445#endif
446
447/*!
448 \fn size_t qHash(QPoint key, size_t seed = 0)
449 \relates QHash
450 \since 6.0
451
452 Returns the hash value for the \a key, using \a seed to seed the
453 calculation.
454*/
455size_t qHash(QPoint key, size_t seed) noexcept
456{
457 return qHashMulti(seed, args: key.x(), args: key.y());
458}
459
460/*!
461 \class QPointF
462 \inmodule QtCore
463 \ingroup painting
464 \reentrant
465
466 \brief The QPointF class defines a point in the plane using
467 floating point precision.
468
469 A point is specified by a x coordinate and an y coordinate which
470 can be accessed using the x() and y() functions. The coordinates
471 of the point are specified using finite floating point numbers for
472 accuracy. The isNull() function returns \c true if both x and y are
473 set to 0.0. The coordinates can be set (or altered) using the setX()
474 and setY() functions, or alternatively the rx() and ry() functions which
475 return references to the coordinates (allowing direct
476 manipulation).
477
478 Given a point \e p, the following statements are all equivalent:
479
480 \snippet code/src_corelib_tools_qpoint.cpp 9
481
482 A QPointF object can also be used as a vector: Addition and
483 subtraction are defined as for vectors (each component is added
484 separately). A QPointF object can also be divided or multiplied by
485 an \c int or a \c qreal.
486
487 In addition, the QPointF class provides a constructor converting a
488 QPoint object into a QPointF object, and a corresponding toPoint()
489 function which returns a QPoint copy of \e this point. Finally,
490 QPointF objects can be streamed as well as compared.
491
492 \sa QPoint, QPolygonF
493*/
494
495/*!
496 \fn QPointF::QPointF()
497
498 Constructs a null point, i.e. with coordinates (0.0, 0.0)
499
500 \sa isNull()
501*/
502
503/*!
504 \fn QPointF::QPointF(const QPoint &point)
505
506 Constructs a copy of the given \a point.
507
508 \sa toPoint(), QPoint::toPointF()
509*/
510
511/*!
512 \fn QPointF::QPointF(qreal xpos, qreal ypos)
513
514 Constructs a point with the given coordinates (\a xpos, \a ypos).
515
516 \sa setX(), setY()
517*/
518
519/*!
520 \fn bool QPointF::isNull() const
521
522 Returns \c true if both the x and y coordinates are set to 0.0 (ignoring
523 the sign); otherwise returns \c false.
524*/
525
526
527/*!
528 \fn qreal QPointF::manhattanLength() const
529 \since 4.6
530
531 Returns the sum of the absolute values of x() and y(),
532 traditionally known as the "Manhattan length" of the vector from
533 the origin to the point.
534
535 \sa QPoint::manhattanLength()
536*/
537
538/*!
539 \fn qreal QPointF::x() const
540
541 Returns the x coordinate of this point.
542
543 \sa setX(), rx()
544*/
545
546/*!
547 \fn qreal QPointF::y() const
548
549 Returns the y coordinate of this point.
550
551 \sa setY(), ry()
552*/
553
554/*!
555 \fn void QPointF::setX(qreal x)
556
557 Sets the x coordinate of this point to the given finite \a x coordinate.
558
559 \sa x(), setY()
560*/
561
562/*!
563 \fn void QPointF::setY(qreal y)
564
565 Sets the y coordinate of this point to the given finite \a y coordinate.
566
567 \sa y(), setX()
568*/
569
570/*!
571 \fn QPointF::transposed() const
572 \since 5.14
573
574 Returns a point with x and y coordinates exchanged:
575 \code
576 QPointF{1.0, 2.0}.transposed() // {2.0, 1.0}
577 \endcode
578
579 \sa x(), y(), setX(), setY()
580*/
581
582/*!
583 \fn qreal& QPointF::rx()
584
585 Returns a reference to the x coordinate of this point.
586
587 Using a reference makes it possible to directly manipulate x. For example:
588
589 \snippet code/src_corelib_tools_qpoint.cpp 10
590
591 \sa x(), setX()
592*/
593
594/*!
595 \fn qreal& QPointF::ry()
596
597 Returns a reference to the y coordinate of this point.
598
599 Using a reference makes it possible to directly manipulate y. For example:
600
601 \snippet code/src_corelib_tools_qpoint.cpp 11
602
603 \sa y(), setY()
604*/
605
606/*!
607 \fn QPointF& QPointF::operator+=(const QPointF &point)
608
609 Adds the given \a point to this point and returns a reference to
610 this point. For example:
611
612 \snippet code/src_corelib_tools_qpoint.cpp 12
613
614 \sa operator-=()
615*/
616
617/*!
618 \fn QPointF& QPointF::operator-=(const QPointF &point)
619
620 Subtracts the given \a point from this point and returns a reference
621 to this point. For example:
622
623 \snippet code/src_corelib_tools_qpoint.cpp 13
624
625 \sa operator+=()
626*/
627
628/*!
629 \fn QPointF& QPointF::operator*=(qreal factor)
630
631 Multiplies this point's coordinates by the given finite \a factor, and
632 returns a reference to this point. For example:
633
634 \snippet code/src_corelib_tools_qpoint.cpp 14
635
636 \sa operator/=()
637*/
638
639/*!
640 \fn QPointF& QPointF::operator/=(qreal divisor)
641
642 Divides both x and y by the given \a divisor, and returns a reference
643 to this point. For example:
644
645 \snippet code/src_corelib_tools_qpoint.cpp 15
646
647 The \a divisor must not be zero or NaN.
648
649 \sa operator*=()
650*/
651
652/*!
653 \fn QPointF QPointF::operator+(const QPointF &p1, const QPointF &p2)
654
655 Returns a QPointF object that is the sum of the given points, \a p1
656 and \a p2; each component is added separately.
657
658 \sa QPointF::operator+=()
659*/
660
661/*!
662 \fn QPointF QPointF::operator-(const QPointF &p1, const QPointF &p2)
663
664 Returns a QPointF object that is formed by subtracting \a p2 from \a p1;
665 each component is subtracted separately.
666
667 \sa QPointF::operator-=()
668*/
669
670/*!
671 \fn QPointF QPointF::operator*(const QPointF &point, qreal factor)
672
673 Returns a copy of the given \a point, multiplied by the given finite \a factor.
674
675 \sa QPointF::operator*=()
676*/
677
678/*!
679 \fn QPointF QPointF::operator*(qreal factor, const QPointF &point)
680
681 \overload
682
683 Returns a copy of the given \a point, multiplied by the given finite \a factor.
684*/
685
686/*!
687 \fn QPointF QPointF::operator+(const QPointF &point)
688 \since 5.0
689
690 Returns \a point unmodified.
691*/
692
693/*!
694 \fn QPointF QPointF::operator-(const QPointF &point)
695 \overload
696
697 Returns a QPointF object that is formed by changing the sign of
698 each component of the given \a point.
699
700 Equivalent to \c {QPointF(0,0) - point}.
701*/
702
703/*!
704 \fn QPointF QPointF::operator/(const QPointF &point, qreal divisor)
705
706 Returns the QPointF object formed by dividing each component of
707 the given \a point by the given \a divisor.
708
709 The \a divisor must not be zero or NaN.
710
711 \sa QPointF::operator/=()
712*/
713
714/*!
715 \fn QPoint QPointF::toPoint() const
716
717 Rounds the coordinates of this point to the nearest integer, and
718 returns a QPoint object with the rounded coordinates.
719
720 \sa QPointF(), QPoint::toPointF()
721*/
722
723/*!
724 \fn static qreal QPointF::dotProduct(const QPointF &p1, const QPointF &p2)
725 \since 5.1
726
727 \snippet code/src_corelib_tools_qpoint.cpp 17
728
729 Returns the dot product of \a p1 and \a p2.
730*/
731
732/*!
733 \fn bool QPointF::operator==(const QPointF &p1, const QPointF &p2)
734
735 Returns \c true if \a p1 is approximately equal to \a p2; otherwise
736 returns \c false.
737
738 \warning This function does not check for strict equality; instead,
739 it uses a fuzzy comparison to compare the points' coordinates.
740
741 \sa qFuzzyCompare
742*/
743
744/*!
745 \fn bool QPointF::operator!=(const QPointF &p1, const QPointF &p2);
746
747 Returns \c true if \a p1 is sufficiently different from \a p2;
748 otherwise returns \c false.
749
750 \warning This function does not check for strict inequality; instead,
751 it uses a fuzzy comparison to compare the points' coordinates.
752
753 \sa qFuzzyCompare
754*/
755
756#ifndef QT_NO_DATASTREAM
757/*!
758 \fn QDataStream &operator<<(QDataStream &stream, const QPointF &point)
759 \relates QPointF
760
761 Writes the given \a point to the given \a stream and returns a
762 reference to the stream.
763
764 \sa {Serializing Qt Data Types}
765*/
766
767QDataStream &operator<<(QDataStream &s, const QPointF &p)
768{
769 s << double(p.x()) << double(p.y());
770 return s;
771}
772
773/*!
774 \fn QDataStream &operator>>(QDataStream &stream, QPointF &point)
775 \relates QPointF
776
777 Reads a point from the given \a stream into the given \a point
778 and returns a reference to the stream.
779
780 \sa {Serializing Qt Data Types}
781*/
782
783QDataStream &operator>>(QDataStream &s, QPointF &p)
784{
785 double x, y;
786 s >> x;
787 s >> y;
788 p.setX(qreal(x));
789 p.setY(qreal(y));
790 return s;
791}
792#endif // QT_NO_DATASTREAM
793
794QT_END_NAMESPACE
795

source code of qtbase/src/corelib/tools/qpoint.cpp