From 758d06af108fd8ae505e346c37f379f58118da1f Mon Sep 17 00:00:00 2001
From: Timon <timonpost@hotmail.nl>
Date: Thu, 30 Jun 2022 20:45:17 +0200
Subject: [PATCH] Make some commands 1-based and document that 0 is defaulted
 to 1.

---
 src/cursor.rs | 31 +++++++++++++++++++------------
 1 file changed, 19 insertions(+), 12 deletions(-)

diff --git a/src/cursor.rs b/src/cursor.rs
index a6381737..a777ec9c 100644
--- a/src/cursor.rs
+++ b/src/cursor.rs
@@ -55,7 +55,6 @@ pub(crate) mod sys;
 /// A command that moves the terminal cursor to the given position (column, row).
 ///
 /// # Notes
-/// * This command is 0 based, meaning 0 is 1.
 /// * Top left cell is represented as `0,0`.
 /// * Commands must be executed/queued for execution otherwise they do nothing.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -76,7 +75,8 @@ impl Command for MoveTo {
 /// and moves it to the first column.
 ///
 /// # Notes
-/// * This command is 0 based, meaning 0 is 1.
+/// * This command is 1 based, meaning `MoveToNextLine(1)` moves to the next line.
+/// * Most terminals default 0 argument to 1.
 /// * Commands must be executed/queued for execution otherwise they do nothing.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct MoveToNextLine(pub u16);
@@ -100,7 +100,8 @@ impl Command for MoveToNextLine {
 /// and moves it to the first column.
 ///
 /// # Notes
-/// * This command is 0 based, meaning 0 is 1.
+/// * This command is 1 based, meaning `MoveToPreviousLine(1)` moves to the previous line.
+/// * Most terminals default 0 argument to 1.
 /// * Commands must be executed/queued for execution otherwise they do nothing.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct MoveToPreviousLine(pub u16);
@@ -123,7 +124,8 @@ impl Command for MoveToPreviousLine {
 /// A command that moves the terminal cursor to the given column on the current row.
 ///
 /// # Notes
-/// * This command is 0 based, meaning 0 is 1.
+/// * This command is 0 based, meaning 0 is the leftmost column.
+/// * Most terminals default 0 argument to 1.
 /// * Commands must be executed/queued for execution otherwise they do nothing.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct MoveToColumn(pub u16);
@@ -143,7 +145,8 @@ impl Command for MoveToColumn {
 /// A command that moves the terminal cursor to the given row on the current column.
 ///
 /// # Notes
-/// * This command is 0 based, meaning 0 is 1.
+/// * This command is 0 based, meaning 0 is the topmost row.
+/// * Most terminals default 0 argument to 1.
 /// * Commands must be executed/queued for execution otherwise they do nothing.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct MoveToRow(pub u16);
@@ -163,14 +166,15 @@ impl Command for MoveToRow {
 /// A command that moves the terminal cursor a given number of rows up.
 ///
 /// # Notes
-/// * This command is 0 based, meaning 0 is 1.
+/// * This command is 1 based, meaning `MoveUp(1) moves the cursor up one cell.
+/// * Most terminals default 0 argument to 1.
 /// * Commands must be executed/queued for execution otherwise they do nothing.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct MoveUp(pub u16);
 
 impl Command for MoveUp {
     fn write_ansi(&self, f: &mut impl fmt::Write) -> fmt::Result {
-        write!(f, csi!("{}A"), self.0 + 1)?;
+        write!(f, csi!("{}A"), self.0)?;
         Ok(())
     }
 
@@ -183,7 +187,8 @@ impl Command for MoveUp {
 /// A command that moves the terminal cursor a given number of columns to the right.
 ///
 /// # Notes
-/// * This command is 0 based, meaning 0 is 1.
+/// * This command is 1 based, meaning `MoveRight(1) moves the cursor right one cell.
+/// * Most terminals default 0 argument to 1.
 /// * Commands must be executed/queued for execution otherwise they do nothing.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct MoveRight(pub u16);
@@ -203,14 +208,15 @@ impl Command for MoveRight {
 /// A command that moves the terminal cursor a given number of rows down.
 ///
 /// # Notes
-/// * This command is 0 based, meaning 0 is 1.
+/// * This command is 1 based, meaning `MoveDown(1) moves the cursor down one cell.
+/// * Most terminals default 0 argument to 1.
 /// * Commands must be executed/queued for execution otherwise they do nothing.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct MoveDown(pub u16);
 
 impl Command for MoveDown {
     fn write_ansi(&self, f: &mut impl fmt::Write) -> fmt::Result {
-        write!(f, csi!("{}B"), self.0 + 1)?;
+        write!(f, csi!("{}B"), self.0)?;
         Ok(())
     }
 
@@ -223,14 +229,15 @@ impl Command for MoveDown {
 /// A command that moves the terminal cursor a given number of columns to the left.
 ///
 /// # Notes
-/// * This command is 0 based, meaning 0 is 1.
+/// * This command is 1 based, meaning `MoveLeft(1) moves the cursor left one cell.
+/// * Most terminals default 0 argument to 1.
 /// * Commands must be executed/queued for execution otherwise they do nothing.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct MoveLeft(pub u16);
 
 impl Command for MoveLeft {
     fn write_ansi(&self, f: &mut impl fmt::Write) -> fmt::Result {
-        write!(f, csi!("{}D"), self.0 + 1)?;
+        write!(f, csi!("{}D"), self.0)?;
         Ok(())
     }