diff --git a/rust/src/error.rs b/rust/src/error.rs index cede5a57c..c6290d706 100644 --- a/rust/src/error.rs +++ b/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) } } diff --git a/rust/src/macros.rs b/rust/src/macros.rs index 16fff0b94..3e0877362 100644 --- a/rust/src/macros.rs +++ b/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` -/// milliseconds and returns the result of [notcurses_render][crate::notcurses_render]. +/// Renders the `$nc` [Notcurses][crate::Notcurses] object, +/// 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], -/// otherwise returns -/// Err([NcError][crate::NcError]::[new][crate::NcError#method.new](`$res`, `$msg`)). +// Error Wrappers Macros ------------------------------------------------------- + +/// 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, (), ""]; + }; +} diff --git a/rust/src/notcurses/methods.rs b/rust/src/notcurses/methods.rs index a7e83b3c7..1d282cb7e 100644 --- a/rust/src/notcurses/methods.rs +++ b/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 - /// published to [getc()][Notcurses#method.getc]. + /// On success, mouse events will be published to [getc()][Notcurses#method.getc]. /// /// *C style function: [notcurses_mouse_enable()][crate::notcurses_mouse_enable].* pub fn mouse_enable(&mut self) -> NcResult<()> {