rust: add most NcCell methods

- add & fix comments.
- add methods links.

rust/src/cells/methods.rs

@@ -1,11 +1,11 @@
 //! `NcCell` methods and associated functions.
 
 use crate::{
-    cell_extract, cell_load, cstring, NcAlphaBits, NcCell, NcChannel, NcChannelPair, NcColor,
-    NcEgc, NcEgcBackstop, NcPaletteIndex, NcPlane, NcRgb, NcStyleMask, NCRESULT_ERR,
+    cell_load, cstring, error, NcAlphaBits, NcCell, NcChannel, NcChannelPair, NcColor, NcEgc,
+    NcEgcBackstop, NcPaletteIndex, NcPlane, NcResult, NcRgb, NcStyleMask, NCRESULT_ERR,
 };
 
-/// # `NcCell` Constructors
+/// # NcCell constructors
 impl NcCell {
     /// New NcCell, expects a 7-bit [char].
     #[inline]
@@ -42,11 +42,82 @@ impl NcCell {
     pub const fn new() -> Self {
         Self::with_char7b(0 as char)
     }
+
+    // TODO: it's not clear what it does
+    //
+    // /// Breaks the UTF-8 string in `gcluster` down, setting up this NcCell,
+    // /// and returns the number of bytes copied out of `gcluster`.
+    // ///
+    // /// The styling of the cell is left untouched, but any resources are released.
+    // /// *C style function: [cell_load()][crate::cell_load].*
+    // pub fn load(
+    //     plane: &mut NcPlane,
+    //     cell: &mut NcCell,
+    //     gcluster: NcEgc,
+    // ) -> NcResult<u32> {
+    //     let bytes = unsafe { crate::cell_load(plane, cell, gcluster as u32 as *const i8)};
+    //     error![bytes, bytes as u32]
+    // }
+
+    /// Same as [load][NcCell#method.load], plus blasts the styling with
+    /// `style` and `channels`.
+    ///
+    /// - Breaks the UTF-8 string in `gcluster` down, setting up this NcCell.
+    /// - Returns the number of bytes copied out of `gcluster`.
+    /// - The styling of the cell is left untouched, but any resources are released.
+    /// - Blasts the styling with `style` and `channels`.
+    ///
+    /// *C style function: [cell_prime()][crate::cell_prime].*
+    pub fn prime(
+        plane: &mut NcPlane,
+        cell: &mut NcCell,
+        gcluster: NcEgc,
+        style: NcStyleMask,
+        channels: NcChannelPair,
+    ) -> NcResult<u32> {
+        let bytes = crate::cell_prime(plane, cell, gcluster, style, channels);
+        error![bytes, bytes as u32]
+    }
+
+    /// Duplicate this NcCell into another one.
+    ///
+    /// Both must be or will be bound to `common_plane`.
+    ///
+    /// *C style function: [cell_duplicate()][crate::cell_duplicate].*
+    pub fn duplicate(&self, target: &mut NcCell, common_plane: &mut NcPlane) -> NcResult<()> {
+        error![unsafe { crate::cell_duplicate(common_plane, target, self) }]
+    }
+
+    /// Initializes (zeroes out) the NcCell.
+    ///
+    /// *C style function: [cell_init()][crate::cell_init].*
+    #[inline]
+    pub fn init(&mut self) {
+        crate::cell_init(self);
+    }
+
+    /// Releases resources held by the current cell in the [NcPlane] `plane`.
+    ///
+    /// *C style function: [cell_release()][crate::cell_release].*
+    pub fn release(&mut self, plane: &mut NcPlane) {
+        unsafe {
+            crate::cell_release(plane, self);
+        }
+    }
 }
 
 // -----------------------------------------------------------------------------
-/// ## NcPlane methods: bg|fg `NcChannel`s manipulation.
+/// ## NcCell methods: bg|fg `NcChannel`s manipulation.
 impl NcCell {
+    /// 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 = crate::cell_extract(plane, self, &mut _styles, &mut channels);
+        channels
+    }
+
     /// Gets the background [NcChannel].
     ///
     /// *C style function: [cell_bchannel()][crate::cell_bchannel].*
@@ -246,8 +317,19 @@ impl NcCell {
     }
 }
 
