diff --git a/ratatui-core/src/layout/position.rs b/ratatui-core/src/layout/position.rs index 63893389..d005abf6 100644 --- a/ratatui-core/src/layout/position.rs +++ b/ratatui-core/src/layout/position.rs @@ -1,7 +1,8 @@ #![warn(missing_docs)] use core::fmt; +use core::ops::{Add, AddAssign, Sub, SubAssign}; -use crate::layout::Rect; +use crate::layout::{Offset, Rect}; /// Position in the terminal coordinate system. /// @@ -23,10 +24,18 @@ use crate::layout::Rect; /// - [`from(Rect)`](Self::from) - Create from [`Rect`] (uses top-left corner) /// - [`into((u16, u16))`] - Convert to `(u16, u16)` tuple /// +/// # Movement +/// +/// - [`offset`](Self::offset) - Move by an [`Offset`] +/// - [`Add`](core::ops::Add) and [`Sub`](core::ops::Sub) - Shift by offsets with +/// clamping +/// - [`AddAssign`](core::ops::AddAssign) and [`SubAssign`](core::ops::SubAssign) - +/// In-place shifting +/// /// # Examples /// /// ``` -/// use ratatui_core::layout::{Position, Rect}; +/// use ratatui_core::layout::{Offset, Position, Rect}; /// /// // the following are all equivalent /// let position = Position { x: 1, y: 2 }; @@ -36,6 +45,10 @@ use crate::layout::Rect; /// /// // position can be converted back into the components when needed /// let (x, y) = position.into(); +/// +/// // movement by offsets +/// let position = Position::new(5, 5) + Offset::new(2, -3); +/// assert_eq!(position, Position::new(7, 2)); /// ``` /// /// For comprehensive layout documentation and examples, see the [`layout`](crate::layout) module. @@ -69,6 +82,15 @@ impl Position { pub const fn new(x: u16, y: u16) -> Self { Self { x, y } } + + /// Moves the position by the given offset. + /// + /// Positive offsets move right and down, negative offsets move left and up. Values that would + /// move the position outside the `u16` range are clamped to the nearest edge. + #[must_use = "method returns the modified value"] + pub fn offset(self, offset: Offset) -> Self { + self + offset + } } impl From<(u16, u16)> for Position { @@ -95,6 +117,68 @@ impl fmt::Display for Position { } } +impl Add for Position { + type Output = Self; + + /// Moves the position by the given offset. + /// + /// Values that would move the position outside the `u16` range are clamped to the nearest + /// edge. + fn add(self, offset: Offset) -> Self { + let max = i32::from(u16::MAX); + let x = i32::from(self.x).saturating_add(offset.x).clamp(0, max) as u16; + let y = i32::from(self.y).saturating_add(offset.y).clamp(0, max) as u16; + Self { x, y } + } +} + +impl Add for Offset { + type Output = Position; + + /// Moves the position by the given offset. + /// + /// Values that would move the position outside the `u16` range are clamped to the nearest + /// edge. + fn add(self, position: Position) -> Position { + position + self + } +} + +impl Sub for Position { + type Output = Self; + + /// Moves the position by the inverse of the given offset. + /// + /// Values that would move the position outside the `u16` range are clamped to the nearest + /// edge. + fn sub(self, offset: Offset) -> Self { + let max = i32::from(u16::MAX); + let x = i32::from(self.x).saturating_sub(offset.x).clamp(0, max) as u16; + let y = i32::from(self.y).saturating_sub(offset.y).clamp(0, max) as u16; + Self { x, y } + } +} + +impl AddAssign for Position { + /// Moves the position in place by the given offset. + /// + /// Values that would move the position outside the `u16` range are clamped to the nearest + /// edge. + fn add_assign(&mut self, offset: Offset) { + *self = *self + offset; + } +} + +impl SubAssign for Position { + /// Moves the position in place by the inverse of the given offset. + /// + /// Values that would move the position outside the `u16` range are clamped to the nearest + /// edge. + fn sub_assign(&mut self, offset: Offset) { + *self = *self - offset; + } +} + #[cfg(test)] mod tests { use alloc::string::ToString; @@ -104,15 +188,15 @@ mod tests { #[test] fn new() { let position = Position::new(1, 2); - assert_eq!(position.x, 1); - assert_eq!(position.y, 2); + + assert_eq!(position, Position { x: 1, y: 2 }); } #[test] fn from_tuple() { let position = Position::from((1, 2)); - assert_eq!(position.x, 1); - assert_eq!(position.y, 2); + + assert_eq!(position, Position { x: 1, y: 2 }); } #[test] @@ -127,8 +211,8 @@ mod tests { fn from_rect() { let rect = Rect::new(1, 2, 3, 4); let position = Position::from(rect); - assert_eq!(position.x, 1); - assert_eq!(position.y, 2); + + assert_eq!(position, Position { x: 1, y: 2 }); } #[test] @@ -136,4 +220,34 @@ mod tests { let position = Position::new(1, 2); assert_eq!(position.to_string(), "(1, 2)"); } + + #[test] + fn offset_moves_position() { + let position = Position::new(2, 3).offset(Offset::new(5, 7)); + + assert_eq!(position, Position::new(7, 10)); + } + + #[test] + fn offset_clamps_to_bounds() { + let position = Position::new(1, 1).offset(Offset::MAX); + + assert_eq!(position, Position::MAX); + } + + #[test] + fn add_and_subtract_offset() { + let position = Position::new(10, 10) + Offset::new(-3, 4) - Offset::new(5, 20); + + assert_eq!(position, Position::new(2, 0)); + } + + #[test] + fn add_assign_and_sub_assign_offset() { + let mut position = Position::new(5, 5); + position += Offset::new(2, 3); + position -= Offset::new(10, 1); + + assert_eq!(position, Position::new(0, 7)); + } }