rust: continue refactoring the error system.

- deal with null()|null_mut() being returned from
  functions, previously ignored.
- new macros: error_ptr & error_str to deal with
  functions returning *mut T & *const c_char into
  NcResult<&mut T> or NcResult<String>, respectively.

rust/src/error.rs

@@ -25,14 +25,14 @@ pub const NCRESULT_MAX: i32 = i32::MAX;
 /// The error type for the Rust methods API.
 #[derive(Debug, Clone, Default)]
 pub struct NcError {
-    /// [NcIntError].
+    /// [NcIntResult].
     pub int: i32,
     pub msg: String,
 }
 
 impl fmt::Display for NcError {
     fn fmt(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> {
-        write!(f, "NcIntError: {}. {}", self.int, self.msg)
+        write!(f, "NcError {}: {}", self.int, self.msg)
     }
 }
 

rust/src/macros.rs

@@ -1,4 +1,10 @@
 //! Macros
+//!
+//! NOTE: Use full paths everywhere. Don't assume anything will be in scope.
+
+#[allow(unused_imports)]
+// enjoy briefer doc comments
+use crate::{NcError, NCRESULT_ERR, NCRESULT_OK};
 
 // General Utility Macros ------------------------------------------------------
 
@@ -10,11 +16,24 @@ macro_rules! sleep {
     };
 }
 
-/// Renders the [Notcurses][crate::Notcurses] object, then sleeps for `$ms`
+/// Renders the `$nc` [Notcurses][crate::Notcurses] object,
-/// milliseconds and returns the result of [notcurses_render][crate::notcurses_render].
+/// then sleeps for `$ms` milliseconds.
 #[macro_export]
 macro_rules! rsleep {
     ($nc:expr, $ms:expr) => {{
+        // Rust style, with methods & NcResult
+        crate::$nc.render();
+        std::thread::sleep(std::time::Duration::from_millis($ms));
+    }};
+}
+
+/// Renders the `$nc` [Notcurses][crate::Notcurses] object,
+/// then sleeps for `$ms` milliseconds and returns the result of
+/// [notcurses_render][crate::notcurses_render].
+#[macro_export]
+macro_rules! rsleep_c {
+    ($nc:expr, $ms:expr) => {{
+        // C style, with functions & NcIntResult
         let mut res: crate::NcIntResult = 0;
         unsafe {
             res = crate::notcurses_render($nc);
@@ -43,13 +62,17 @@ macro_rules! printf {
     };
 }
 
-/// Returns Ok(`$ok`) if `$res` >= [NCRESULT_OK][crate::NCRESULT_OK],
+// Error Wrappers Macros -------------------------------------------------------
-/// otherwise returns
+
-/// Err([NcError][crate::NcError]::[new][crate::NcError#method.new](`$res`, `$msg`)).
+/// Returns an Ok(<`$ok`>),
+/// or an Err([NcError]) if `$res` < [NCRESULT_OK].
+///
+/// In other words:
+/// Returns Ok(`$ok`) if `$res` >= [NCRESULT_OK], otherwise returns
+/// Err([NcError]::[new][NcError#method.new](`$res`, `$msg`)).
 ///
 /// `$ok` & `$msg` are optional. By default they will be the unit
 /// type `()`, and an empty `&str` `""`, respectively.
-///
 #[macro_export]
 macro_rules! error {
     ($res:expr, $ok:expr, $msg:expr) => {
@@ -66,3 +89,47 @@ macro_rules! error {
         error![$res, (), ""];
     };
 }
+
+/// Returns an Ok(&mut T) from a `*mut T` pointer,
+/// or an Err([NcError]) if the pointer is null.
+///
+/// In other words:
+/// Returns Ok(&mut *`$ptr`) if `$ptr` != `null()`, otherwise returns
+/// Err([NcError]]::[new][NcError#method.new]([NCRESULT_ERR], `$msg`)).
+///
+/// `$msg` is optional. By default it will be an empty `&str` `""`.
+#[macro_export]
+macro_rules! error_ptr {
+    ($ptr:expr, $msg:expr) => {
+        if $ptr != core::ptr::null_mut() {
+            return Ok(unsafe { &mut *$ptr });
+        } else {
+            return Err(crate::NcError::with_msg(crate::NCRESULT_ERR, $msg));
+        }
+    };
+    ($ptr:expr) => {
+        error![$ptr, (), ""];
+    };
+}
+
+/// Returns an Ok([`String`]) from a `*const` pointer to a C string,
+/// or an Err([NcError]) if the pointer is null.
+///
+/// In other words:
+/// Returns Ok((&*`$str`).to_string()) if `$str` != `null()`, otherwise returns
+/// Err([NcError]]::[new][NcError#method.new]([NCRESULT_ERR], `$msg`)).
+///
+/// `$msg` is optional. By default it will be an empty `&str` `""`.
+#[macro_export]
+macro_rules! error_str {
+    ($str:expr, $msg:expr) => {
+        if $str != core::ptr::null_mut() {
+            return Ok(unsafe { (&*$str).to_string() });
+        } else {
+            return Err(crate::NcError::with_msg(crate::NCRESULT_ERR, $msg));
+        }
+    };
+    ($str:expr) => {
+        error![$str, (), ""];
+    };
+}

rust/src/notcurses/methods.rs

@@ -398,8 +398,7 @@ impl Notcurses {
     /// Enable the mouse in "button-event tracking" mode with focus detection
     /// and UTF8-style extended coordinates.
     ///
-    /// On success, [NCRESULT_OK] is returned, and mouse events will be
+    /// On success, mouse events will be published to [getc()][Notcurses#method.getc].
-    /// published to [getc()][Notcurses#method.getc].
     ///
     /// *C style function: [notcurses_mouse_enable()][crate::notcurses_mouse_enable].*
     pub fn mouse_enable(&mut self) -> NcResult<()> {