-/// # `NcCell` Methods
+/// # `NcCell` methods: other components
 impl NcCell {
+    /// Returns true if the two cells have distinct [NcEgc]s, attributes,
+    /// or [NcChannel]s.
+    ///
+    /// The actual egcpool index needn't be the same--indeed, the planes
+    /// needn't even be the same. Only the expanded NcEgc must be bit-equal.
+    ///
+    /// *C style function: [cellcmp()][crate::cellcmp].*
+    pub fn compare(plane1: &NcPlane, cell1: &NcCell, plane2: &NcPlane, cell2: &NcCell) -> bool {
+        crate::cellcmp(plane1, cell1, plane2, cell2)
+    }
+
     /// Saves the [NcStyleMask] and the [NcChannelPair], and returns the [NcEgc]
     /// (the three elements of an NcCell).
     ///
@@ -258,32 +340,154 @@ impl NcCell {
         styles: &mut NcStyleMask,
         channels: &mut NcChannelPair,
     ) -> NcEgc {
-        cell_extract(plane, self, styles, channels)
+        crate::cell_extract(plane, self, styles, channels)
     }
 
-    /// Returns the [NcChannelPair] of the NcCell.
+    /// Returns the [NcEgc] of the NcCell.
+    ///
+    /// See also: [extended_gcluster][NcCell#method.extended_gcluster] method.
     ///
     /// *(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
+    pub fn egc(&mut self, plane: &mut NcPlane) -> NcEgc {
+        let (mut _styles, mut _channels) = (0, 0);
+        crate::cell_extract(plane, self, &mut _styles, &mut _channels)
     }
 
-    /// Returns the [NcStyleMask] of the NcCell.
+    /// Returns the [NcStyleMask] bits.
     ///
-    /// *(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
+    /// *C style function: [cell_styles()][crate::cell_styles].*
+    pub fn styles(&mut self) -> NcStyleMask {
+        crate::cell_styles(self)
     }
 
-    /// Returns the [NcEgc] of the NcCell.
+    /// Removes the specified [NcStyleMask] bits.
     ///
-    /// *(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)
+    /// *C style function: [cell_off()][crate::cell_off_styles].*
+    pub fn off_styles(&mut self, stylebits: NcStyleMask) {
+        crate::cell_off_styles(self, stylebits)
+    }
+
+    /// Adds the specified [NcStyleMask] bits.
+    ///
+    /// *C style function: [cell_on()][crate::cell_on_styles].*
+    pub fn on_styles(&mut self, stylebits: NcStyleMask) {
+        crate::cell_on_styles(self, stylebits)
+    }
+
+    /// Sets just the specified [NcStyleMask] bits.
+    ///
+    /// *C style function: [cell_set_styles()][crate::cell_set_styles].*
+    pub fn set_styles(&mut self, stylebits: NcStyleMask) {
+        crate::cell_set_styles(self, stylebits)
+    }
+}
+
+/// # `NcCell` methods: text
+impl NcCell {
+    // /// Returns a pointer to the [NcEgc] of this NcCell in the [NcPlane] `plane`.
+    // ///
+    // /// This pointer can be invalidated by any further operation on the referred
+    // /// plane, so… watch out!
+    // ///
+    // /// *C style function: [cell_extended_gcluster()][crate::cell_wide_left_p].*
+    // pub fn extended_gcluster(&self, plane: &NcPlane) -> u32 {
+    //     let egcpointer = unsafe { crate::cell_extended_gcluster(plane, self) };
+    //     egcpointer
+    // }
+
+    /// Copies the UTF8-encoded [NcEgc] out of this NcCell,
+    /// whether simple or complex.
+    ///
+    /// The result is not tied to the [NcPlane],
+    /// and persists across erases and destruction.
+    ///
+    /// *C style function: [cell_strdup()][crate::cell_strdup].*
+    pub fn strdup(&self, plane: &NcPlane) -> NcEgc {
+        crate::cell_strdup(plane, self)
+    }
+
+    /// Does this NcCell contain an East Asian Wide codepoint?
+    ///
+    /// *C style function: [cell_double_wide_p()][crate::cell_double_wide_p].*
+    pub fn double_wide_p(&self) -> bool {
+        crate::cell_double_wide_p(self)
+    }
+
+    /// Is this the left half of a wide character?
+    ///
+    /// *C style function: [cell_wide_left_p()][crate::cell_wide_left_p].*
+    pub fn wide_left_p(&self) -> bool {
+        crate::cell_wide_right_p(self)
+    }
+
+    /// Is this the right half of a wide character?
+    ///
+    /// *C style function: [cell_wide_right_p()][crate::cell_wide_right_p].*
+    pub fn wide_right_p(&self) -> bool {
+        crate::cell_wide_right_p(self)
+    }
+}
+
+/// # `NcCell` methods: boxes
+impl NcCell {
+    /// Loads up six cells with the [NcEgc]s necessary to draw a box.
+    ///
+    /// 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`.
+    ///
+    /// *C style function: [cells_load_box()][crate::cells_load_box].*
+    pub fn load_box(
+        plane: &mut NcPlane,
+        style: NcStyleMask,
+        channels: NcChannelPair,
+        ul: &mut NcCell,
+        ur: &mut NcCell,
+        ll: &mut NcCell,
+        lr: &mut NcCell,
+        hl: &mut NcCell,
+        vl: &mut NcCell,
+        gcluster: NcEgc,
+    ) -> NcResult<()> {
+        error![crate::cells_load_box(
+            plane, style, channels, ul, ur, ll, lr, hl, vl, gcluster
+        )]
+    }
+
+    /// NcCell.[load_box()][NcCell#method.box] with the double box-drawing characters.
+    /// 
+    /// *C style function: [cells_double_box()][crate::cells_double_box].*
+    pub fn double_box(
+        plane: &mut NcPlane,
+        style: NcStyleMask,
+        channels: NcChannelPair,
+        ul: &mut NcCell,
+        ur: &mut NcCell,
+        ll: &mut NcCell,
+        lr: &mut NcCell,
+        hl: &mut NcCell,
+        vl: &mut NcCell,
+    ) -> NcResult<()> {
+        error![unsafe {
+            crate::cells_double_box(plane, style as u32, channels, ul, ur, ll, lr, hl, vl)
+        }]
+    }
+
+    /// NcCell.[load_box()][NcCell#method.box] with the rounded box-drawing characters.
+    ///
+    /// *C style function: [cells_rounded_box()][crate::cells_double_box].*
+    pub fn rounded_box(
+        plane: &mut NcPlane,
+        style: NcStyleMask,
+        channels: NcChannelPair,
+        ul: &mut NcCell,
+        ur: &mut NcCell,
+        ll: &mut NcCell,
+        lr: &mut NcCell,
+        hl: &mut NcCell,
+        vl: &mut NcCell,
+    ) -> NcResult<()> {
+        error![unsafe {
+            crate::cells_rounded_box(plane, style as u32, channels, ul, ur, ll, lr, hl, vl)
+        }]
     }
 }

