From 548ca72bf41c3d4909e2b4bc29e70ff5e6f761f1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?joseLu=C3=ADs?= <joseluis@andamira.net>
Date: Wed, 14 Jul 2021 09:49:50 +0200
Subject: [PATCH] [rust] add `NcPlane` methods

- reimplement the static function `ncplane_moverel`.
- new methods `move_rel`, `cursor_move_rel`, `putln`.
- rename `home` to `cursor_home` and deprecate.
---
 rust/src/plane/methods.rs       | 43 +++++++++++++++++++++++++++------
 rust/src/plane/mod.rs           |  1 +
 rust/src/plane/reimplemented.rs | 20 +++++++++++++--
 3 files changed, 55 insertions(+), 9 deletions(-)

diff --git a/rust/src/plane/methods.rs b/rust/src/plane/methods.rs
index c9a481779..bf33654f7 100644
--- a/rust/src/plane/methods.rs
+++ b/rust/src/plane/methods.rs
@@ -807,7 +807,8 @@ impl NcPlane {
     /// cursor to the beginning of the next row.
     ///
     /// Advances the cursor by some positive number of columns (though not
-    /// beyond the end of the plane); this number is returned on success.
+    /// beyond the end of the plane); this number will be returned on success,
+    /// after calling [`putln`][NcPlane#method.putln].
     ///
     /// On error, a non-positive number is returned, indicating the number of
     /// columns which were written before the error.
@@ -815,9 +816,17 @@ impl NcPlane {
     /// *(No equivalent C style function)*
     pub fn putstrln(&mut self, string: &str) -> NcResult<NcDim> {
         let cols = self.putstr(string)?;
+        self.putln()?;
+        Ok(cols)
+    }
+
+    /// Moves the cursor to the beginning of the next row.
+    ///
+    /// *(No equivalent C style function)*
+    pub fn putln(&mut self) -> NcResult<()> {
         let (y, _x) = self.cursor_yx();
         self.cursor_move_yx(y + 1, 0)?;
-        Ok(cols)
+        Ok(())
     }
 
     /// Same as [`putstr_yx()`][NcPlane#method.putstr_yx]
@@ -964,15 +973,17 @@ impl NcPlane {
         ]
     }
 
-    /// Moves this `NcPlane` relative to its current position.
+    /// Moves this `NcPlane` relative to its current location.
+    ///
+    /// Negative values move up and left, respectively.
+    /// Pass 0 to hold an axis constant.
     ///
     /// It is an error to attempt to move the standard plane.
     ///
-    /// *(No equivalent C style function)*
+    /// *C style function: [ncplane_moverel()][crate::ncplane_moverel].*
     pub fn move_rel(&mut self, rows: NcOffset, cols: NcOffset) -> NcResult<()> {
-        let (y, x) = self.yx();
         error![
-            unsafe { crate::ncplane_move_yx(self, y + rows, x + cols) },
+            crate::ncplane_moverel(self, rows, cols),
             &format!("NcPlane.move_rel({}, {})", rows, cols)
         ]
     }
@@ -1190,12 +1201,18 @@ impl NcPlane {
     /// Moves the cursor to 0, 0.
     ///
     /// *C style function: [ncplane_home()][crate::ncplane_home].*
-    pub fn home(&mut self) {
+    pub fn cursor_home(&mut self) {
         unsafe {
             crate::ncplane_home(self);
         }
     }
 
+    #[doc(hidden)]
+    #[deprecated]
+    pub fn home(&mut self) {
+        self.cursor_home()
+    }
+
     /// Returns the current position of the cursor within this `NcPlane`.
     ///
     /// *C style function: [ncplane_cursor_yx()][crate::ncplane_cursor_yx].*
@@ -1278,6 +1295,18 @@ impl NcPlane {
         let (y, x) = self.cursor_yx();
         self.cursor_move_yx(y, (x as NcOffset + cols) as NcDim)
     }
+
+    /// Moves the cursor relatively, the number of rows and columns specified
+    /// (forward or backwards).
+    ///
+    /// It will error if the target row or column exceeds the plane dimensions.
+    ///
+    /// *(No equivalent C style function)*
+    pub fn cursor_move_rel(&mut self, rows: NcOffset, cols: NcOffset) -> NcResult<()> {
+        self.cursor_move_rows(rows)?;
+        self.cursor_move_cols(cols)?;
+        Ok(())
+    }
 }
 
 // -----------------------------------------------------------------------------
diff --git a/rust/src/plane/mod.rs b/rust/src/plane/mod.rs
index 01e4ab00c..486fbe4d2 100644
--- a/rust/src/plane/mod.rs
+++ b/rust/src/plane/mod.rs
@@ -150,6 +150,7 @@
 //W+ ncplane_gradient_sized
 //W+ ncplane_halign
 // + ncplane_hline
+//W  ncplane_moverel
 //W+ ncplane_perimeter
 //W+ ncplane_perimeter_double
 //W+ ncplane_perimeter_rounded
diff --git a/rust/src/plane/reimplemented.rs b/rust/src/plane/reimplemented.rs
index 9b5fb1b6e..476a07b2a 100644
--- a/rust/src/plane/reimplemented.rs
+++ b/rust/src/plane/reimplemented.rs
@@ -4,7 +4,7 @@ use core::ptr::null_mut;
 
 use crate::{
     cstring, nccell_release, NcAlign, NcAlphaBits, NcBoxMask, NcCell, NcChannel, NcChannels,
-    NcComponent, NcDim, NcIntResult, NcPlane, NcRgb, NcStyle, NCRESULT_ERR, NCRESULT_OK,
+    NcComponent, NcDim, NcIntResult, NcOffset, NcPlane, NcRgb, NcStyle, NCRESULT_ERR, NCRESULT_OK,
 };
 
 // Alpha -----------------------------------------------------------------------
@@ -247,7 +247,23 @@ pub fn ncplane_putnstr(plane: &mut NcPlane, size: u32, gclustarr: &[u8]) -> NcIn
     unsafe { crate::ncplane_putnstr_yx(plane, -1, -1, size.into(), cstring![gclustarr]) }
 }
 
-// size & alignment ------------------------------------------------------------
+// movement, size & alignment --------------------------------------------------
+
+/// Moves this `NcPlane` relative to its current location.
+///
+/// Negative values move up and left, respectively.
+/// Pass 0 to hold an axis constant.
+///
+/// It is an error to attempt to move the standard plane.
+///
+/// *C style function: [ncplane_moverel()][crate::ncplane_moverel].*
+pub fn ncplane_moverel(plane: &mut NcPlane, rows: NcOffset, cols: NcOffset) -> NcIntResult {
+    let (mut orig_y, mut orig_x) = (0, 0);
+    unsafe {
+        crate::ncplane_dim_yx(plane, &mut orig_y, &mut orig_x);
+        crate::ncplane_move_yx(plane, orig_y + rows, orig_x + cols)
+    }
+}
 
 /// Gets the columns of the [NcPlane].
 ///