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 \fn size_t qHash(QPoint key, size_t seed = 0)
454 \relates QHash
455 \since 6.0
456
457 Returns the hash value for the \a key, using \a seed to seed the
458 calculation.
459*/
460size_t qHash(QPoint key, size_t seed) noexcept
461{
462 return qHashMulti(seed, args: key.x(), args: key.y());
463}
464
465/*!
466 \class QPointF
467 \inmodule QtCore
468 \ingroup painting
469 \reentrant
470
471 \compares equality
472 \compareswith equality QPoint
473 \endcompareswith
474
475 \brief The QPointF class defines a point in the plane using
476 floating point precision.
477
478 A point is specified by a x coordinate and an y coordinate which
479 can be accessed using the x() and y() functions. The coordinates
480 of the point are specified using finite floating point numbers for
481 accuracy. The isNull() function returns \c true if both x and y are
482 set to 0.0. The coordinates can be set (or altered) using the setX()
483 and setY() functions, or alternatively the rx() and ry() functions which
484 return references to the coordinates (allowing direct
485 manipulation).
486
487 Given a point \e p, the following statements are all equivalent:
488
489 \snippet code/src_corelib_tools_qpoint.cpp 9
490
491 A QPointF object can also be used as a vector: Addition and
492 subtraction are defined as for vectors (each component is added
493 separately). A QPointF object can also be divided or multiplied by
494 an \c int or a \c qreal.
495
496 In addition, the QPointF class provides a constructor converting a
497 QPoint object into a QPointF object, and a corresponding toPoint()
498 function which returns a QPoint copy of \e this point. Finally,
499 QPointF objects can be streamed as well as compared.
500
501 \sa QPoint, QPolygonF
502*/
503
504/*!
505 \fn QPointF::QPointF()
506
507 Constructs a null point, i.e. with coordinates (0.0, 0.0)
508
509 \sa isNull()
510*/
511
512/*!
513 \fn QPointF::QPointF(const QPoint &point)
514
515 Constructs a copy of the given \a point.
516
517 \sa toPoint(), QPoint::toPointF()
518*/
519
520/*!
521 \fn QPointF::QPointF(qreal xpos, qreal ypos)
522
523 Constructs a point with the given coordinates (\a xpos, \a ypos).
524
525 \sa setX(), setY()
526*/
527
528/*!
529 \fn bool QPointF::isNull() const
530
531 Returns \c true if both the x and y coordinates are set to 0.0 (ignoring
532 the sign); otherwise returns \c false.
533*/
534
535
536/*!
537 \fn qreal QPointF::manhattanLength() const
538 \since 4.6
539
540 Returns the sum of the absolute values of x() and y(),
541 traditionally known as the "Manhattan length" of the vector from
542 the origin to the point.
543
544 \sa QPoint::manhattanLength()
545*/
546
547/*!
548 \fn qreal QPointF::x() const
549
550 Returns the x coordinate of this point.
551
552 \sa setX(), rx()
553*/
554
555/*!
556 \fn qreal QPointF::y() const
557
558 Returns the y coordinate of this point.
559
560 \sa setY(), ry()
561*/
562
563/*!
564 \fn void QPointF::setX(qreal x)
565
566 Sets the x coordinate of this point to the given finite \a x coordinate.
567
568 \sa x(), setY()
569*/
570
571/*!
572 \fn void QPointF::setY(qreal y)
573
574 Sets the y coordinate of this point to the given finite \a y coordinate.
575
576 \sa y(), setX()
577*/
578
579/*!
580 \fn QPointF::transposed() const
581 \since 5.14
582
583 Returns a point with x and y coordinates exchanged:
584 \code
585 QPointF{1.0, 2.0}.transposed() // {2.0, 1.0}
586 \endcode
587
588 \sa x(), y(), setX(), setY()
589*/
590
591/*!
592 \fn qreal& QPointF::rx()
593
594 Returns a reference to the x coordinate of this point.
595
596 Using a reference makes it possible to directly manipulate x. For example:
597
598 \snippet code/src_corelib_tools_qpoint.cpp 10
599
600 \sa x(), setX()
601*/
602
603/*!
604 \fn qreal& QPointF::ry()
605
606 Returns a reference to the y coordinate of this point.
607
608 Using a reference makes it possible to directly manipulate y. For example:
609
610 \snippet code/src_corelib_tools_qpoint.cpp 11
611
612 \sa y(), setY()
613*/
614
615/*!
616 \fn QPointF& QPointF::operator+=(const QPointF &point)
617
618 Adds the given \a point to this point and returns a reference to
619 this point. For example:
620
621 \snippet code/src_corelib_tools_qpoint.cpp 12
622
623 \sa operator-=()
624*/
625
626/*!
627 \fn QPointF& QPointF::operator-=(const QPointF &point)
628
629 Subtracts the given \a point from this point and returns a reference
630 to this point. For example:
631
632 \snippet code/src_corelib_tools_qpoint.cpp 13
633
634 \sa operator+=()
635*/
636
637/*!
638 \fn QPointF& QPointF::operator*=(qreal factor)
639
640 Multiplies this point's coordinates by the given finite \a factor, and
641 returns a reference to this point. For example:
642
643 \snippet code/src_corelib_tools_qpoint.cpp 14
644
645 \sa operator/=()
646*/
647
648/*!
649 \fn QPointF& QPointF::operator/=(qreal divisor)
650
651 Divides both x and y by the given \a divisor, and returns a reference
652 to this point. For example:
653
654 \snippet code/src_corelib_tools_qpoint.cpp 15
655
656 The \a divisor must not be zero or NaN.
657
658 \sa operator*=()
659*/
660
661/*!
662 \fn QPointF QPointF::operator+(const QPointF &p1, const QPointF &p2)
663
664 Returns a QPointF object that is the sum of the given points, \a p1
665 and \a p2; each component is added separately.
666
667 \sa QPointF::operator+=()
668*/
669
670/*!
671 \fn QPointF QPointF::operator-(const QPointF &p1, const QPointF &p2)
672
673 Returns a QPointF object that is formed by subtracting \a p2 from \a p1;
674 each component is subtracted separately.
675
676 \sa QPointF::operator-=()
677*/
678
679/*!
680 \fn QPointF QPointF::operator*(const QPointF &point, qreal factor)
681
682 Returns a copy of the given \a point, multiplied by the given finite \a factor.
683
684 \sa QPointF::operator*=()
685*/
686
687/*!
688 \fn QPointF QPointF::operator*(qreal factor, const QPointF &point)
689
690 \overload
691
692 Returns a copy of the given \a point, multiplied by the given finite \a factor.
693*/
694
695/*!
696 \fn QPointF QPointF::operator+(const QPointF &point)
697 \since 5.0
698
699 Returns \a point unmodified.
700*/
701
702/*!
703 \fn QPointF QPointF::operator-(const QPointF &point)
704 \overload
705
706 Returns a QPointF object that is formed by changing the sign of
707 each component of the given \a point.
708
709 Equivalent to \c {QPointF(0,0) - point}.
710*/
711
712/*!
713 \fn QPointF QPointF::operator/(const QPointF &point, qreal divisor)
714
715 Returns the QPointF object formed by dividing each component of
716 the given \a point by the given \a divisor.
717
718 The \a divisor must not be zero or NaN.
719
720 \sa QPointF::operator/=()
721*/
722
723/*!
724 \fn QPoint QPointF::toPoint() const
725
726 Rounds the coordinates of this point to the nearest integer, and
727 returns a QPoint object with the rounded coordinates.
728
729 \sa QPointF(), QPoint::toPointF()
730*/
731
732/*!
733 \fn static qreal QPointF::dotProduct(const QPointF &p1, const QPointF &p2)
734 \since 5.1
735
736 \snippet code/src_corelib_tools_qpoint.cpp 17
737
738 Returns the dot product of \a p1 and \a p2.
739*/
740
741/*!
742 \fn bool QPointF::operator==(const QPointF &lhs, const QPointF &rhs)
743
744 Returns \c true if \a lhs is approximately equal to \a rhs; otherwise
745 returns \c false.
746
747 \warning This function does not check for strict equality; instead,
748 it uses a fuzzy comparison to compare the points' coordinates.
749
750 \sa qFuzzyCompare
751*/
752
753/*!
754 \fn bool QPointF::operator!=(const QPointF &lhs, const QPointF &rhs)
755
756 Returns \c true if \a lhs is sufficiently different from \a rhs;
757 otherwise returns \c false.
758
759 \warning This function does not check for strict inequality; instead,
760 it uses a fuzzy comparison to compare the points' coordinates.
761
762 \sa qFuzzyCompare
763*/
764
765/*!
766 \fn bool QPointF::qFuzzyCompare(const QPointF &p1, const QPointF &p2)
767 \since 6.8
768
769 Returns \c true if \a p1 is approximately equal to \a p2; otherwise
770 returns \c false.
771
772 \sa qFuzzyIsNull
773*/
774
775/*!
776 \fn bool QPointF::qFuzzyIsNull(const QPointF &point)
777 \since 6.8
778
779 Returns \c true if \a point is approximately equal to a point
780 \c {(0.0, 0.0)}.
781
782 \sa qFuzzyCompare
783*/
784
785#ifndef QT_NO_DATASTREAM
786/*!
787 \fn QDataStream &operator<<(QDataStream &stream, const QPointF &point)
788 \relates QPointF
789
790 Writes the given \a point to the given \a stream and returns a
791 reference to the stream.
792
793 \sa {Serializing Qt Data Types}
794*/
795
796QDataStream &operator<<(QDataStream &s, const QPointF &p)
797{
798 s << double(p.x()) << double(p.y());
799 return s;
800}
801
802/*!
803 \fn QDataStream &operator>>(QDataStream &stream, QPointF &point)
804 \relates QPointF
805
806 Reads a point from the given \a stream into the given \a point
807 and returns a reference to the stream.
808
809 \sa {Serializing Qt Data Types}
810*/
811
812QDataStream &operator>>(QDataStream &s, QPointF &p)
813{
814 double x, y;
815 s >> x;
816 s >> y;
817 p.setX(qreal(x));
818 p.setY(qreal(y));
819 return s;
820}
821#endif // QT_NO_DATASTREAM
822
823QT_END_NAMESPACE
824

Provided by KDAB

Privacy Policy
Start learning QML with our Intro Training
Find out more

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