rust/src/cells/mod.rs

@@ -2,18 +2,21 @@
 
 // functions already exported by bindgen : 6
 // -----------------------------------------
-// cell_duplicate
-// cell_extended_gcluster
-// cell_load
-// cell_release
-// cells_double_box
-// cells_rounded_box
+// (W) wrap: 4
+// (#) test: 0
+// ------------------------------------------
+//W  cell_duplicate
+//…  cell_extended_gcluster
+//…  cell_load
+//W  cell_release
+//W  cells_double_box
+//W  cells_rounded_box
 //
 // functions manually reimplemented: 43
 // ------------------------------------------
 // (X) wont:  2
-// (+) done: 40
-// (W) wrap: 27
+// (+) done: 38
+// (W) wrap: 40
 // (#) test: 26
 // ------------------------------------------
 //W# cell_bchannel
@@ -23,8 +26,8 @@
 //W# cell_bg_palindex_p
 //W# cell_bg_rgb
 //W# cell_bg_rgb8
-// + cellcmp
-// + cell_double_wide_p
+//W+ cellcmp
+//W+ cell_double_wide_p
 //W+ cell_extract
 //W# cell_fchannel
 //W# cell_fg_alpha
@@ -33,12 +36,12 @@
 //W# cell_fg_palindex_p
 //W# cell_fg_rgb
 //W# cell_fg_rgb8
-// + cell_init
-// + cell_load_char
+//W+ cell_init
+//…… cell_load_char
 //   cell_load_egc32
-// + cell_off_styles
-// + cell_on_styles
-// + cell_prime
+//W+ cell_off_styles
+//W+ cell_on_styles
+//W+ cell_prime
 //W# cell_set_bchannel
 //W# cell_set_bg_alpha
 //W# cell_set_bg_default
