1use core::{
2 convert::{TryFrom, TryInto},
3 fmt,
4 ops::{Add, AddAssign, Div, DivAssign, Index, Mul, MulAssign, Neg, Sub, SubAssign},
5};
6
7use crate::geometry::Size;
8
9/// 2D point.
10///
11/// A point can be used to define the position of a graphics object. For example, a [`Rectangle`]
12/// may be defined that has its top left corner at `(-1, -2)`. To specify the size of an object
13/// [`Size`] should be used instead.
14///
15/// [Nalgebra] support can be enabled with the `nalgebra_support` feature. This implements
16/// `From<Vector2<N>>` and `From<&Vector2<N>>` where `N` is `Scalar + Into<i32>`. This allows use
17/// of Nalgebra's [`Vector2`] with embedded-graphics where `i8`, `i16`, `i32`, `u16` or `u8` is used
18/// for value storage.
19///
20/// # Examples
21///
22/// ## Create a `Point` from two integers
23///
24/// ```rust
25/// use embedded_graphics::geometry::Point;
26///
27/// // Create a coord using the `new` constructor method
28/// let p = Point::new(10, 20);
29/// ```
30///
31/// ## Create a `Point` from a Nalgebra `Vector2`
32///
33/// _Be sure to enable the `nalgebra_support` feature to get [Nalgebra] integration._
34///
35/// ```rust
36/// # #[cfg(feature = "nalgebra_support")] {
37/// use embedded_graphics::geometry::Point;
38/// use nalgebra::Vector2;
39///
40/// let n_coord = Vector2::new(10i32, 20);
41///
42/// assert_eq!(Point::from(n_coord), Point::new(10, 20));
43/// # }
44/// ```
45///
46/// ## Convert a `Vector2<u8>` into a `Point`
47///
48/// _Be sure to enable the `nalgebra_support` feature to get [Nalgebra] integration._
49///
50/// Smaller unsigned types that can be converted to `i32` are also supported in conversions.
51///
52/// ```rust
53/// # #[cfg(feature = "nalgebra_support")] {
54/// use embedded_graphics::geometry::Point;
55/// use nalgebra::Vector2;
56///
57/// let n_coord = Vector2::new(10u8, 20);
58///
59/// assert_eq!(Point::from(n_coord), Point::new(10, 20));
60/// # }
61/// ```
62///
63/// [`Rectangle`]: crate::primitives::rectangle::Rectangle
64/// [`Vector2<N>`]: https://docs.rs/nalgebra/0.18.0/nalgebra/base/type.Vector2.html
65/// [`Vector2`]: https://docs.rs/nalgebra/0.18.0/nalgebra/base/type.Vector2.html
66/// [Nalgebra]: https://docs.rs/nalgebra
67#[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug, Default)]
68#[cfg_attr(feature = "defmt", derive(::defmt::Format))]
69pub struct Point {
70 /// The x coordinate.
71 pub x: i32,
72
73 /// The y coordinate.
74 pub y: i32,
75}
76
77impl Point {
78 /// Creates a point from X and Y coordinates.
79 pub const fn new(x: i32, y: i32) -> Self {
80 Point { x, y }
81 }
82
83 /// Creates a point with X and Y values set to an equal value.
84 ///
85 /// # Examples
86 ///
87 /// ```rust
88 /// use embedded_graphics::geometry::Point;
89 ///
90 /// let point = Point::new_equal(11);
91 ///
92 /// assert_eq!(point, Point { x: 11, y: 11 });
93 /// ```
94 pub const fn new_equal(value: i32) -> Self {
95 Point { x: value, y: value }
96 }
97
98 /// Creates a point with X and Y equal to zero.
99 pub const fn zero() -> Self {
100 Point { x: 0, y: 0 }
101 }
102
103 /// Returns a point with equal `x` value and `y` set to `0`.
104 ///
105 /// # Examples
106 ///
107 /// ## Move a `Point` along the X axis.
108 ///
109 /// ```rust
110 /// use embedded_graphics::geometry::Point;
111 ///
112 /// let translate = Point::new(20, 30);
113 ///
114 /// let point = Point::new(10, 15);
115 ///
116 /// let moved_x = point + translate.x_axis();
117 ///
118 /// assert_eq!(moved_x, Point::new(30, 15));
119 /// ```
120 pub const fn x_axis(self) -> Self {
121 Self { x: self.x, y: 0 }
122 }
123
124 /// Returns a point with equal `y` value and `x` set to `0`.
125 ///
126 /// # Examples
127 ///
128 /// ## Move a `Point` along the Y axis.
129 ///
130 /// ```rust
131 /// use embedded_graphics::geometry::Point;
132 ///
133 /// let translate = Point::new(20, 30);
134 ///
135 /// let point = Point::new(10, 15);
136 ///
137 /// let moved_y = point + translate.y_axis();
138 ///
139 /// assert_eq!(moved_y, Point::new(10, 45));
140 /// ```
141 pub const fn y_axis(self) -> Self {
142 Self { x: 0, y: self.y }
143 }
144
145 /// Remove the sign from a coordinate
146 ///
147 /// # Examples
148 ///
149 /// ```
150 /// # use embedded_graphics::geometry::Point;
151 /// #
152 /// let point = Point::new(-5, -10);
153 ///
154 /// assert_eq!(point.abs(), Point::new(5, 10));
155 /// ```
156 pub const fn abs(self) -> Self {
157 Point::new(self.x.abs(), self.y.abs())
158 }
159
160 /// Offsets a point by subtracting a size.
161 ///
162 /// This method provides a workaround for the `Sub` trait not being usable in `const` contexts.
163 ///
164 /// # Panics
165 ///
166 /// This function will panic if `width` or `height` are too large to be represented as an `i32`
167 /// and debug assertions are enabled.
168 pub(crate) const fn sub_size(self, other: Size) -> Point {
169 let width = other.width as i32;
170 let height = other.height as i32;
171
172 debug_assert!(width >= 0, "width is too large");
173 debug_assert!(height >= 0, "height is too large");
174
175 Point::new(self.x - width, self.y - height)
176 }
177
178 /// Returns the componentwise minimum of two `Point`s
179 ///
180 /// # Examples
181 ///
182 /// ```rust
183 /// use embedded_graphics::geometry::Point;
184 ///
185 /// let min = Point::new(20, 30).component_min(Point::new(15, 50));
186 ///
187 /// assert_eq!(min, Point::new(15, 30));
188 /// ```
189 pub fn component_min(self, other: Self) -> Self {
190 Self::new(self.x.min(other.x), self.y.min(other.y))
191 }
192
193 /// Returns the componentwise maximum of two `Point`s
194 ///
195 /// # Examples
196 ///
197 /// ```rust
198 /// use embedded_graphics::geometry::Point;
199 ///
200 /// let min = Point::new(20, 30).component_max(Point::new(15, 50));
201 ///
202 /// assert_eq!(min, Point::new(20, 50));
203 /// ```
204 pub fn component_max(self, other: Self) -> Self {
205 Self::new(self.x.max(other.x), self.y.max(other.y))
206 }
207
208 /// Returns the componentwise multiplication of two `Point`s.
209 ///
210 /// ```rust
211 /// use embedded_graphics::geometry::Point;
212 ///
213 /// let result = Point::new(20, 30).component_mul(Point::new(-2, 3));
214 ///
215 /// assert_eq!(result, Point::new(-40, 90));
216 /// ```
217 pub const fn component_mul(self, other: Self) -> Self {
218 Self::new(self.x * other.x, self.y * other.y)
219 }
220
221 /// Returns the componentwise division of two `Points`s.
222 ///
223 /// # Panics
224 ///
225 /// Panics if one of the components of `other` equals zero.
226 ///
227 /// ```rust
228 /// use embedded_graphics::geometry::Point;
229 ///
230 /// let result = Point::new(20, 30).component_div(Point::new(10, -3));
231 ///
232 /// assert_eq!(result, Point::new(2, -10));
233 /// ```
234 pub const fn component_div(self, other: Self) -> Self {
235 Self::new(self.x / other.x, self.y / other.y)
236 }
237}
238
239impl Add for Point {
240 type Output = Point;
241
242 fn add(self, other: Point) -> Point {
243 Point::new(self.x + other.x, self.y + other.y)
244 }
245}
246
247impl Add<Size> for Point {
248 type Output = Point;
249
250 /// Offsets a point by adding a size.
251 ///
252 /// # Panics
253 ///
254 /// This function will panic if `width` or `height` are too large to be represented as an `i32`
255 /// and debug assertions are enabled.
256 fn add(self, other: Size) -> Point {
257 let width: i32 = other.width as i32;
258 let height: i32 = other.height as i32;
259
260 debug_assert!(width >= 0, "width is too large");
261 debug_assert!(height >= 0, "height is too large");
262
263 Point::new(self.x + width, self.y + height)
264 }
265}
266
267impl AddAssign for Point {
268 fn add_assign(&mut self, other: Point) {
269 self.x += other.x;
270 self.y += other.y;
271 }
272}
273
274impl AddAssign<Size> for Point {
275 /// Offsets a point by adding a size.
276 ///
277 /// # Panics
278 ///
279 /// This function will panic if `width` or `height` are too large to be represented as an `i32`
280 /// and debug assertions are enabled.
281 fn add_assign(&mut self, other: Size) {
282 let width: i32 = other.width as i32;
283 let height: i32 = other.height as i32;
284
285 debug_assert!(width >= 0, "width is too large");
286 debug_assert!(height >= 0, "height is too large");
287
288 self.x += width;
289 self.y += height;
290 }
291}
292
293impl Sub for Point {
294 type Output = Point;
295
296 fn sub(self, other: Point) -> Point {
297 Point::new(self.x - other.x, self.y - other.y)
298 }
299}
300
301impl Sub<Size> for Point {
302 type Output = Point;
303
304 /// Offsets a point by subtracting a size.
305 ///
306 /// # Panics
307 ///
308 /// This function will panic if `width` or `height` are too large to be represented as an `i32`
309 /// and debug assertions are enabled.
310 fn sub(self, other: Size) -> Point {
311 self.sub_size(other)
312 }
313}
314
315impl SubAssign for Point {
316 fn sub_assign(&mut self, other: Point) {
317 self.x -= other.x;
318 self.y -= other.y;
319 }
320}
321
322impl SubAssign<Size> for Point {
323 /// Offsets a point by subtracting a size.
324 ///
325 /// # Panics
326 ///
327 /// This function will panic if `width` or `height` are too large to be represented as an `i32`
328 /// and debug assertions are enabled.
329 fn sub_assign(&mut self, other: Size) {
330 let width: i32 = other.width as i32;
331 let height: i32 = other.height as i32;
332
333 debug_assert!(width >= 0, "width is too large");
334 debug_assert!(height >= 0, "height is too large");
335
336 self.x -= width;
337 self.y -= height;
338 }
339}
340
341impl Mul<i32> for Point {
342 type Output = Point;
343
344 fn mul(self, rhs: i32) -> Point {
345 Point::new(self.x * rhs, self.y * rhs)
346 }
347}
348
349impl MulAssign<i32> for Point {
350 fn mul_assign(&mut self, rhs: i32) {
351 self.x *= rhs;
352 self.y *= rhs;
353 }
354}
355
356impl Div<i32> for Point {
357 type Output = Point;
358
359 fn div(self, rhs: i32) -> Point {
360 Point::new(self.x / rhs, self.y / rhs)
361 }
362}
363
364impl DivAssign<i32> for Point {
365 fn div_assign(&mut self, rhs: i32) {
366 self.x /= rhs;
367 self.y /= rhs;
368 }
369}
370
371impl Index<usize> for Point {
372 type Output = i32;
373
374 fn index(&self, idx: usize) -> &i32 {
375 match idx {
376 0 => &self.x,
377 1 => &self.y,
378 _ => panic!("index out of bounds: the len is 2 but the index is {}", idx),
379 }
380 }
381}
382
383impl Neg for Point {
384 type Output = Point;
385
386 fn neg(self) -> Self::Output {
387 Point::new(-self.x, -self.y)
388 }
389}
390
391impl From<(i32, i32)> for Point {
392 fn from(other: (i32, i32)) -> Self {
393 Point::new(x:other.0, y:other.1)
394 }
395}
396
397impl From<[i32; 2]> for Point {
398 fn from(other: [i32; 2]) -> Self {
399 Point::new(x:other[0], y:other[1])
400 }
401}
402
403impl From<&[i32; 2]> for Point {
404 fn from(other: &[i32; 2]) -> Self {
405 Point::new(x:other[0], y:other[1])
406 }
407}
408
409impl From<Point> for (i32, i32) {
410 fn from(other: Point) -> (i32, i32) {
411 (other.x, other.y)
412 }
413}
414
415impl From<Point> for [i32; 2] {
416 fn from(other: Point) -> [i32; 2] {
417 [other.x, other.y]
418 }
419}
420
421impl From<&Point> for (i32, i32) {
422 fn from(other: &Point) -> (i32, i32) {
423 (other.x, other.y)
424 }
425}
426
427impl TryFrom<Point> for (u32, u32) {
428 type Error = core::num::TryFromIntError;
429
430 fn try_from(point: Point) -> Result<Self, Self::Error> {
431 Ok((point.x.try_into()?, point.y.try_into()?))
432 }
433}
434
435impl TryFrom<(u32, u32)> for Point {
436 type Error = core::num::TryFromIntError;
437
438 fn try_from(point: (u32, u32)) -> Result<Self, Self::Error> {
439 let x: i32 = point.0.try_into()?;
440 let y: i32 = point.1.try_into()?;
441
442 Ok(Point::new(x, y))
443 }
444}
445
446impl TryFrom<Point> for [u32; 2] {
447 type Error = core::num::TryFromIntError;
448
449 fn try_from(point: Point) -> Result<Self, Self::Error> {
450 Ok([point.x.try_into()?, point.y.try_into()?])
451 }
452}
453
454impl TryFrom<[u32; 2]> for Point {
455 type Error = core::num::TryFromIntError;
456
457 fn try_from(point: [u32; 2]) -> Result<Self, Self::Error> {
458 let x: i32 = point[0].try_into()?;
459 let y: i32 = point[1].try_into()?;
460
461 Ok(Point::new(x, y))
462 }
463}
464
465impl TryFrom<&[u32; 2]> for Point {
466 type Error = core::num::TryFromIntError;
467
468 fn try_from(point: &[u32; 2]) -> Result<Self, Self::Error> {
469 let x: i32 = point[0].try_into()?;
470 let y: i32 = point[1].try_into()?;
471
472 Ok(Point::new(x, y))
473 }
474}
475
476impl fmt::Display for Point {
477 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
478 write!(f, "{}, {}", self.x, self.y)
479 }
480}
481
482#[cfg(feature = "nalgebra_support")]
483use nalgebra::{base::Scalar, Vector2};
484
485#[cfg(feature = "nalgebra_support")]
486impl<N> From<Vector2<N>> for Point
487where
488 N: Into<i32> + Scalar + Copy,
489{
490 fn from(other: Vector2<N>) -> Self {
491 Self::new(other[0].into(), other[1].into())
492 }
493}
494
495#[cfg(feature = "nalgebra_support")]
496impl<N> From<&Vector2<N>> for Point
497where
498 N: Into<i32> + Scalar + Copy,
499{
500 fn from(other: &Vector2<N>) -> Self {
501 Self::new(other[0].into(), other[1].into())
502 }
503}
504
505#[cfg(test)]
506mod tests {
507 use super::*;
508
509 use core::fmt::Write;
510
511 #[test]
512 fn convert_positive_to_u32_tuple() {
513 let p = Point::new(10, 20);
514
515 let tuple: (u32, u32) = p.try_into().unwrap();
516 let array: [u32; 2] = p.try_into().unwrap();
517
518 assert_eq!(tuple, (10, 20));
519 assert_eq!(array, [10, 20]);
520 }
521
522 #[test]
523 fn convert_i32_max_to_u32_tuple() {
524 let p = Point::new(i32::max_value(), i32::max_value());
525
526 let tuple: (u32, u32) = p.try_into().unwrap();
527 let array: [u32; 2] = p.try_into().unwrap();
528
529 // Literal value taken from https://doc.rust-lang.org/std/primitive.i32.html#method.max_value
530 assert_eq!(tuple, (2147483647, 2147483647));
531 assert_eq!(array, [2147483647, 2147483647]);
532 }
533
534 #[test]
535 fn convert_negative_to_u32_tuple() {
536 let p = Point::new(-50, -10);
537
538 let tuple: Result<(u32, u32), _> = p.try_into();
539 let array: Result<[u32; 2], _> = p.try_into();
540
541 assert!(tuple.is_err());
542 assert!(array.is_err());
543 }
544
545 #[test]
546 fn convert_i32_min_to_u32_tuple() {
547 let p = Point::new(i32::min_value(), i32::min_value());
548
549 let tuple: Result<(u32, u32), _> = p.try_into();
550 let array: Result<[u32; 2], _> = p.try_into();
551
552 assert!(tuple.is_err());
553 assert!(array.is_err());
554 }
555
556 #[test]
557 fn points_can_be_added() {
558 let mut left = Point::new(10, 20);
559 let right = Point::new(30, 40);
560
561 assert_eq!(left + right, Point::new(40, 60));
562
563 left += right;
564 assert_eq!(left, Point::new(40, 60));
565 }
566
567 #[test]
568 fn point_and_size_can_be_added() {
569 let mut left = Point::new(11, 21);
570 let right = Size::new(30, 40);
571
572 assert_eq!(left + right, Point::new(41, 61));
573
574 left += right;
575 assert_eq!(left, Point::new(41, 61));
576 }
577
578 #[test]
579 fn points_can_be_subtracted() {
580 let mut left = Point::new(30, 50);
581 let right = Point::new(10, 20);
582
583 assert_eq!(left - right, Point::new(20, 30));
584
585 left -= right;
586 assert_eq!(left, Point::new(20, 30));
587 }
588
589 #[test]
590 fn point_and_size_can_be_subtracted() {
591 let mut left = Point::new(30, 40);
592 let right = Size::new(11, 22);
593
594 assert_eq!(left - right, Point::new(19, 18));
595
596 left -= right;
597 assert_eq!(left, Point::new(19, 18));
598 }
599
600 #[test]
601 fn points_can_be_negative_after_subtraction() {
602 let left = Point::new(10, 20);
603 let right = Point::new(30, 50);
604
605 assert_eq!(left - right, Point::new(-20, -30));
606
607 let left = Point::new(10, 20);
608 let right = Size::new(31, 42);
609
610 assert_eq!(left - right, Point::new(-21, -22));
611 }
612
613 #[test]
614 fn points_can_be_multiplied_by_scalar() {
615 let p = Point::new(1, 2);
616 assert_eq!(p * 3, Point::new(3, 6));
617
618 let mut p = Point::new(3, 4);
619 p *= -5;
620 assert_eq!(p, Point::new(-15, -20));
621 }
622
623 #[test]
624 fn points_can_be_divided_by_scalar() {
625 let p = Point::new(10, 20);
626 assert_eq!(p / 2, Point::new(5, 10));
627
628 let mut p = Point::new(-10, 10);
629 p /= -5;
630 assert_eq!(p, Point::new(2, -2));
631 }
632
633 #[test]
634 #[should_panic(expected = "width is too large")]
635 #[cfg(debug_assertions)]
636 fn too_large_width_can_not_be_added() {
637 let p = Point::zero();
638 let _ = p + Size::new(u32::max_value(), 0);
639 }
640
641 #[test]
642 #[should_panic(expected = "width is too large")]
643 #[cfg(debug_assertions)]
644 fn too_large_width_can_not_be_add_assigned() {
645 let mut p = Point::zero();
646 p += Size::new(u32::max_value(), 0);
647 }
648
649 #[test]
650 #[should_panic(expected = "height is too large")]
651 #[cfg(debug_assertions)]
652 fn too_large_height_can_not_be_added() {
653 let p = Point::zero();
654 let _ = p + Size::new(0, 0x80000000);
655 }
656
657 #[test]
658 #[should_panic(expected = "height is too large")]
659 #[cfg(debug_assertions)]
660 fn too_large_height_can_not_be_add_assigned() {
661 let mut p = Point::zero();
662 p += Size::new(0, 0x80000000);
663 }
664
665 #[test]
666 #[should_panic(expected = "width is too large")]
667 #[cfg(debug_assertions)]
668 fn too_large_width_can_not_be_subtracted() {
669 let p = Point::zero();
670 let _ = p - Size::new(u32::max_value(), 0);
671 }
672
673 #[test]
674 #[should_panic(expected = "width is too large")]
675 #[cfg(debug_assertions)]
676 fn too_large_width_can_not_be_sub_assigned() {
677 let mut p = Point::zero();
678 p -= Size::new(u32::max_value(), 0);
679 }
680
681 #[test]
682 #[should_panic(expected = "height is too large")]
683 #[cfg(debug_assertions)]
684 fn too_large_height_can_not_be_subtracted() {
685 let p = Point::zero();
686 let _ = p - Size::new(0, 0x80000000);
687 }
688
689 #[test]
690 #[should_panic(expected = "height is too large")]
691 #[cfg(debug_assertions)]
692 fn too_large_height_can_not_be_sub_assigned() {
693 let mut p = Point::zero();
694 p -= Size::new(0, 0x80000000);
695 }
696
697 #[test]
698 fn from_tuple() {
699 assert_eq!(Point::from((20i32, 30i32)), Point::new(20, 30));
700 assert_eq!(Point::from((20i32, 30i32)), Point::new(20, 30));
701 }
702
703 #[test]
704 fn from_array() {
705 assert_eq!(Point::from([20i32, 30i32]), Point::new(20, 30));
706 assert_eq!(Point::from([20i32, 30i32]), Point::new(20, 30));
707 }
708
709 #[test]
710 fn from_array_ref() {
711 assert_eq!(Point::from(&[20i32, 30i32]), Point::new(20, 30));
712 assert_eq!(Point::from(&[20i32, 30i32]), Point::new(20, 30));
713 }
714
715 #[test]
716 fn neg() {
717 assert_eq!(-Point::new(10, 20), Point::new(-10, -20));
718 assert_eq!(-Point::new(-40, -50), Point::new(40, 50));
719 }
720
721 #[test]
722 fn index() {
723 let point = Point::new(12, -34);
724
725 assert_eq!(point.x, point[0]);
726 assert_eq!(point.y, point[1]);
727 }
728
729 #[test]
730 #[should_panic]
731 fn index_out_of_bounds() {
732 let point = Point::new(1, 2);
733 let _ = point[2];
734 }
735
736 #[test]
737 #[cfg(feature = "nalgebra_support")]
738 fn nalgebra_support() {
739 let left = nalgebra::Vector2::new(30, 40);
740 let right = nalgebra::Vector2::new(10, 20);
741
742 assert_eq!(Point::from(left - right), Point::new(20, 20));
743 }
744
745 #[test]
746 #[cfg(feature = "nalgebra_support")]
747 fn convert_ref() {
748 let left = nalgebra::Vector2::new(30, 40);
749 let right = nalgebra::Vector2::new(10, 20);
750
751 let c = left - right;
752
753 assert_eq!(Point::from(&c), Point::new(20, 20));
754 }
755
756 #[test]
757 fn component_min_max() {
758 let a = Point::new(20, 30);
759 let b = Point::new(15, 50);
760
761 assert_eq!(a.component_min(b), Point::new(15, 30));
762 assert_eq!(a.component_max(b), Point::new(20, 50));
763 }
764
765 #[test]
766 fn display() {
767 let mut buffer = arrayvec::ArrayString::<32>::new();
768 write!(buffer, "{}", Point::new(123, -456)).unwrap();
769
770 assert_eq!(&buffer, "123, -456");
771 }
772}
773