rust: add methods for NcResizeCb & NcPalette.

- fix intra-doc links.
- refactor palette module.

rust/src/macros.rs

@@ -2,7 +2,7 @@
 
 // General Utility Macros ------------------------------------------------------
 
-/// Sleeps for $ms milliseconds.
+/// Sleeps for `$ms` milliseconds.
 #[macro_export]
 macro_rules! sleep {
     ($ms:expr) => {
@@ -10,7 +10,7 @@ macro_rules! sleep {
     };
 }
 
-/// Renders the [Notcurses][crate::Notcurses] object, then sleeps for $ms
+/// Renders the [Notcurses][crate::Notcurses] object, then sleeps for `$ms`
 /// milliseconds and returns the result of [notcurses_render][crate::notcurses_render].
 #[macro_export]
 macro_rules! rsleep {

rust/src/palette/methods.rs

@@ -0,0 +1,54 @@
+//! `NcPalette` methods and associated functions.
+
+use crate::{NcChannel, NcColor, NcPalette, NcPaletteIndex, NcResult, NcRgb, Notcurses};
+
+impl NcPalette {
+    /// New NcPalette.
+    ///
+    /// *C style function: [palette256_new()][crate::palette256_new].*
+    pub fn new<'a>(nc: &mut Notcurses) -> &'a mut Self {
+        unsafe { &mut *crate::palette256_new(nc) }
+    }
+
+    /// Frees this NcPalette.
+    ///
+    /// *C style function: [palette256_free()][crate::palette256_free].*
+    pub fn free(&mut self) {
+        unsafe {
+            crate::palette256_free(self);
+        }
+    }
+
+    /// Attempts to configure the terminal with this NcPalette.
+    ///
+    /// *C style function: [palette256_use()][crate::palette256_use].*
+    pub fn r#use(&self, nc: &mut Notcurses) -> NcResult {
+        unsafe { crate::palette256_use(nc, self) }
+    }
+
+    /// Returns the [NcColor] RGB components from the [NcChannel] in this NcPalette.
+    ///
+    /// *C style function: [palette256_get_rgb()][crate::palette256_get_rgb].*
+    pub fn get_rgb8(&self, index: NcPaletteIndex) -> (NcColor, NcColor, NcColor) {
+        let (mut r, mut g, mut b) = (0, 0, 0);
+        crate::channel_rgb8(self.chans[index as usize], &mut r, &mut g, &mut b);
+        (r, g, b)
+    }
+
+    /// Extracts the [NcColor] RGB components from an [NcChannel] entry inside
+    /// this NcPalette, and returns the NcChannel.
+    ///
+    /// *C style function: [palette256_get_rgb()][crate::palette256_get_rgb].*
+    pub fn get_rgb(&self, index: NcPaletteIndex) -> NcChannel {
+        let (mut r, mut g, mut b) = (0, 0, 0);
+        crate::channel_rgb8(self.chans[index as usize], &mut r, &mut g, &mut b)
+    }
+
+    /// Sets the [NcRgb] value of the [NcChannel][crate::NcChannel] entry
+    /// inside this NcPalette.
+    ///
+    /// *C style function: [palette256_set()][crate::palette256_set].*
+    pub fn set(&mut self, index: NcPaletteIndex, rgb: NcRgb) {
+        crate::channel_set(&mut self.chans[index as usize], rgb);
+    }
+}

rust/src/palette/mod.rs

@@ -6,22 +6,26 @@
 //
 // functions already exported by bindgen : 3
 // -----------------------------------------
-// (#) unit tests: 0 / 3
+// (#) test: 0
+// (W) wrap: 3 / 0
 // -----------------------------------------
-//  palette256_free
-//  palette256_new
-//  palette256_use
+//W  palette256_free
+//W  palette256_new
+//W  palette256_use
 //
 // functions manually reimplemented: 3
 // -----------------------------------------
-// (+) implement : 3 / 0
-// (#) unit tests: 0 / 3
+// (+) done: 3 / 0
+// (#) test: 0
+// (W) wrap: 3 / 0
 // -----------------------------------------
-// + palette256_get_rgb
-// + palette256_set
-// + palette256_set_rgb
+//W+ palette256_get_rgb
+//W+ palette256_set
+//W+ palette256_set_rgb
 
+mod methods;
 mod reimplemented;
+pub use methods::*;
 pub use reimplemented::*;
 
 /// NcPalette structure consisting of an array of 256

rust/src/palette/reimplemented.rs

@@ -1,36 +1,41 @@
 //! `palette256_*` reimplemented functions.
 
-use crate::{
-    channel_rgb8, channel_set, channel_set_rgb8, NcChannel, NcColor, NcPalette, NcPaletteIndex,
-    NcRgb,
-};
+use crate::{NcChannel, NcColor, NcPalette, NcPaletteIndex, NcRgb};
 
-/// Set the different color components of an entry inside a palette store.
-#[inline]
-pub fn palette256_set_rgb(
-    palette: &mut NcPalette,
-    idx: NcPaletteIndex,
-    red: NcColor,
-    green: NcColor,
-    blue: NcColor,
-) {
-    channel_set_rgb8(&mut palette.chans[idx as usize], red, green, blue)
-}
-
-/// Same as `palette256_set_rgb()` but set an assembled 24 bit channel at once.
-#[inline]
-pub fn palette256_set(palette: &mut NcPalette, idx: NcPaletteIndex, rgb: NcRgb) {
-    channel_set(&mut palette.chans[idx as usize], rgb);
-}
-
-/// Extract the three 8-bit R/G/B components from an entry inside a palette store.
+/// Extracts the [NcColor] RGB components from an [NcChannel] entry inside
+/// an [NcPalette], and returns the NcChannel.
+///
+/// *Method: NcPalette.[get_rgb()][NcPalette#method.get_rgb].*
+/// *Method: NcPalette.[get_rgb8()][NcPalette#method.get_rgb8].*
 #[inline]
 pub fn palette256_get_rgb(
     palette: &NcPalette,
-    idx: NcPaletteIndex,
+    index: NcPaletteIndex,
     red: &mut NcColor,
     green: &mut NcColor,
     blue: &mut NcColor,
 ) -> NcChannel {
-    channel_rgb8(palette.chans[idx as usize], red, green, blue)
+    crate::channel_rgb8(palette.chans[index as usize], red, green, blue)
+}
+
+/// Sets the [NcRgb] value of the [NcChannel] entry inside an [NcPalette].
+///
+/// *Method: NcPalette.[set()][NcPalette#method.set].*
+#[inline]
+pub fn palette256_set(palette: &mut NcPalette, index: NcPaletteIndex, rgb: NcRgb) {
+    crate::channel_set(&mut palette.chans[index as usize], rgb);
+}
+
+/// Sets the [NcColor] components of the [NcChannel] entry inside an [NcPalette].
+///
+/// *Method: NcPalette.[set_rgb()][NcPalette#method.set_rgb].*
+#[inline]
+pub fn palette256_set_rgb(
+    palette: &mut NcPalette,
+    index: NcPaletteIndex,
+    red: NcColor,
+    green: NcColor,
+    blue: NcColor,
+) {
+    crate::channel_set_rgb8(&mut palette.chans[index as usize], red, green, blue)
 }

rust/src/plane/methods.rs

@@ -756,14 +756,14 @@ impl NcPlane {
 
     /// Returns the topmost NcPlane of the current pile.
     ///
-    /// *C style function: [ncplane_top()][crate::ncplane_top].*
+    /// *C style function: [ncpile_top()][crate::ncpile_top].*
     pub fn top<'a>(&mut self) -> &'a mut NcPlane {
         unsafe { &mut *crate::ncpile_top(self) }
     }
 
     /// Returns the bottommost NcPlane of the current pile.
     ///
-    /// *C style function: [ncplane_bottom()][crate::ncplane_bottom].*
+    /// *C style function: [ncpile_bottom()][crate::ncpile_bottom].*
     pub fn bottom<'a>(&mut self) -> &'a mut NcPlane {
         unsafe { &mut *crate::ncpile_bottom(self) }
     }
@@ -1002,14 +1002,14 @@ impl NcPlane {
 
     /// Returns the current row of the cursor within this NcPlane.
     ///
-    /// *C style function: [ncplane_cursor_y()][crate::ncplane_cursor_y].*
+    /// *(No equivalent C style function)*
     pub fn cursor_y(&self) -> NcDimension {
         self.cursor_yx().0
     }
 
     /// Returns the current column of the cursor within this NcPlane.
     ///
-    /// *C style function: [ncplane_cursor_x()][crate::ncplane_cursor_x].*
+    /// *(No equivalent C style function)*
     pub fn cursor_x(&self) -> NcDimension {
         self.cursor_yx().1
     }
@@ -1185,7 +1185,9 @@ impl NcPlane {
     ///
     /// Suitable for use as an [NcResizeCb].
     ///
-    /// *C style function: [ncplane_resize_align()][crate::ncplane_resize_align].*
+    /// *C style function: [ncplane_resize_realign()][crate::ncplane_resize_realign].*
+    //
+    // TODO: suitable for use as an NcResizeCb?
     pub fn resize_realign(&mut self) -> NcResult {
         unsafe { crate::ncplane_resize_realign(self) }
     }

rust/src/resizecb.rs

@@ -2,14 +2,16 @@
 
 use crate::{NcPlane, NcResult};
 
-/// A callback function called when an [`NcPlane`] is resized.
+/// A callback function called when an [NcPlane] is resized.
 ///
 /// See also [ncresizecb_to_rust] & [ncresizecb_to_c].
+///
 pub type NcResizeCb = fn(&mut NcPlane) -> NcResult;
 
-pub(crate) type NcResizeCbUnsafe = unsafe extern "C" fn(*mut NcPlane) -> NcResult;
+/// The unsafe version of [NcResizeCb] expected by the notcurses C API.
+pub type NcResizeCbUnsafe = unsafe extern "C" fn(*mut NcPlane) -> NcResult;
 
-/// Returns [NcResizeCb] from the resizecb type in the notcurses C API.
+/// Converts [NcResizeCbUnsafe] to [NcResizeCb].
 pub fn ncresizecb_to_rust(resizecb: Option<NcResizeCbUnsafe>) -> Option<NcResizeCb> {
     if let Some(cb) = resizecb {
         return Some(unsafe { core::mem::transmute(cb) });
@@ -18,7 +20,8 @@ pub fn ncresizecb_to_rust(resizecb: Option<NcResizeCbUnsafe>) -> Option<NcResize
     }
 }
 
-/// Converts [NcResizeCb] to the resizecb type expected by notcurses C API.
+/// Converts [NcResizeCb] to [NcResizeCbUnsafe].
+///
 pub fn ncresizecb_to_c(resizecb: Option<NcResizeCb>) -> Option<NcResizeCbUnsafe> {
     if let Some(cb) = resizecb {
         return Some(unsafe { core::mem::transmute(cb) });
@@ -26,3 +29,36 @@ pub fn ncresizecb_to_c(resizecb: Option<NcResizeCb>) -> Option<NcResizeCbUnsafe>
         None
     }
 }
+
+/// Enables the [NcResizeCb] methods.
+pub trait NcResizeCbMethods {
+    fn to_rust(&self) -> Option<NcResizeCb>;
+    fn to_c(&self) -> Option<NcResizeCbUnsafe>;
+}
+
+impl NcResizeCbMethods for NcResizeCb {
+    /// Returns [NcResizeCbUnsafe].
+    ///
+    /// *C style function: [ncresizecb_to_c()][ncresizecb_to_c].*
+    fn to_c(&self) -> Option<NcResizeCbUnsafe> {
+        ncresizecb_to_c(Some(*self))
+    }
+    /// no-op.
+    fn to_rust(&self) -> Option<NcResizeCb> {
+        Some(*self)
+    }
+}
+
+impl NcResizeCbMethods for NcResizeCbUnsafe {
+    /// no-op.
+    fn to_c(&self) -> Option<NcResizeCbUnsafe> {
+        Some(*self)
+    }
+
+    /// Returns [NcResizeCb].
+    ///
+    /// *C style function: [ncresizecb_to_rust()][ncresizecb_to_rust].*
+    fn to_rust(&self) -> Option<NcResizeCb> {
+        ncresizecb_to_rust(Some(*self))
+    }
+}