rust: add NcCell Methods.

- improve some apis.
- made some functions const.
- add comments and intra-doc links.
- fix comments.

rust/src/cells/methods.rs

@@ -1,8 +1,8 @@
 //! `NcCell` methods and associated functions.
 
 use crate::{
-    cell_extract, cell_load, cstring, NcCell, NcChannelPair, NcEgc, NcEgcBackstop, NcPlane,
-    NcStyleMask, NCRESULT_ERR,
+    cell_extract, cell_load, cstring, NcAlphaBits, NcCell, NcChannel, NcChannelPair, NcColor,
+    NcEgc, NcEgcBackstop, NcPaletteIndex, NcPlane, NcRgb, NcStyleMask, NCRESULT_ERR,
 };
 
 /// # `NcCell` Constructors
@@ -55,10 +55,214 @@ impl NcCell {
     }
 }
 
+// -----------------------------------------------------------------------------
+/// ## NcPlane methods: bg|fg `NcChannel`s manipulation.
+impl NcCell {
+    /// Gets the background [NcChannel].
+    ///
+    /// *C style function: [cell_bchannel()][crate::cell_bchannel].*
+    pub fn bchannel(&self) -> NcChannel {
+        crate::cell_bchannel(self)
+    }
+
+    /// Extracts the background [NcAlphaBits] (shifted to LSBs).
+    ///
+    /// *C style function: [cell_bg_alpha()][crate::cell_bg_alpha].*
+    pub fn bg_alpha(&self) -> NcAlphaBits {
+        crate::cell_bg_alpha(self)
+    }
+
+    /// Is the background [NcChannel] using the "default background color"?
+    ///
+    /// *C style function: [cell_bg_default_p()][crate::cell_bg_default_p].*
+    pub fn bg_default_p(&self) -> bool {
+        crate::cell_bg_default_p(self)
+    }
+
+    /// Gets the [NcPaletteIndex] of the background [NcChannel].
+    ///
+    /// *C style function: [cell_bg_palindex()][crate::cell_bg_palindex].*
+    pub fn bg_palindex(&self) -> NcPaletteIndex {
+        crate::cell_bg_palindex(self)
+    }
+
+    /// Is the background [NcChannel] using an [NcPaletteIndex] indexed
+    /// [NcPalette][crate::NcPalette] color?
+    ///
+    /// *C style function: [cell_bg_palindex_p()][crate::cell_bg_palindex_p].*
+    pub fn bg_palindex_p(&self) -> bool {
+        crate::cell_bg_palindex_p(self)
+    }
+
+    /// Gets the background [NcRgb] (shifted to LSBs).
+    ///
+    /// *C style function: [cell_bg_rgb()][crate::cell_bg_rgb].*
+    pub fn bg_rgb(&self) -> NcRgb {
+        crate::cell_bg_rgb(self)
+    }
+
+    /// Gets the background [NcColor] RGB components.
+    ///
+    /// *C style function: [cell_bg_rgb8()][crate::cell_bg_rgb8].*
+    pub fn bg_rgb8(&self) -> (NcColor, NcColor, NcColor) {
+        let (mut r, mut g, mut b) = (0, 0, 0);
+        crate::cell_bg_rgb8(self, &mut r, &mut g, &mut b);
+        (r, g, b)
+    }
+
+    /// Gets the foreground [NcChannel].
+    ///
+    /// *C style function: [cell_fchannel()][crate::cell_fchannel].*
+    pub fn fchannel(&self) -> NcChannel {
+        crate::cell_fchannel(self)
+    }
+
+    /// Extracts the foreground [NcAlphaBits] (shifted to LSBs).
+    ///
+    /// *C style function: [cell_fg_alpha()][crate::cell_fg_alpha].*
+    pub fn fg_alpha(&self) -> NcAlphaBits {
+        crate::cell_fg_alpha(self)
+    }
+
+    /// Is the foreground [NcChannel] using the "default foreground color"?
+    ///
+    /// *C style function: [cell_fg_default_p()][crate::cell_fg_default_p].*
+    pub fn fg_default_p(&self) -> bool {
+        crate::cell_fg_default_p(self)
+    }
+
+    /// Gets the [NcPaletteIndex] of the foreground [NcChannel].
+    ///
+    /// *C style function: [cell_fg_palindex()][crate::cell_fg_palindex].*
+    pub fn fg_palindex(&self) -> NcPaletteIndex {
+        crate::cell_fg_palindex(self)
+    }
+
+    /// Is the foreground [NcChannel] using an [NcPaletteIndex] indexed
+    /// [NcPalette][crate::NcPalette] color?
+    ///
+    /// *C style function: [cell_fg_palindex_p()][crate::cell_fg_palindex_p].*
+    pub fn fg_palindex_p(&self) -> bool {
+        crate::cell_fg_palindex_p(self)
+    }
+
+    /// Gets the foreground [NcRgb] (shifted to LSBs).
+    ///
+    /// *C style function: [cell_fg_rgb()][crate::cell_fg_rgb].*
+    pub fn fg_rgb(&self) -> NcRgb {
+        crate::cell_fg_rgb(self)
+    }
+
+    /// Gets the foreground [NcColor] RGB components.
+    ///
+    /// *C style function: [cell_fg_rgb8()][crate::cell_fg_rgb8].*
+    pub fn fg_rgb8(&self) -> (NcColor, NcColor, NcColor) {
+        let (mut r, mut g, mut b) = (0, 0, 0);
+        crate::cell_fg_rgb8(self, &mut r, &mut g, &mut b);
+        (r, g, b)
+    }
+
+    /// Sets the background [NcChannel] and returns the new [NcChannelPair].
+    ///
+    /// *C style function: [cell_set_bchannel()][crate::cell_set_bchannel].*
+    pub fn set_bchannel(&mut self, channel: NcChannel) -> NcChannelPair {
+        crate::cell_set_bchannel(self, channel)
+    }
+
+    /// Sets the background [NcAlphaBits].
+    ///
+    /// *C style function: [cell_set_bg_alpha()][crate::cell_set_bg_alpha].*
+    pub fn set_bg_alpha(&mut self, alpha: NcAlphaBits) {
+        crate::cell_set_bg_alpha(self, alpha);
+    }
+
+    /// Indicates to use the "default color" for the background [NcChannel].
+    ///
+    /// *C style function: [cell_set_bg_default()][crate::cell_set_bg_default].*
+    pub fn set_bg_default(&mut self) {
+        crate::cell_set_bg_default(self);
+    }
+
+    /// Sets the background [NcPaletteIndex].
+    ///
+    /// Also sets [NCCELL_BG_PALETTE][crate::NCCELL_BG_PALETTE] and
+    /// [NCCELL_ALPHA_OPAQUE][crate::NCCELL_ALPHA_OPAQUE], and clears out
+    /// [NCCELL_BGDEFAULT_MASK][crate::NCCELL_BGDEFAULT_MASK].
+    ///
+    /// *C style function: [cell_set_bg_palindex()][crate::cell_set_bg_palindex].*
+    pub fn set_bg_palindex(&mut self, index: NcPaletteIndex) {
+        crate::cell_set_bg_palindex(self, index);
+    }
+
+    /// Sets the background [NcRgb] and marks it as not using the default color.
+    ///
+    /// *C style function: [cell_set_bg_rgb()][crate::cell_set_bg_rgb].*
+    pub fn set_bg_rgb(&mut self, rgb: NcRgb) {
+        crate::cell_set_bg_rgb(self, rgb);
+    }
+
+    /// Sets the background [NcColor] RGB components, and marks it as not using
+    /// the "default color".
+    ///
+    /// *C style function: [cell_set_bg_rgb8()][crate::cell_set_bg_rgb8].*
+    pub fn set_bg_rgb8(&mut self, red: NcColor, green: NcColor, blue: NcColor) {
+        crate::cell_set_bg_rgb8(self, red, green, blue);
+    }
+
+    /// Sets the foreground [NcChannel] and returns the new [NcChannelPair].
+    ///
+    /// *C style function: [cell_set_fchannel()][crate::cell_set_fchannel].*
+    pub fn set_fchannel(&mut self, channel: NcChannel) -> NcChannelPair {
+        crate::cell_set_fchannel(self, channel)
+    }
+
+    /// Sets the foreground [NcAlphaBits].
+    ///
+    /// *C style function: [cell_set_fg_alpha()][crate::cell_set_fg_alpha].*
+    pub fn set_fg_alpha(&mut self, alpha: NcAlphaBits) {
+        crate::cell_set_fg_alpha(self, alpha);
+    }
+
+    /// Indicates to use the "default color" for the foreground [NcChannel].
+    ///
+    /// *C style function: [cell_set_fg_default()][crate::cell_set_fg_default].*
+    pub fn set_fg_default(&mut self) {
+        crate::cell_set_fg_default(self);
+    }
+
+    /// Sets the foreground [NcPaletteIndex].
+    ///
+    /// Also sets [NCCELL_FG_PALETTE][crate::NCCELL_FG_PALETTE] and
+    /// [NCCELL_ALPHA_OPAQUE][crate::NCCELL_ALPHA_OPAQUE], and clears out
+    /// [NCCELL_BGDEFAULT_MASK][crate::NCCELL_BGDEFAULT_MASK].
+    ///
+    /// *C style function: [cell_set_fg_palindex()][crate::cell_set_fg_palindex].*
+    pub fn set_fg_palindex(&mut self, index: NcPaletteIndex) {
+        crate::cell_set_fg_palindex(self, index);
+    }
+
+    /// Sets the foreground [NcRgb] and marks it as not using the default color.
+    ///
+    /// *C style function: [cell_set_fg_rgb()][crate::cell_set_fg_rgb].*
+    pub fn set_fg_rgb(&mut self, rgb: NcRgb) {
+        crate::cell_set_fg_rgb(self, rgb);
+    }
+
+    /// Sets the foreground [NcColor] RGB components, and marks it as not using
+    /// the "default color".
+    ///
+    /// *C style function: [cell_set_fg_rgb8()][crate::cell_set_fg_rgb8].*
+    pub fn set_fg_rgb8(&mut self, red: NcColor, green: NcColor, blue: NcColor) {
+        crate::cell_set_fg_rgb8(self, red, green, blue);
+    }
+}
+
 /// # `NcCell` Methods
 impl NcCell {
     /// Saves the [NcStyleMask] and the [NcChannelPair], and returns the [NcEgc]
     /// (the three elements of an NcCell).
+    ///
+    /// *C style function: [cell_fg_alpha()][crate::cell_fg_alpha].*
     pub fn extract(
         &mut self,
         plane: &mut NcPlane,
@@ -68,22 +272,27 @@ impl NcCell {
         cell_extract(plane, self, styles, channels)
     }
 
-    /// Saves the [NcChannelPair] of the NcCell.
-    // not in the C API
-    pub fn channels(&mut self, plane: &mut NcPlane, channels: &mut NcChannelPair) {
-        let mut _styles = 0;
-        let _char = cell_extract(plane, self, &mut _styles, channels);
+    /// Returns the [NcChannelPair] of the NcCell.
+    ///
+    /// *(No equivalent C style function)*
+    pub fn channels(&mut self, plane: &mut NcPlane) -> NcChannelPair {
+        let (mut _styles, mut channels) = (0, 0);
+        let _char = cell_extract(plane, self, &mut _styles, &mut channels);
+        channels
     }
 
-    /// Saves the [NcStyleMask] of the NcCell.
-    // not in the C API
-    pub fn styles(&mut self, plane: &mut NcPlane, styles: &mut NcStyleMask) {
-        let mut _channels = 0;
-        let _char = cell_extract(plane, self, styles, &mut _channels);
+    /// Returns the [NcStyleMask] of the NcCell.
+    ///
+    /// *(No equivalent C style function)*
+    pub fn styles(&mut self, plane: &mut NcPlane) -> NcStyleMask {
+        let (mut styles, mut _channels) = (0, 0);
+        let _char = cell_extract(plane, self, &mut styles, &mut _channels);
+        styles
     }
 
     /// Returns the [NcEgc] of the NcCell.
-    // not in the C API
+    ///
+    /// *(No equivalent C style function)*
     pub fn egc(&mut self, plane: &mut NcPlane) -> NcEgc {
         let (mut _styles, mut _channels) = (0, 0);
         cell_extract(plane, self, &mut _styles, &mut _channels)

rust/src/cells/mod.rs

@@ -13,42 +13,42 @@
 // ------------------------------------------
 // (X) wont:  2
 // (+) done: 40 /  0
-// (W) wrap:  1 / 39
-// (#) test:  26 / 14
+// (W) wrap: 27
+// (#) test: 26
 // ------------------------------------------
-// # cell_bchannel
-// # cell_bg_alpha
-// # cell_bg_default_p
-// # cell_bg_palindex
-// # cell_bg_palindex_p
-// # cell_bg_rgb
-// # cell_bg_rgb8
+//W# cell_bchannel
+//W# cell_bg_alpha
+//W# cell_bg_default_p
+//W# cell_bg_palindex
+//W# cell_bg_palindex_p
+//W# cell_bg_rgb
+//W# cell_bg_rgb8
 // + cellcmp
 // + cell_double_wide_p
 //W+ cell_extract
-// # cell_fchannel
-// # cell_fg_alpha
-// # cell_fg_default_p
-// # cell_fg_palindex
-// # cell_fg_palindex_p
-// # cell_fg_rgb
-// # cell_fg_rgb8
+//W# cell_fchannel
+//W# cell_fg_alpha
+//W# cell_fg_default_p
+//W# cell_fg_palindex
+//W# cell_fg_palindex_p
+//W# cell_fg_rgb
+//W# cell_fg_rgb8
 // + cell_init
 // + cell_load_char
 // + cell_prime
-// # cell_set_bchannel
-// # cell_set_bg_alpha
-// # cell_set_bg_default
-// # cell_set_bg_palindex
-// # cell_set_bg_rgb
-// # cell_set_bg_rgb8
+//W# cell_set_bchannel
+//W# cell_set_bg_alpha
+//W# cell_set_bg_default
+//W# cell_set_bg_palindex
+//W# cell_set_bg_rgb
+//W# cell_set_bg_rgb8
 // X cell_set_bg_rgb8_clipped   // unneeded
-// # cell_set_fchannel
-// # cell_set_fg_alpha
-// # cell_set_fg_default
-// # cell_set_fg_palindex
-// # cell_set_fg_rgb
-// # cell_set_fg_rgb8
+//W# cell_set_fchannel
+//W# cell_set_fg_alpha
+//W# cell_set_fg_default
+//W# cell_set_fg_palindex
+//W# cell_set_fg_rgb
+//W# cell_set_fg_rgb8
 // X cell_set_fg_rgb8_clipped   // unneeded
 // + cells_load_box
 // + cell_strdup
@@ -67,7 +67,7 @@ mod reimplemented;
 pub use reimplemented::*;
 
 // NcCell
-/// A coordinate on an [`NcPlane`][crate::NcPlane] storing 128 bits of data
+/// A coordinate on an [`NcPlane`][crate::NcPlane] storing 128 bits of data.
 ///
 /// An `NcCell` corresponds to a single character cell on some [`NcPlane`],
 /// which can be occupied by a single [`NcEgc`] grapheme cluster (some root

rust/src/cells/reimplemented.rs

@@ -3,76 +3,88 @@
 use libc::strcmp;
 
 use crate::{
-    cell_extended_gcluster, cell_load, cell_release, channels_bchannel, channels_bg_alpha,
-    channels_bg_default_p, channels_bg_palindex_p, channels_bg_rgb, channels_bg_rgb8,
-    channels_fchannel, channels_fg_alpha, channels_fg_default_p, channels_fg_palindex_p,
-    channels_fg_rgb, channels_fg_rgb8, channels_set_bchannel, channels_set_bg_alpha,
-    channels_set_bg_default, channels_set_bg_rgb, channels_set_bg_rgb8, channels_set_fchannel,
-    channels_set_fg_alpha, channels_set_fg_default, channels_set_fg_rgb, channels_set_fg_rgb8,
-    NcAlphaBits, NcCell, NcChannel, NcChannelPair, NcColor, NcEgc, NcPaletteIndex, NcPlane,
-    NcResult, NcRgb, NcStyleMask, NCCELL_ALPHA_OPAQUE, NCCELL_BGDEFAULT_MASK, NCCELL_BG_PALETTE,
-    NCCELL_FGDEFAULT_MASK, NCCELL_FG_PALETTE, NCCELL_NOBACKGROUND_MASK, NCCELL_WIDEASIAN_MASK,
-    NCRESULT_ERR, NCRESULT_OK, NCSTYLE_MASK,
+    cell_release, NcAlphaBits, NcCell, NcChannel, NcChannelPair, NcColor, NcEgc, NcPaletteIndex,
+    NcPlane, NcResult, NcRgb, NcStyleMask, NCCELL_ALPHA_OPAQUE, NCCELL_BGDEFAULT_MASK,
+    NCCELL_BG_PALETTE, NCCELL_FGDEFAULT_MASK, NCCELL_FG_PALETTE, NCCELL_NOBACKGROUND_MASK,
+    NCCELL_WIDEASIAN_MASK, NCRESULT_ERR, NCRESULT_OK, NCSTYLE_MASK,
 };
 
 // Alpha -----------------------------------------------------------------------
 
 /// Extracts the foreground [NcAlphaBits] from an [NcCell] (shifted to LSBs).
+///
+/// *Method: NcCell.[fg_alpha()][NcCell#method.fg_alpha].*
 #[inline]
 pub fn cell_fg_alpha(cell: &NcCell) -> NcAlphaBits {
-    channels_fg_alpha(cell.channels)
+    crate::channels_fg_alpha(cell.channels)
 }
 
 /// Extracts the background [NcAlphaBits] from an [NcCell] (shifted to LSBs).
+///
+/// *Method: NcCell.[bg_alpha()][NcCell#method.bg_alpha].*
 #[inline]
 pub fn cell_bg_alpha(cell: &NcCell) -> NcAlphaBits {
-    channels_bg_alpha(cell.channels)
+    crate::channels_bg_alpha(cell.channels)
 }
 
 /// Sets the foreground [NcAlphaBits] of an [NcCell].
+///
+/// *Method: NcCell.[set_fg_alpha()][NcCell#method.set_fg_alpha].*
 #[inline]
 pub fn cell_set_fg_alpha(cell: &mut NcCell, alpha: NcAlphaBits) {
-    channels_set_fg_alpha(&mut cell.channels, alpha);
+    crate::channels_set_fg_alpha(&mut cell.channels, alpha);
 }
 
 /// Sets the background [NcAlphaBits] of an [NcCell].
+///
+/// *Method: NcCell.[set_bg_alpha()][NcCell#method.set_bg_alpha].*
 #[inline]
 pub fn cell_set_bg_alpha(cell: &mut NcCell, alpha: NcAlphaBits) {
-    channels_set_bg_alpha(&mut cell.channels, alpha);
+    crate::channels_set_bg_alpha(&mut cell.channels, alpha);
 }
 
 // Channels --------------------------------------------------------------------
 
 /// Gets the foreground [NcChannel] from an [NcCell].
+///
+/// *Method: NcCell.[fchannel()][NcCell#method.fchannel].*
 #[inline]
 pub fn cell_fchannel(cell: &NcCell) -> NcChannel {
-    channels_fchannel(cell.channels)
+    crate::channels_fchannel(cell.channels)
 }
 
 /// Gets the background [NcChannel] from an [NcCell].
+///
+/// *Method: NcCell.[bchannel()][NcCell#method.bchannel].*
 #[inline]
 pub fn cell_bchannel(cell: &NcCell) -> NcChannel {
-    channels_bchannel(cell.channels)
+    crate::channels_bchannel(cell.channels)
 }
 
 /// Sets the foreground [NcChannel] of an [NcCell] and returns the new
 /// [NcChannelPair].
+///
+/// *Method: NcCell.[set_fchannel()][NcCell#method.set_fchannel].*
 #[inline]
 pub fn cell_set_fchannel(cell: &mut NcCell, channel: NcChannel) -> NcChannelPair {
-    channels_set_fchannel(&mut cell.channels, channel)
+    crate::channels_set_fchannel(&mut cell.channels, channel)
 }
 
 /// Sets the background [NcChannel] of an [NcCell] and returns the new
 /// [NcChannelPair].
+///
+/// *Method: NcCell.[set_bchannel()][NcCell#method.set_bchannel].*
 #[inline]
 pub fn cell_set_bchannel(cell: &mut NcCell, channel: NcChannel) -> NcChannelPair {
-    channels_set_bchannel(&mut cell.channels, channel)
+    crate::channels_set_bchannel(&mut cell.channels, channel)
 }
 
 // NcColor ---------------------------------------------------------------------
 
 /// Gets the foreground [NcColor] RGB components of an [NcCell],
 /// and returns the [NcChannel] (which can have some extra bits set).
+///
+/// *Method: NcCell.[fg_rgb8()][NcCell#method.fg_rgb8].*
 #[inline]
 pub fn cell_fg_rgb8(
     cell: &NcCell,
@@ -80,11 +92,13 @@ pub fn cell_fg_rgb8(
     green: &mut NcColor,
     blue: &mut NcColor,
 ) -> NcChannel {
-    channels_fg_rgb8(cell.channels, red, green, blue)
+    crate::channels_fg_rgb8(cell.channels, red, green, blue)
 }
 
 /// Gets the background [NcColor] RGB components of an [NcCell],
 /// and returns the [NcChannel] (which can have some extra bits set).
+///
+/// *Method: NcCell.[bg_rgb8()][NcCell#method.bg_rgb8].*
 #[inline]
 pub fn cell_bg_rgb8(
     cell: &NcCell,
@@ -92,72 +106,90 @@ pub fn cell_bg_rgb8(
     green: &mut NcColor,
     blue: &mut NcColor,
 ) -> NcChannel {
-    channels_bg_rgb8(cell.channels, red, green, blue)
+    crate::channels_bg_rgb8(cell.channels, red, green, blue)
 }
 
-/// Sets the foreground [NcColor] 8-bit RGB components of of the [NcCell],
+/// Sets the foreground [NcColor] RGB components of the [NcCell],
 /// and marks it as not using the "default color".
+///
+/// *Method: NcCell.[set_fg_rgb8()][NcCell#method.set_fg_rgb8].*
 #[inline]
 pub fn cell_set_fg_rgb8(cell: &mut NcCell, red: NcColor, green: NcColor, blue: NcColor) {
-    channels_set_fg_rgb8(&mut cell.channels, red, green, blue);
+    crate::channels_set_fg_rgb8(&mut cell.channels, red, green, blue);
 }
 
-/// Sets the background [NcColor] 8-bit RGB components of of the [NcCell],
+/// Sets the background [NcColor] RGB components of the [NcCell],
 /// and marks it as not using the "default color".
+///
+/// *Method: NcCell.[set_bg_rgb8()][NcCell#method.set_bg_rgb8].*
 #[inline]
 pub fn cell_set_bg_rgb8(cell: &mut NcCell, red: NcColor, green: NcColor, blue: NcColor) {
-    channels_set_bg_rgb8(&mut cell.channels, red, green, blue);
+    crate::channels_set_bg_rgb8(&mut cell.channels, red, green, blue);
 }
 
 // NcRgb -----------------------------------------------------------------------
 
 /// Gets the foreground [NcRgb] from an [NcCell] (shifted to LSBs).
+///
+/// *Method: NcCell.[fg_rgb()][NcCell#method.fg_rgb].*
 #[inline]
 pub fn cell_fg_rgb(cell: &NcCell) -> NcRgb {
-    channels_fg_rgb(cell.channels)
+    crate::channels_fg_rgb(cell.channels)
 }
 
 /// Gets the background [NcRgb] from an [NcCell] (shifted to LSBs).
+///
+/// *Method: NcCell.[bg_rgb()][NcCell#method.bg_rgb].*
 #[inline]
 pub fn cell_bg_rgb(cell: &NcCell) -> NcRgb {
-    channels_bg_rgb(cell.channels)
+    crate::channels_bg_rgb(cell.channels)
 }
 
 /// Sets the foreground [NcRgb] of an [NcCell],
 /// and marks it as not using the default color.
+///
+/// *Method: NcCell.[set_fg_rgb()][NcCell#method.set_fg_rgb].*
 #[inline]
 pub fn cell_set_fg_rgb(cell: &mut NcCell, rgb: NcRgb) {
-    channels_set_fg_rgb(&mut cell.channels, rgb);
+    crate::channels_set_fg_rgb(&mut cell.channels, rgb);
 }
 
 /// Sets the background [NcRgb] of an [NcCell],
 /// and marks it as not using the default color.
+///
+/// *Method: NcCell.[set_bg_rgb()][NcCell#method.set_bg_rgb].*
 #[inline]
 pub fn cell_set_bg_rgb(cell: &mut NcCell, rgb: NcRgb) {
-    channels_set_bg_rgb(&mut cell.channels, rgb);
+    crate::channels_set_bg_rgb(&mut cell.channels, rgb);
 }
 
 // Default ---------------------------------------------------------------------
 
-/// Indicates to use the "default color" for the **foreground** [NcChannel]
+/// Indicates to use the "default color" for the foreground [NcChannel]
 /// of an [NcCell].
+///
+/// *Method: NcCell.[set_fg_default()][NcCell#method.set_fg_default].*
 #[inline]
 pub fn cell_set_fg_default(cell: &mut NcCell) {
-    channels_set_fg_default(&mut cell.channels);
+    crate::channels_set_fg_default(&mut cell.channels);
 }
 
-/// Indicates to use the "default color" for the **background** [NcChannel]
+/// Indicates to use the "default color" for the background [NcChannel]
 /// of an [NcCell].
+///
+/// *Method: NcCell.[set_bg_default()][NcCell#method.set_bg_default].*
 #[inline]
 pub fn cell_set_bg_default(cell: &mut NcCell) {
-    channels_set_bg_default(&mut cell.channels);
+    crate::channels_set_bg_default(&mut cell.channels);
 }
 
 /// Is the foreground [NcChannel] of this [NcCell] using the
 /// "default foreground color"?
+///
+/// *Method: NcCell.[fg_default_p()][NcCell#method.fg_default_p].*
 #[inline]
 pub fn cell_fg_default_p(cell: &NcCell) -> bool {
-    channels_fg_default_p(cell.channels)
+    crate::channels_fg_default_p(cell.channels)
 }
 
 /// Is the background [NcChannel] of this [NcCell] using the
@@ -165,36 +197,46 @@ pub fn cell_fg_default_p(cell: &NcCell) -> bool {
 ///
 /// The "default background color" must generally be used to take advantage of
 /// terminal-effected transparency.
+///
+/// *Method: NcCell.[bg_default_p()][NcCell#method.bg_default_p].*
 #[inline]
 pub fn cell_bg_default_p(cell: &NcCell) -> bool {
-    channels_bg_default_p(cell.channels)
+    crate::channels_bg_default_p(cell.channels)
 }
 
 // Palette ---------------------------------------------------------------------
 
 /// Is the foreground [NcChannel] of this [NcCell] using an
 /// [NcPaletteIndex] [indexed][NcPaletteIndex] [NcPalette][crate::NcPalette] color?
+///
+/// *Method: NcCell.[fg_palindex_p()][NcCell#method.fg_palindex_p].*
 #[inline]
 pub fn cell_fg_palindex_p(cell: &NcCell) -> bool {
-    channels_fg_palindex_p(cell.channels)
+    crate::channels_fg_palindex_p(cell.channels)
 }
 
 /// Is the background [NcChannel] of this [NcCell] using an
 /// [NcPaletteIndex] [indexed][NcPaletteIndex] [NcPalette][crate::NcPalette] color?
+///
+/// *Method: NcCell.[bg_palindex_p()][NcCell#method.bg_palindex_p].*
 #[inline]
 pub fn cell_bg_palindex_p(cell: &NcCell) -> bool {
-    channels_bg_palindex_p(cell.channels)
+    crate::channels_bg_palindex_p(cell.channels)
 }
 
 /// Gets the [NcPaletteIndex] of the foreground [NcChannel] of the [NcCell].
+///
+/// *Method: NcCell.[fg_palindex()][NcCell#method.fg_palindex].*
 #[inline]
-pub fn cell_fg_palindex(cell: &NcCell) -> NcPaletteIndex {
+pub const fn cell_fg_palindex(cell: &NcCell) -> NcPaletteIndex {
     ((cell.channels & 0xff00000000 as NcChannelPair) >> 32) as NcPaletteIndex
 }
 
 /// Gets the [NcPaletteIndex] of the background [NcChannel] of the [NcCell].
+///
+/// *Method: NcCell.[bg_palindex()][NcCell#method.bg_palindex].*
 #[inline]
-pub fn cell_bg_palindex(cell: &NcCell) -> NcPaletteIndex {
+pub const fn cell_bg_palindex(cell: &NcCell) -> NcPaletteIndex {
     (cell.channels & 0xff) as NcPaletteIndex
 }
 
@@ -203,6 +245,8 @@ pub fn cell_bg_palindex(cell: &NcCell) -> NcPaletteIndex {
 /// Also sets [NCCELL_FG_PALETTE] and [NCCELL_ALPHA_OPAQUE],
 /// and clears out [NCCELL_FGDEFAULT_MASK].
 ///
+/// *Method: NcCell.[set_fg_palindex()][NcCell#method.set_fg_palindex].*
+//
 // NOTE: unlike the original C function, this one can't fail
 #[inline]
 pub fn cell_set_fg_palindex(cell: &mut NcCell, index: NcPaletteIndex) {
@@ -218,6 +262,8 @@ pub fn cell_set_fg_palindex(cell: &mut NcCell, index: NcPaletteIndex) {
 /// Also sets [NCCELL_BG_PALETTE] and [NCCELL_ALPHA_OPAQUE],
 /// and clears out [NCCELL_BGDEFAULT_MASK].
 ///
+/// *Method: NcCell.[set_bg_palindex()][NcCell#method.set_bg_palindex].*
+//
 // NOTE: unlike the original C function, this one can't fail
 #[inline]
 pub fn cell_set_bg_palindex(cell: &mut NcCell, index: NcPaletteIndex) {
@@ -231,19 +277,25 @@ pub fn cell_set_bg_palindex(cell: &mut NcCell, index: NcPaletteIndex) {
 // Styles ----------------------------------------------------------------------
 
 /// Extracts the [NcStyleMask] bits from an [NcCell].
+///
+/// *Method: NcCell.[cell_styles()][NcCell#method.cell_styles].*
 #[inline]
-pub fn cell_styles(cell: &NcCell) -> NcStyleMask {
+pub const fn cell_styles(cell: &NcCell) -> NcStyleMask {
     cell.stylemask
 }
 
 /// Adds the specified [NcStyleMask] bits to an [NcCell]'s existing spec.,
 /// whether they're actively supported or not.
+///
+/// *Method: NcCell.[styles_on()][NcCell#method.styles_on].*
 #[inline]
 pub fn cell_styles_on(cell: &mut NcCell, stylebits: NcStyleMask) {
     cell.stylemask |= stylebits & NCSTYLE_MASK as u16;
 }
 
 /// Removes the specified [NcStyleMask] bits from an [NcCell]'s existing spec.
+///
+/// *Method: NcCell.[styles_off()][NcCell#method.styles_off].*
 #[inline]
 pub fn cell_styles_off(cell: &mut NcCell, stylebits: NcStyleMask) {
     cell.stylemask &= !(stylebits & NCSTYLE_MASK as u16);
@@ -251,6 +303,8 @@ pub fn cell_styles_off(cell: &mut NcCell, stylebits: NcStyleMask) {
 
 /// Sets *just* the specified [NcStyleMask] bits for an [NcCell],
 /// whether they're actively supported or not.
+///
+/// *Method: NcCell.[styles_set()][NcCell#method.styles_set].*
 #[inline]
 pub fn cell_styles_set(cell: &mut NcCell, stylebits: NcStyleMask) {
     cell.stylemask = stylebits & NCSTYLE_MASK as u16;
@@ -259,45 +313,79 @@ pub fn cell_styles_set(cell: &mut NcCell, stylebits: NcStyleMask) {
 // Chars -----------------------------------------------------------------------
 
 /// Does the [NcCell] contain an East Asian Wide codepoint?
-// NOTE: remove casting when fixed:
-// https://github.com/rust-lang/rust-bindgen/issues/1875
+///
+/// *Method: NcCell.[double_wide_p()][NcCell#method.double_wide_p].*
+//
+// REMAINDER: remove casting when fixed:
+// Waiting for: https://github.com/rust-lang/rust-bindgen/issues/1875
 #[inline]
-pub fn cell_double_wide_p(cell: &NcCell) -> bool {
+pub const fn cell_double_wide_p(cell: &NcCell) -> bool {
     (cell.channels & NCCELL_WIDEASIAN_MASK as NcChannelPair) != 0
 }
 
 /// Is this the right half of a wide character?
+///
+/// *Method: NcCell.[wide_right_p()][NcCell#method.wide_right_p].*
 #[inline]
-pub fn cell_wide_right_p(cell: &NcCell) -> bool {
+pub const fn cell_wide_right_p(cell: &NcCell) -> bool {
     cell_double_wide_p(cell) && cell.gcluster == 0
 }
 
 /// Is this the left half of a wide character?
+///
+/// *Method: NcCell.[wide_left_p()][NcCell#method.wide_left_p].*
 #[inline]
-pub fn cell_wide_left_p(cell: &NcCell) -> bool {
+pub const fn cell_wide_left_p(cell: &NcCell) -> bool {
     cell_double_wide_p(cell) && cell.gcluster != 0
 }
 
 /// Loads a 7-bit char into the [NcCell].
+///
+/// *Method: NcCell.[load_char()][NcCell#method.load_char].*
+//
 // NOTE: Unlike the original C function this doesn't return anything.
-// REMINDER: remove casting for NCCELL_WIDEASIAN_MASK when fixed: https://github.com/rust-lang/rust-bindgen/issues/1875
+// REMINDER: remove casting for NCCELL_WIDEASIAN_MASK when fixed:
+// Waiting for: https://github.com/rust-lang/rust-bindgen/issues/1875
 #[inline]
 pub fn cell_load_char(plane: &mut NcPlane, cell: &mut NcCell, ch: NcEgc) /* -> i32 */
 {
     unsafe {
-        cell_release(plane, cell);
+        crate::cell_release(plane, cell);
     }
     cell.channels &= !(NCCELL_WIDEASIAN_MASK as NcChannelPair | NCCELL_NOBACKGROUND_MASK);
     cell.gcluster = ch as u32;
+
+    /* TODO new version:
+
+    char gcluster[2];
+    gcluster[0] = ch;
+    gcluster[1] = '\0';
+    return cell_load(n, c, gcluster);
+    */
 }
 
+// TODO:
+// // Load a UTF-8 encoded EGC of up to 4 bytes into the cell `c`.
+// static inline int
+// cell_load_egc32(struct ncplane* n, cell* c, uint32_t egc){
+//     char gcluster[sizeof(egc) + 1];
+//     egc = egc.to_le();
+//     memcpy(gcluster, &egc, sizeof(egc));
+//     gcluster[4] = '\0';
+//     return cell_load(n, c, gcluster);
+// }
+
 /// Copies the UTF8-encoded [NcEgc] out of the cell, whether simple or complex.
 ///
 /// The result is not tied to the [NcPlane], and persists across erases and destruction.
+///
+/// *Method: NcCell.[strdup()][NcCell#method.strdup].*
 #[inline]
 pub fn cell_strdup(plane: &NcPlane, cell: &NcCell) -> NcEgc {
-    core::char::from_u32(unsafe { libc::strdup(cell_extended_gcluster(plane, cell)) } as i32 as u32)
-        .expect("wrong char")
+    core::char::from_u32(
+        unsafe { libc::strdup(crate::cell_extended_gcluster(plane, cell)) } as i32 as u32,
+    )
+    .expect("wrong char")
 
     // Unsafer option B (maybe faster, TODO: bench):
     // unsafe {
@@ -309,6 +397,8 @@ pub fn cell_strdup(plane: &NcPlane, cell: &NcCell) -> NcEgc {
 
 /// Saves the [NcStyleMask] and the [NcChannelPair],
 /// and returns the [NcEgc], of an [NcCell].
+///
+/// *Method: NcCell.[extract()][NcCell#method.extract].*
 #[inline]
 pub fn cell_extract(
     plane: &NcPlane,
@@ -329,6 +419,9 @@ pub fn cell_extract(
 ///
 /// The actual egcpool index needn't be the same--indeed, the planes needn't even
 /// be the same. Only the expanded NcEgc must be equal. The NcEgc must be bit-equal;
+///
+/// *Method: NcCell.[compare()][NcCell#method.compare].*
+//
 // NOTE: FIXME: it would probably be better to test whether they're Unicode-equal
 #[inline]
 pub fn cellcmp(plane1: &NcPlane, cell1: &NcCell, plane2: &NcPlane, cell2: &NcCell) -> bool {
@@ -340,25 +433,29 @@ pub fn cellcmp(plane1: &NcPlane, cell1: &NcCell, plane2: &NcPlane, cell2: &NcCel
     }
     unsafe {
         strcmp(
-            cell_extended_gcluster(plane1, cell1),
-            cell_extended_gcluster(plane2, cell2),
+            crate::cell_extended_gcluster(plane1, cell1),
+            crate::cell_extended_gcluster(plane2, cell2),
         ) != 0
     }
 }
 
 /// Initializes (zeroes out) an [NcCell].
+///
+/// *Method: NcCell.[init()][NcCell#method.init].*
 #[inline]
 pub fn cell_init(cell: &mut NcCell) {
     *cell = unsafe { core::mem::zeroed() }
 }
 
-/// Same as [cell_load], plus blasts the styling with 'style' and 'channels'.
+/// Same as [cell_load][crate::cell_load], plus blasts the styling with
+/// `style` and `channels`.
 ///
-/// - Breaks the UTF-8 string in 'gcluster' down, setting up the cell 'cell'.
-/// - Returns the number of bytes copied out of 'gcluster', or -1 on failure.
+/// - Breaks the UTF-8 string in `gcluster` down, setting up the cell `cell`.
+/// - Returns the number of bytes copied out of `gcluster`, or -1 on failure.
 /// - The styling of the cell is left untouched, but any resources are released.
-/// - Blasts the styling with 'style' and 'channels'.
+/// - Blasts the styling with `style` and `channels`.
 ///
+/// *Method: NcCell.[prime()][NcCell#method.prime].*
 pub fn cell_prime(
     plane: &mut NcPlane,
     cell: &mut NcCell,
@@ -368,7 +465,7 @@ pub fn cell_prime(
 ) -> NcResult {
     cell.stylemask = style;
     cell.channels = channels;
-    unsafe { cell_load(plane, cell, gcluster as u32 as *const i8) }
+    unsafe { crate::cell_load(plane, cell, gcluster as u32 as *const i8) }
 }
 
 /// Loads up six cells with the [NcEgc]s necessary to draw a box.
@@ -378,6 +475,7 @@ pub fn cell_prime(
 /// On error, any [NcCell]s this function might have loaded before the error
 /// are [cell_release]d. There must be at least six [NcEgc]s in gcluster.
 ///
+/// *Method: NcCell.[load_box()][NcCell#method.load_box].*
 pub fn cells_load_box(
     plane: &mut NcPlane,
     style: NcStyleMask,

rust/src/plane/mod.rs

@@ -55,16 +55,16 @@
 //W  ncplane_pulse
 //   ncplane_putchar_stained
 //   ncplane_putc_yx
-// X ncplane_putegc_stained
-// X ncplane_putegc_yx
+// X ncplane_putegc_stained            // unneeded
+// X ncplane_putegc_yx                 // unneeded
 //   ncplane_putnstr_aligned
 //   ncplane_putnstr_yx
 //   ncplane_putstr_aligned
 //   ncplane_putstr_stained
 //   ncplane_putstr_yx
 //   ncplane_puttext
-// X ncplane_putwegc_stained
-// X ncplane_putwstr_stained
+// X ncplane_putwegc_stained           // unneeded
+// X ncplane_putwstr_stained           // unneeded
 //   ncplane_qrcode
 //W  ncplane_reparent
 //W  ncplane_reparent_family
@@ -82,7 +82,7 @@
 //W  ncplane_set_bg_palindex
 //W  ncplane_set_bg_rgb
 //W  ncplane_set_bg_rgb8
-// X ncplane_set_bg_rgb8_clipped
+// X ncplane_set_bg_rgb8_clipped       // unneeded
 //W# ncplane_set_channels
 //W# ncplane_set_fchannel
 //W  ncplane_set_fg_alpha
@@ -90,7 +90,7 @@
 //W  ncplane_set_fg_palindex
 //W  ncplane_set_fg_rgb
 //W  ncplane_set_fg_rgb8
-// X ncplane_set_fg_rgb8_clipped
+// X ncplane_set_fg_rgb8_clipped       // unneeded
 //W  ncplane_set_resizecb
 //W  ncplane_set_scrolling
 //W  ncplane_set_styles
@@ -108,7 +108,7 @@
 //W  ncplane_y
 //W  ncplane_yx
 //
-// functions manually reimplemented: 42
+// functions manually reimplemented: 41
 // ------------------------------------------
 // (X) wont:  9
 // (+) done: 34 / 0
@@ -141,17 +141,17 @@
 // + ncplane_putc
 // + ncplane_putchar
 // + ncplane_putchar_yx
-// X ncplane_putegc
+// X ncplane_putegc                    // unneeded
 // + ncplane_putnstr
 //W+ ncplane_putstr
-// X ncplane_putwc
-// X ncplane_putwc_stained
-// X ncplane_putwc_yx
-// X ncplane_putwegc
-// X ncplane_putwegc_yx
-// X ncplane_putwstr
-// X ncplane_putwstr_aligned
-// X ncplane_putwstr_yx
+// X ncplane_putwc                     // unneeded
+// X ncplane_putwc_stained             // unneeded
+// X ncplane_putwc_yx                  // unneeded
+// X ncplane_putwegc                   // unneeded
+// X ncplane_putwegc_yx                // unneeded
+// X ncplane_putwstr                   // unneeded
+// X ncplane_putwstr_aligned           // unneeded
+// X ncplane_putwstr_yx                // unneeded
 //W# ncplane_resize_simple
 // + ncplane_rounded_box
 // + ncplane_rounded_box_sized