@@ -53,12 +56,12 @@
 //W# cell_set_fg_rgb
 //W# cell_set_fg_rgb8
 // X cell_set_fg_rgb8_clipped   // unneeded
-// + cell_set_styles
-// + cells_load_box
-// + cell_strdup
-// + cell_styles
-// + cell_wide_left_p
-// + cell_wide_right_p
+//W+ cell_set_styles
+//W+ cells_load_box
+//W+ cell_strdup
+//W+ cell_styles
+//W+ cell_wide_left_p
+//W+ cell_wide_right_p
 
 #[cfg(test)]
 mod test;
@@ -70,11 +73,24 @@ pub use reimplemented::*;
 // NcCell
 /// A coordinate on an [`NcPlane`][crate::NcPlane] storing 128 bits of data.
 ///
-/// An `NcCell` corresponds to a single character cell on some [`NcPlane`],
+/// # Methods & Associated Functions
+///
+/// - [Constructors & Destructors](#nccell-constructors-and-destructors)
+///
+/// - [bg|fg `NcChannel`s manipulation](#nccell-methods-bgfg-ncchannels-manipulation)
+/// - [Other components](#nccell-methods-other-components)
+/// - [Text](#nccell-methods-text)
+///
+/// # Description
+///
+/// An `NcCell` corresponds to a single character cell on some NcPlane`,
 /// which can be occupied by a single [`NcEgc`] grapheme cluster (some root
 /// spacing glyph, along with possible combining characters, which might span
 /// multiple columns).
 ///
+/// An NcCell is bounded to an NcPlane, but the cell doesn't know which plane it is.
+/// The extended grapheme information
+///
 /// At any `NcCell`, we can have a theoretically arbitrarily long UTF-8 string,
 /// a foreground color, a background color, and an [`NcStyleMask`] attribute set.
 ///
@@ -120,6 +136,8 @@ pub use reimplemented::*;
 ///
 /// `type in C: cell (struct)`
 ///
+/// # More NcCell Information
+///
 /// ## Size
 ///
 /// Multi-column characters can only have a single style/color throughout.

rust/src/cells/reimplemented.rs

@@ -375,9 +375,10 @@ pub fn cell_load_char(plane: &mut NcPlane, cell: &mut NcCell, ch: NcEgc) /* -> i
 //     return cell_load(n, c, gcluster);
 // }
 
-/// Copies the UTF8-encoded [NcEgc] out of the cell, whether simple or complex.
+/// Copies the UTF8-encoded [NcEgc] out of the [NcCell], whether simple or complex.
 ///
-/// The result is not tied to the [NcPlane], and persists across erases and destruction.
+/// The result is not tied to the [NcPlane],
+/// and persists across erases and destruction.
 ///
 /// *Method: NcCell.[strdup()][NcCell#method.strdup].*
 #[inline]
@@ -473,7 +474,7 @@ pub fn cell_prime(
 /// Returns [NCRESULT_OK] on success, [NCRESULT_ERR] on error.
 ///
 /// 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.
+/// 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(

rust/src/plane/methods.rs

@@ -68,7 +68,7 @@ impl NcPlaneOptions {
     }
 }
 
-/// # NcPlane constructors and destructors
+/// # NcPlane constructors & destructors
 impl NcPlane {
     /// New NcPlane.
     ///
@@ -1466,7 +1466,8 @@ impl NcPlane {
         )]
     }
 
-    ///
+    /// NcPlane.[perimeter()][NcDirect#method.perimeter] with the double box-drawing characters.
+
     ///
     /// *C style function: [ncplane_perimeter_double()][crate::ncplane_perimeter_double].*
     #[inline]
@@ -1481,6 +1482,7 @@ impl NcPlane {
         )]
     }
 
+    /// NcPlane.[perimeter()][NcDirect#method.perimeter] with the rounded box-drawing characters.
     ///
     ///
     /// *C style function: [ncplane_perimeter_rounded()][crate::ncplane_perimeter_rounded].*

rust/src/plane/mod.rs

@@ -220,7 +220,7 @@ pub use reimplemented::*;
 ///
 /// # Methods & Associated Functions
 ///
-/// - [Constructors & Destructors](#ncplane-constructors-and-destructors)
+/// - [Constructors & Destructors](#ncplane-constructors--destructors)
 ///
 /// Methods:
 /// - [`NcAlphaBits`](#ncplane-methods-ncalphabits)