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

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