rust: refactoring and corrections.

- reorder cell, ncchannel & ncplane reimplemented functions.
- minor fixes and corrections.
- improve doc comments.

rust/src/cells/methods.rs

@@ -1,11 +1,10 @@
 //! `NcCell` methods and associated functions.
 
-pub use crate::{
+use crate::{
-    cell_load, cstring, NcCell, NcChannelPair, NcEgcBackstop, NcPlane, NcStyleMask, NCRESULT_ERR,
+    cell_extract, cell_load, cstring, NcCell, NcChannelPair, NcEgc, NcEgcBackstop, NcPlane,
+    NcStyleMask, NCRESULT_ERR,
 };
 
-use crate::{cell_extract, NcEgc};
-
 /// # `NcCell` Constructors
 impl NcCell {
     /// New NcCell, expects a [char], [NcStyleMask] and [NcChannelPair].

rust/src/cells/reimplemented.rs

@@ -15,111 +15,221 @@ use crate::{
     NCRESULT_ERR, NCRESULT_OK, NCSTYLE_MASK,
 };
 
-/// Same as [cell_load], plus blasts the styling with 'style' and 'channels'.
+// Alpha -----------------------------------------------------------------------
-///
+
-/// - Breaks the UTF-8 string in 'gcluster' down, setting up the cell 'cell'.
+/// Extracts the foreground [NcAlphaBits] from an [NcCell] (shifted to LSBs).
-/// - Returns the number of bytes copied out of 'gcluster', or -1 on failure.
+#[inline]
-/// - The styling of the cell is left untouched, but any resources are released.
+pub fn cell_fg_alpha(cell: &NcCell) -> NcAlphaBits {
-/// - Blasts the styling with 'style' and 'channels'.
+    channels_fg_alpha(cell.channels)
-///
-#[allow(unused_unsafe)]
-pub unsafe fn cell_prime(
-    plane: &mut NcPlane,
-    cell: &mut NcCell,
-    gcluster: NcEgc,
-    style: NcStyleMask,
-    channels: NcChannelPair,
-) -> NcResult {
-    cell.stylemask = style;
-    cell.channels = channels;
-    unsafe { cell_load(plane, cell, gcluster as u32 as *const i8) }
 }
 
-/// Loads up six cells with the [NcEgc]s necessary to draw a box.
+/// Extracts the background [NcAlphaBits] from an [NcCell] (shifted to LSBs).
-///
+#[inline]
-/// Returns [NCRESULT_OK] on success, [NCRESULT_ERR] on error.
+pub fn cell_bg_alpha(cell: &NcCell) -> NcAlphaBits {
-///
+    channels_bg_alpha(cell.channels)
-/// 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.
-///
-#[allow(unused_unsafe)]
-pub unsafe fn cells_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 {
-    // mutable copy for pointer arithmetics:
-    let mut gclu = gcluster as u32 as *const i8;
-    let mut ulen: NcResult;
 
-    ulen = unsafe { cell_prime(plane, ul, gcluster, style, channels) };
+/// Sets the foreground [NcAlphaBits] of an [NcCell].
+#[inline]
+pub fn cell_set_fg_alpha(cell: &mut NcCell, alpha: NcAlphaBits) {
+    channels_set_fg_alpha(&mut cell.channels, alpha);
+}
 
-    if ulen > 0 {
+/// Sets the background [NcAlphaBits] of an [NcCell].
-        gclu = unsafe { gclu.offset(ulen as isize) };
+#[inline]
-        ulen = unsafe { cell_prime(plane, ur, gcluster, style, channels) };
+pub fn cell_set_bg_alpha(cell: &mut NcCell, alpha: NcAlphaBits) {
+    channels_set_bg_alpha(&mut cell.channels, alpha);
+}
 
-        if ulen > 0 {
+// Channels --------------------------------------------------------------------
-            gclu = unsafe { gclu.offset(ulen as isize) };
-            ulen = unsafe { cell_prime(plane, ll, gcluster, style, channels) };
 
-            if ulen > 0 {
+/// Gets the foreground [NcChannel] from an [NcCell].
-                gclu = unsafe { gclu.offset(ulen as isize) };
+#[inline]
-                ulen = unsafe { cell_prime(plane, lr, gcluster, style, channels) };
+pub fn cell_fchannel(cell: &NcCell) -> NcChannel {
+    channels_fchannel(cell.channels)
+}
 
-                if ulen > 0 {
+/// Gets the background [NcChannel] from an [NcCell].
-                    gclu = unsafe { gclu.offset(ulen as isize) };
+#[inline]
-                    ulen = unsafe { cell_prime(plane, hl, gcluster, style, channels) };
+pub fn cell_bchannel(cell: &NcCell) -> NcChannel {
+    channels_bchannel(cell.channels)
+}
 
-                    if ulen > 0 {
+/// Sets the foreground [NcChannel] of an [NcCell] and returns the new
-                        let _gclu = unsafe { gclu.offset(ulen as isize) };
+/// [NcChannelPair].
-                        ulen = unsafe { cell_prime(plane, vl, gcluster, style, channels) };
+#[inline]
+pub fn cell_set_fchannel(cell: &mut NcCell, channel: NcChannel) -> NcChannelPair {
+    channels_set_fchannel(&mut cell.channels, channel)
+}
 
-                        if ulen > 0 {
+/// Sets the background [NcChannel] of an [NcCell] and returns the new
-                            return NCRESULT_OK;
+/// [NcChannelPair].
+#[inline]
+pub fn cell_set_bchannel(cell: &mut NcCell, channel: NcChannel) -> NcChannelPair {
+    channels_set_bchannel(&mut cell.channels, channel)
 }
-                        unsafe {
+
-                            cell_release(plane, hl);
+// NcColor ---------------------------------------------------------------------
+
+/// Gets the foreground [NcColor] RGB components of an [NcCell],
+/// and returns the [NcChannel] (which can have some extra bits set).
+#[inline]
+pub fn cell_fg_rgb8(
+    cell: &NcCell,
+    red: &mut NcColor,
+    green: &mut NcColor,
+    blue: &mut NcColor,
+) -> NcChannel {
+    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).
+#[inline]
+pub fn cell_bg_rgb8(
+    cell: &NcCell,
+    red: &mut NcColor,
+    green: &mut NcColor,
+    blue: &mut NcColor,
+) -> NcChannel {
+    channels_bg_rgb8(cell.channels, red, green, blue)
 }
-                    unsafe {
+
-                        cell_release(plane, lr);
+/// Sets the foreground [NcColor] 8-bit RGB components of of the [NcCell],
+/// and marks it as not using the "default color".
+#[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);
 }
+
+/// Sets the background [NcColor] 8-bit RGB components of of the [NcCell],
+/// and marks it as not using the "default color".
+#[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);
 }
-                unsafe {
+
-                    cell_release(plane, ll);
+// NcRgb -----------------------------------------------------------------------
+
+/// Gets the foreground [NcRgb] from an [NcCell] (shifted to LSBs).
+#[inline]
+pub fn cell_fg_rgb(cell: &NcCell) -> NcRgb {
+    channels_fg_rgb(cell.channels)
 }
+
+/// Gets the background [NcRgb] from an [NcCell] (shifted to LSBs).
+#[inline]
+pub fn cell_bg_rgb(cell: &NcCell) -> NcRgb {
+    channels_bg_rgb(cell.channels)
 }
-            unsafe {
+
-                cell_release(plane, ur);
+/// Sets the foreground [NcRgb] of an [NcCell],
+/// and marks it as not using the default color.
+#[inline]
+pub fn cell_set_fg_rgb(cell: &mut NcCell, rgb: NcRgb) {
+    channels_set_fg_rgb(&mut cell.channels, rgb);
 }
+
+/// Sets the background [NcRgb] of an [NcCell],
+/// and marks it as not using the default color.
+#[inline]
+pub fn cell_set_bg_rgb(cell: &mut NcCell, rgb: NcRgb) {
+    channels_set_bg_rgb(&mut cell.channels, rgb);
 }
-        unsafe {
+
-            cell_release(plane, ul);
+// Default ---------------------------------------------------------------------
+
+/// Indicates to use the "default color" for the **foreground** [NcChannel]
+/// of an [NcCell].
+#[inline]
+pub fn cell_set_fg_default(cell: &mut NcCell) {
+    channels_set_fg_default(&mut cell.channels);
 }
+
+/// Indicates to use the "default color" for the **background** [NcChannel]
+/// of an [NcCell].
+#[inline]
+pub fn cell_set_bg_default(cell: &mut NcCell) {
+    channels_set_bg_default(&mut cell.channels);
 }
-    NCRESULT_ERR
+
+/// Is the foreground [NcChannel] of this [NcCell] using the
+/// "default foreground color"?
+#[inline]
+pub fn cell_fg_default_p(cell: &NcCell) -> bool {
+    channels_fg_default_p(cell.channels)
 }
 
-/// Initializes (zeroes out) an [NcCell].
+/// Is the background [NcChannel] of this [NcCell] using the
+/// "default background color"?
+///
+/// The "default background color" must generally be used to take advantage of
+/// terminal-effected transparency.
 #[inline]
-pub fn cell_init(cell: &mut NcCell) {
+pub fn cell_bg_default_p(cell: &NcCell) -> bool {
-    *cell = unsafe { core::mem::zeroed() }
+    channels_bg_default_p(cell.channels)
 }
 
-/// Sets *just* the specified [NcStyleMask] bits for an [NcCell],
+// Palette ---------------------------------------------------------------------
-/// whether they're actively supported or not.
+
+/// Is the foreground [NcChannel] of this [NcCell] using an
+/// [NcPaletteIndex] [indexed][NcPaletteIndex] [NcPalette][crate::NcPalette] color?
 #[inline]
-pub fn cell_styles_set(cell: &mut NcCell, stylebits: NcStyleMask) {
+pub fn cell_fg_palindex_p(cell: &NcCell) -> bool {
-    cell.stylemask = stylebits & NCSTYLE_MASK as u16;
+    channels_fg_palindex_p(cell.channels)
+}
+
+/// Is the background [NcChannel] of this [NcCell] using an
+/// [NcPaletteIndex] [indexed][NcPaletteIndex] [NcPalette][crate::NcPalette] color?
+#[inline]
+pub fn cell_bg_palindex_p(cell: &NcCell) -> bool {
+    channels_bg_palindex_p(cell.channels)
+}
+
+/// Gets the [NcPaletteIndex] of the foreground [NcChannel] of the [NcCell].
+#[inline]
+pub 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].
+#[inline]
+pub fn cell_bg_palindex(cell: &NcCell) -> NcPaletteIndex {
+    (cell.channels & 0xff) as NcPaletteIndex
+}
+
+/// Sets an [NcCell]'s foreground [NcPaletteIndex].
+///
+/// Also sets [NCCELL_FG_PALETTE] and [NCCELL_ALPHA_OPAQUE],
+/// and clears out [NCCELL_FGDEFAULT_MASK].
+///
+// NOTE: unlike the original C function, this one can't fail
+#[inline]
+pub fn cell_set_fg_palindex(cell: &mut NcCell, index: NcPaletteIndex) {
+    cell.channels |= NCCELL_FGDEFAULT_MASK;
+    cell.channels |= NCCELL_FG_PALETTE;
+    cell_set_fg_alpha(cell, NCCELL_ALPHA_OPAQUE);
+    cell.channels &= 0xff000000ffffffff as NcChannelPair;
+    cell.channels |= (index as NcChannelPair) << 32;
+}
+
+/// Sets an [NcCell]'s background [NcPaletteIndex].
+///
+/// Also sets [NCCELL_BG_PALETTE] and [NCCELL_ALPHA_OPAQUE],
+/// and clears out [NCCELL_BGDEFAULT_MASK].
+///
+// NOTE: unlike the original C function, this one can't fail
+#[inline]
+pub fn cell_set_bg_palindex(cell: &mut NcCell, index: NcPaletteIndex) {
+    cell.channels |= NCCELL_BGDEFAULT_MASK as NcChannelPair;
+    cell.channels |= NCCELL_BG_PALETTE as NcChannelPair;
+    cell_set_bg_alpha(cell, NCCELL_ALPHA_OPAQUE);
+    cell.channels &= 0xffffffffff000000;
+    cell.channels |= index as NcChannelPair;
+}
+
+// Styles ----------------------------------------------------------------------
+
 /// Extracts the [NcStyleMask] bits from an [NcCell].
 #[inline]
 pub fn cell_styles(cell: &NcCell) -> NcStyleMask {
@@ -139,31 +249,14 @@ pub fn cell_styles_off(cell: &mut NcCell, stylebits: NcStyleMask) {
     cell.stylemask &= !(stylebits & NCSTYLE_MASK as u16);
 }
 
-/// Indicates to use the "default color" for the **foreground** [NcChannel]
+/// Sets *just* the specified [NcStyleMask] bits for an [NcCell],
-/// of an [NcCell].
+/// whether they're actively supported or not.
-#[inline]
-pub fn cell_set_fg_default(cell: &mut NcCell) {
-    channels_set_fg_default(&mut cell.channels);
-}
-
-/// Indicates to use the "default color" for the **background** [NcChannel]
-/// of an [NcCell].
-#[inline]
-pub fn cell_set_bg_default(cell: &mut NcCell) {
-    channels_set_bg_default(&mut cell.channels);
-}
-
-/// Sets the foreground [NcAlphaBits] of an [NcCell].
 #[inline]
-pub fn cell_set_fg_alpha(cell: &mut NcCell, alpha: NcAlphaBits) {
+pub fn cell_styles_set(cell: &mut NcCell, stylebits: NcStyleMask) {
-    channels_set_fg_alpha(&mut cell.channels, alpha);
+    cell.stylemask = stylebits & NCSTYLE_MASK as u16;
 }
 
-/// Sets the background [NcAlphaBits] of an [NcCell].
+// Chars -----------------------------------------------------------------------
-#[inline]
-pub fn cell_set_bg_alpha(cell: &mut NcCell, alpha: NcAlphaBits) {
-    channels_set_bg_alpha(&mut cell.channels, alpha);
-}
 
 /// Does the [NcCell] contain an East Asian Wide codepoint?
 // NOTE: remove casting when fixed:
@@ -185,24 +278,37 @@ pub fn cell_wide_left_p(cell: &NcCell) -> bool {
     cell_double_wide_p(cell) && cell.gcluster != 0
 }
 
-/// Copies the UTF8-encoded [NcEgc] out of the cell, whether simple
+/// Loads a 7-bit char into the [NcCell].
-/// or complex.
+// 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
+#[inline]
+pub fn cell_load_char(plane: &mut NcPlane, cell: &mut NcCell, ch: NcEgc) /* -> i32 */
+{
+    unsafe {
+        cell_release(plane, cell);
+    }
+    cell.channels &= !(NCCELL_WIDEASIAN_MASK as NcChannelPair | NCCELL_NOBACKGROUND_MASK);
+    cell.gcluster = ch as u32;
+}
+
+/// Copies the UTF8-encoded [NcEgc] out of the cell, whether simple or complex.
 ///
-/// The result is not tied to the [NcPlane], and persists
+/// The result is not tied to the [NcPlane], and persists across erases and destruction.
-/// across erases and destruction.
 #[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")
 
-    // unsafer option B (maybe faster, TODO: bench)
+    // Unsafer option B (maybe faster, TODO: bench):
     // unsafe {
     //     core::char::from_u32_unchecked(libc::strdup(cell_extended_gcluster(plane, cell)) as i32 as u32)
     // }
 }
 
-/// Saves the [NcStyleMask] and the [NcChannelPair], and returns the [NcEgc]
+// Misc. -----------------------------------------------------------------------
-/// (the three elements of an [NcCell]).
+
+/// Saves the [NcStyleMask] and the [NcChannelPair],
+/// and returns the [NcEgc], of an [NcCell].
 #[inline]
 pub fn cell_extract(
     plane: &NcPlane,
@@ -219,7 +325,7 @@ pub fn cell_extract(
     cell_strdup(plane, cell)
 }
 
-/// Returns true if the two cells are distinct [NcEgc]s, attributes, or channels
+/// Returns true if the two cells are distinct [NcEgc]s, attributes, or channels.
 ///
 /// 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;
@@ -240,195 +346,100 @@ pub fn cellcmp(plane1: &NcPlane, cell1: &NcCell, plane2: &NcPlane, cell2: &NcCel
     }
 }
 
-/// Loads a 7-bit char into the [NcCell].
+/// Initializes (zeroes out) an [NcCell].
-// 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
-#[inline]
-pub fn cell_load_char(plane: &mut NcPlane, cell: &mut NcCell, ch: NcEgc) /* -> i32 */
-{
-    unsafe {
-        cell_release(plane, cell);
-    }
-    cell.channels &= !(NCCELL_WIDEASIAN_MASK as NcChannelPair | NCCELL_NOBACKGROUND_MASK);
-    cell.gcluster = ch as u32;
-}
-
-/// Extracts the 32-bit background [NcChannel] from an [NcCell].
-#[inline]
-pub fn cell_bchannel(cell: &NcCell) -> NcChannel {
-    channels_bchannel(cell.channels)
-}
-
-/// Extracts the 32-bit foreground [NcChannel] from an [NcCell].
 #[inline]
-pub fn cell_fchannel(cell: &NcCell) -> NcChannel {
+pub fn cell_init(cell: &mut NcCell) {
-    channels_fchannel(cell.channels)
+    *cell = unsafe { core::mem::zeroed() }
 }
 
-/// Sets the 32-bit background [NcChannel] of an [NcCell] and returns its new
+/// Same as [cell_load], plus blasts the styling with 'style' and 'channels'.
-/// [NcChannelPair].
+///
-#[inline]
+/// - Breaks the UTF-8 string in 'gcluster' down, setting up the cell 'cell'.
-pub fn cell_set_bchannel(cell: &mut NcCell, channel: NcChannel) -> NcChannelPair {
+/// - Returns the number of bytes copied out of 'gcluster', or -1 on failure.
-    channels_set_bchannel(&mut cell.channels, channel)
+/// - The styling of the cell is left untouched, but any resources are released.
+/// - Blasts the styling with 'style' and 'channels'.
+///
+#[allow(unused_unsafe)]
+pub unsafe fn cell_prime(
+    plane: &mut NcPlane,
+    cell: &mut NcCell,
+    gcluster: NcEgc,
+    style: NcStyleMask,
+    channels: NcChannelPair,
+) -> NcResult {
+    cell.stylemask = style;
+    cell.channels = channels;
+    unsafe { cell_load(plane, cell, gcluster as u32 as *const i8) }
 }
 
-/// Sets the 32-bit foreground [NcChannel] of an [NcCell] and returns its new
+/// Loads up six cells with the [NcEgc]s necessary to draw a box.
-/// [NcChannelPair].
+///
-#[inline]
+/// Returns [NCRESULT_OK] on success, [NCRESULT_ERR] on error.
-pub fn cell_set_fchannel(cell: &mut NcCell, channel: NcChannel) -> NcChannelPair {
+///
-    channels_set_fchannel(&mut cell.channels, channel)
+/// 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.
+///
+#[allow(unused_unsafe)]
+pub unsafe fn cells_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 {
+    // mutable copy for pointer arithmetics:
+    let mut gclu = gcluster as u32 as *const i8;
+    let mut ulen: NcResult;
 
-/// Extracts the foreground [NcRgb] 24-bit value from an [NcCell]
+    ulen = unsafe { cell_prime(plane, ul, gcluster, style, channels) };
-/// (shifted to LSBs).
-#[inline]
-pub fn cell_fg_rgb(cell: &NcCell) -> NcRgb {
-    channels_fg_rgb(cell.channels)
-}
 
-/// Extracts the background [NcRgb] 24-bit value from an [NcCell]
+    if ulen > 0 {
-/// (shifted to LSBs).
+        gclu = unsafe { gclu.offset(ulen as isize) };
-#[inline]
+        ulen = unsafe { cell_prime(plane, ur, gcluster, style, channels) };
-pub fn cell_bg_rgb(cell: &NcCell) -> NcRgb {
-    channels_bg_rgb(cell.channels)
-}
 
-/// Extracts the foreground [NcAlphaBits] from an [NcCell] (shifted to LSBs).
+        if ulen > 0 {
-#[inline]
+            gclu = unsafe { gclu.offset(ulen as isize) };
-pub fn cell_fg_alpha(cell: &NcCell) -> NcAlphaBits {
+            ulen = unsafe { cell_prime(plane, ll, gcluster, style, channels) };
-    channels_fg_alpha(cell.channels)
-}
 
-/// Extracts the background [NcAlphaBits] from an [NcCell] (shifted to LSBs).
+            if ulen > 0 {
-#[inline]
+                gclu = unsafe { gclu.offset(ulen as isize) };
-pub fn cell_bg_alpha(cell: &NcCell) -> NcAlphaBits {
+                ulen = unsafe { cell_prime(plane, lr, gcluster, style, channels) };
-    channels_bg_alpha(cell.channels)
-}
 
-/// Extracts the foreground [NcRgb] 24-bit value from an [NcCell] and saves it
+                if ulen > 0 {
-/// split into three [NcColor] 8-bit components. Also returns the corresponding
+                    gclu = unsafe { gclu.offset(ulen as isize) };
-/// [NcChannel] (which can have some extra bits set).
+                    ulen = unsafe { cell_prime(plane, hl, gcluster, style, channels) };
-#[inline]
-pub fn cell_fg_rgb8(
-    cell: &NcCell,
-    red: &mut NcColor,
-    green: &mut NcColor,
-    blue: &mut NcColor,
-) -> NcChannel {
-    channels_fg_rgb8(cell.channels, red, green, blue)
-}
 
-/// Extracts the background [NcRgb] 24-bit value from an [NcCell] and saves it
+                    if ulen > 0 {
-/// split into three [NcColor] 8-bit components. Also returns the corresponding
+                        let _gclu = unsafe { gclu.offset(ulen as isize) };
-/// [NcChannel] (which can have some extra bits set).
+                        ulen = unsafe { cell_prime(plane, vl, gcluster, style, channels) };
-#[inline]
-pub fn cell_bg_rgb8(
-    cell: &NcCell,
-    red: &mut NcColor,
-    green: &mut NcColor,
-    blue: &mut NcColor,
-) -> NcChannel {
-    channels_bg_rgb8(cell.channels, red, green, blue)
-}
 
-/// Sets the RGB [NcColor] components for the foreground [NcChannel] of an
+                        if ulen > 0 {
-/// [NcCell], and marks it as not using the default color.
+                            return NCRESULT_OK;
-#[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);
                         }
-
+                        unsafe {
-/// Sets the 24-bit [NcRgb] value for the foreground [NcChannel] of an
+                            cell_release(plane, hl);
-/// [NcCell], and marks it as not using the default color.
-#[inline]
-pub fn cell_set_fg_rgb(cell: &mut NcCell, rgb: NcRgb) {
-    channels_set_fg_rgb(&mut cell.channels, rgb);
                         }
-
-/// Sets an [NcCell]'s foreground [NcPaletteIndex].
-///
-/// Also sets [NCCELL_FG_PALETTE] and [NCCELL_ALPHA_OPAQUE],
-/// and clears out [NCCELL_FGDEFAULT_MASK].
-///
-// NOTE: unlike the original C function, this one can't fail
-#[inline]
-pub fn cell_set_fg_palindex(cell: &mut NcCell, index: NcPaletteIndex) {
-    cell.channels |= NCCELL_FGDEFAULT_MASK;
-    cell.channels |= NCCELL_FG_PALETTE;
-    cell_set_fg_alpha(cell, NCCELL_ALPHA_OPAQUE);
-    cell.channels &= 0xff000000ffffffff as NcChannelPair;
-    cell.channels |= (index as NcChannelPair) << 32;
                     }
-
+                    unsafe {
-/// Returns the [NcPaletteIndex] of the foreground [NcChannel] of the
+                        cell_release(plane, lr);
-/// [NcCell]
-#[inline]
-pub fn cell_fg_palindex(cell: &NcCell) -> NcPaletteIndex {
-    ((cell.channels & 0xff00000000 as NcChannelPair) >> 32) as NcPaletteIndex
                     }
-
-/// Sets the [NcColor] 8-bit RGB components of the background [NcChannel]
-/// of the [NcCell], and marks it as not using the "default color".
-#[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);
                 }
-
+                unsafe {
-/// Sets the [NcRgb] 24-bit value for the background [NcChannel] of this
+                    cell_release(plane, ll);
-/// [NcCell], and marks it as not using the default color.
-#[inline]
-pub fn cell_set_bg_rgb(cell: &mut NcCell, rgb: NcRgb) {
-    channels_set_bg_rgb(&mut cell.channels, rgb);
                 }
-
-/// Sets an [NcCell]'s background [NcPaletteIndex].
-///
-/// Also sets [NCCELL_BG_PALETTE] and [NCCELL_ALPHA_OPAQUE],
-/// and clears out [NCCELL_BGDEFAULT_MASK].
-///
-// NOTE: unlike the original C function, this one can't fail
-#[inline]
-pub fn cell_set_bg_palindex(cell: &mut NcCell, index: NcPaletteIndex) {
-    cell.channels |= NCCELL_BGDEFAULT_MASK as NcChannelPair;
-    cell.channels |= NCCELL_BG_PALETTE as NcChannelPair;
-    cell_set_bg_alpha(cell, NCCELL_ALPHA_OPAQUE);
-    cell.channels &= 0xffffffffff000000;
-    cell.channels |= index as NcChannelPair;
             }
-
+            unsafe {
-/// Returns the [NcPaletteIndex] of the background [NcChannel] of the [NcCell]
+                cell_release(plane, ur);
-#[inline]
-pub fn cell_bg_palindex(cell: &NcCell) -> NcPaletteIndex {
-    (cell.channels & 0xff) as NcPaletteIndex
             }
-
-/// Is the foreground [NcChannel] of this [NcCell] using the
-/// "default foreground color"?
-#[inline]
-pub fn cell_fg_default_p(cell: &NcCell) -> bool {
-    channels_fg_default_p(cell.channels)
         }
-
+        unsafe {
-/// Is the foreground [NcChannel] of this [NcCell] using an
+            cell_release(plane, ul);
-/// [NcPaletteIndex] [indexed][NcPaletteIndex] [NcPalette][crate::NcPalette] color?
-#[inline]
-pub fn cell_fg_palindex_p(cell: &NcCell) -> bool {
-    channels_fg_palindex_p(cell.channels)
         }
-
-/// Is the background [NcChannel] of this [NcCell] using the
-/// "default background color"?
-///
-/// The "default background color" must generally be used to take advantage of
-/// terminal-effected transparency.
-#[inline]
-pub fn cell_bg_default_p(cell: &NcCell) -> bool {
-    channels_bg_default_p(cell.channels)
     }
-
+    NCRESULT_ERR
-/// Is the background [NcChannel] of this [NcCell] using an
-/// [NcPaletteIndex] [indexed][NcPaletteIndex] [NcPalette][crate::NcPalette] color?
-#[inline]
-pub fn cell_bg_palindex_p(cell: &NcCell) -> bool {
-    channels_bg_palindex_p(cell.channels)
 }

rust/src/channel/reimplemented.rs

@@ -6,54 +6,9 @@ use crate::{
     NCCELL_BG_RGB_MASK, NCCELL_FGDEFAULT_MASK, NCCELL_FG_PALETTE, NCCHANNEL_ALPHA_MASK,
 };
 
-/// Extracts the [NcColor] 8-bit red component from a 32-bit [NcChannel].
+// Alpha -----------------------------------------------------------------------
-#[inline]
-pub const fn channel_r(channel: NcChannel) -> NcColor {
-    ((channel & 0xff0000) >> 16) as NcColor
-}
-
-/// Extracts the [NcColor] 8-bit green component from a 32-bit [NcChannel].
-#[inline]
-pub const fn channel_g(channel: NcChannel) -> NcColor {
-    ((channel & 0x00ff00) >> 8) as NcColor
-}
-
-/// Extracts the [NcColor] 8-bit blue component from a 32-bit [NcChannel].
-#[inline]
-pub const fn channel_b(channel: NcChannel) -> NcColor {
-    (channel & 0x0000ff) as NcColor
-}
-
-/// Extracts the three [NcColor] 8-bit RGB components from a 32-bit [NcChannel].
-#[inline]
-pub fn channel_rgb8(
-    channel: NcChannel,
-    r: &mut NcColor,
-    g: &mut NcColor,
-    b: &mut NcColor,
-) -> NcChannel {
-    *r = channel_r(channel);
-    *g = channel_g(channel);
-    *b = channel_b(channel);
-    channel
-}
 
-/// Sets the three [NcColor] 8-bit components of a 32-bit [NcChannel], and marks
+/// Gets the [NcAlphaBits] 2-bit component from a 32-bit [NcChannel].
-/// it as not using the "default color". Retain the other bits unchanged.
-#[inline]
-pub fn channel_set_rgb8(channel: &mut NcChannel, r: NcColor, g: NcColor, b: NcColor) {
-    let rgb: NcRgb = (r as NcChannel) << 16 | (g as NcChannel) << 8 | (b as NcChannel);
-    *channel = (*channel & !NCCELL_BG_RGB_MASK) | NCCELL_BGDEFAULT_MASK | rgb;
-}
-
-/// Sets the [NcRgb] 24-bit RGB value of a 32-bit [NcChannel], and marks it as
-/// not using the "default color". Retain the other bits unchanged.
-#[inline]
-pub fn channel_set(channel: &mut NcChannel, rgb: NcRgb) {
-    *channel = (*channel & !NCCELL_BG_RGB_MASK) | NCCELL_BGDEFAULT_MASK | (rgb & 0x00ffffff);
-}
-
-/// Extracts the [NcAlphaBits] 2-bit component from a 32-bit [NcChannel].
 #[inline]
 pub fn channel_alpha(channel: NcChannel) -> NcAlphaBits {
     channel & NCCHANNEL_ALPHA_MASK
@@ -71,25 +26,41 @@ pub fn channel_set_alpha(channel: &mut NcChannel, alpha: NcAlphaBits) {
     }
 }
 
-/// Is this [NcChannel] using the "default color" rather than RGB/palette-indexed?
+/// Gets the foreground [NcAlphabits] from an [NcChannelPair], shifted to LSBs.
 #[inline]
-pub fn channel_default_p(channel: NcChannel) -> bool {
+pub fn channels_fg_alpha(channels: NcChannelPair) -> NcAlphaBits {
-    (channel & NCCELL_BGDEFAULT_MASK) == 0
+    channel_alpha(channels_fchannel(channels))
 }
 
-/// Is this [NcChannel] using palette-indexed color rather than RGB?
+/// Gets the background [NcAlphabits] from an [NcChannelPair], shifted to LSBs.
 #[inline]
-pub fn channel_palindex_p(channel: NcChannel) -> bool {
+pub fn channels_bg_alpha(channels: NcChannelPair) -> NcAlphaBits {
-    !(channel_default_p(channel) && (channel & NCCELL_BG_PALETTE) == 0)
+    channel_alpha(channels_bchannel(channels))
 }
 
-/// Marks an [NcChannel] as using its "default color", which also marks it opaque.
+/// Sets the [NcAlphaBits] of the foreground [NcChannel] of an [NcChannelPair].
 #[inline]
-pub fn channel_set_default(channel: &mut NcChannel) -> NcChannel {
+pub fn channels_set_fg_alpha(channels: &mut NcChannelPair, alpha: NcAlphaBits) {
-    *channel &= !(NCCELL_BGDEFAULT_MASK | NCCELL_ALPHA_HIGHCONTRAST);
+    let mut channel = channels_fchannel(*channels);
-    *channel
+    channel_set_alpha(&mut channel, alpha);
+    *channels = (channel as NcChannelPair) << 32 | *channels & 0xffffffff_u64;
 }
 
+/// Sets the [NcAlphaBits] of the background [NcChannel] of an [NcChannelPair].
+#[inline]
+pub fn channels_set_bg_alpha(channels: &mut NcChannelPair, alpha: NcAlphaBits) {
+    let mut alpha_clean = alpha;
+    if alpha == NCCELL_ALPHA_HIGHCONTRAST {
+        // forbidden for background alpha, so makes it opaque
+        alpha_clean = NCCELL_ALPHA_OPAQUE;
+    }
+    let mut channel = channels_bchannel(*channels);
+    channel_set_alpha(&mut channel, alpha_clean);
+    channels_set_bchannel(channels, channel);
+}
+
+// Channels --------------------------------------------------------------------
+
 /// Extracts the 32-bit background [NcChannel] from a [NcChannelPair].
 #[inline]
 pub fn channels_bchannel(channels: NcChannelPair) -> NcChannel {
@@ -125,33 +96,49 @@ pub fn channels_combine(fchannel: NcChannel, bchannel: NcChannel) -> NcChannelPa
     channels
 }
 
-/// Extracts the foreground [NcRgb] 24-bit value from an [NcChannelPair],
+// NcColor ---------------------------------------------------------------------
-/// shifted to LSBs.
+
+/// Gets the red [NcColor] 8-bit component from a 32-bit [NcChannel].
 #[inline]
-pub fn channels_fg_rgb(channels: NcChannelPair) -> NcChannel {
+pub const fn channel_r(channel: NcChannel) -> NcColor {
-    channels_fchannel(channels) & NCCELL_BG_RGB_MASK
+    ((channel & 0xff0000) >> 16) as NcColor
 }
 
-/// Extracts the background [NcRgb] 24-bit value from an [NcChannelPair],
+/// Gets the [NcColor] 8-bit component from a 32-bit [NcChannel].
-/// shifted to LSBs.
 #[inline]
-pub fn channels_bg_rgb(channels: NcChannelPair) -> NcChannel {
+pub const fn channel_b(channel: NcChannel) -> NcColor {
-    channels_bchannel(channels) & NCCELL_BG_RGB_MASK
+    (channel & 0x0000ff) as NcColor
 }
 
-/// Extracts the foreground [NcAlphabits] from an [NcChannelPair], shifted to LSBs.
+/// Gets the green [NcColor] 8-bit component from a 32-bit [NcChannel].
 #[inline]
-pub fn channels_fg_alpha(channels: NcChannelPair) -> NcAlphaBits {
+pub const fn channel_g(channel: NcChannel) -> NcColor {
-    channel_alpha(channels_fchannel(channels))
+    ((channel & 0x00ff00) >> 8) as NcColor
 }
 
-/// Extracts the background [NcAlphabits] from an [NcChannelPair], shifted to LSBs.
+/// Gets the three [NcColor] 8-bit RGB components from a 32-bit [NcChannel].
 #[inline]
-pub fn channels_bg_alpha(channels: NcChannelPair) -> NcAlphaBits {
+pub fn channel_rgb8(
-    channel_alpha(channels_bchannel(channels))
+    channel: NcChannel,
+    r: &mut NcColor,
+    g: &mut NcColor,
+    b: &mut NcColor,
+) -> NcChannel {
+    *r = channel_r(channel);
+    *g = channel_g(channel);
+    *b = channel_b(channel);
+    channel
+}
+
+/// Sets the three [NcColor] 8-bit components of a 32-bit [NcChannel], and marks
+/// it as not using the "default color". Retain the other bits unchanged.
+#[inline]
+pub fn channel_set_rgb8(channel: &mut NcChannel, r: NcColor, g: NcColor, b: NcColor) {
+    let rgb: NcRgb = (r as NcChannel) << 16 | (g as NcChannel) << 8 | (b as NcChannel);
+    *channel = (*channel & !NCCELL_BG_RGB_MASK) | NCCELL_BGDEFAULT_MASK | rgb;
 }
 
-/// Extracts the foreground [NcRgb] 24-bit value from an [NcChannelPair], and
+/// Gets the foreground [NcRgb] 24-bit value from an [NcChannelPair], and
 /// saves it split into three [NcColor] 8-bit components. Also returns the
 /// corresponding [NcChannel] (which can have some extra bits set).
 #[inline]
@@ -164,7 +151,7 @@ pub fn channels_fg_rgb8(
     channel_rgb8(channels_fchannel(channels), r, g, b)
 }
 
-/// Extracts the background [NcRgb] 24-bit value from an [NcChannelPair], and
+/// Gets the background [NcRgb] 24-bit value from an [NcChannelPair], and
 /// saves it split into three [NcColor] 8-bit components. Also returns the
 /// corresponding [NcChannel] (which can have some extra bits set).
 #[inline]
@@ -186,15 +173,6 @@ pub fn channels_set_fg_rgb8(channels: &mut NcChannelPair, r: NcColor, g: NcColor
     *channels = (channel as u64) << 32 | *channels & 0xffffffff_u64;
 }
 
-/// Sets the [NcRgb] 24-bit value for the foreground [NcChannel] of an
-/// [NcChannelPair] 64-bit variable, and marks it as not using the "default color".
-#[inline]
-pub fn channels_set_fg_rgb(channels: &mut NcChannelPair, rgb: NcRgb) {
-    let mut channel = channels_fchannel(*channels);
-    channel_set(&mut channel, rgb);
-    *channels = (channel as u64) << 32 | *channels & 0xffffffff_u64;
-}
-
 /// Sets the RGB [NcColor] components for the background [NcChannel] of an
 /// [NcChannelPair] 64-bit variable, and marks it as not using the "default color".
 #[inline]
@@ -204,8 +182,40 @@ pub fn channels_set_bg_rgb8(channels: &mut NcChannelPair, r: NcColor, g: NcColor
     channels_set_bchannel(channels, channel);
 }
 
-/// Sets the [NcRgb] 24-bit value for the background [NcChannel] of an
+// NcRgb -----------------------------------------------------------------------
-/// [NcChannelPair] 64-bit variable, and marks it as not using the "default color".
+
+/// Gets the foreground [NcRgb] 24-bit value from an [NcChannelPair],
+/// shifted to LSBs.
+#[inline]
+pub fn channels_fg_rgb(channels: NcChannelPair) -> NcChannel {
+    channels_fchannel(channels) & NCCELL_BG_RGB_MASK
+}
+
+/// Gets the background [NcRgb] 24-bit value from an [NcChannelPair],
+/// shifted to LSBs.
+#[inline]
+pub fn channels_bg_rgb(channels: NcChannelPair) -> NcChannel {
+    channels_bchannel(channels) & NCCELL_BG_RGB_MASK
+}
+
+/// Sets the [NcRgb] 24-bit RGB value of a 32-bit [NcChannel], and marks it as
+/// not using the "default color". Retain the other bits unchanged.
+#[inline]
+pub fn channel_set(channel: &mut NcChannel, rgb: NcRgb) {
+    *channel = (*channel & !NCCELL_BG_RGB_MASK) | NCCELL_BGDEFAULT_MASK | (rgb & 0x00ffffff);
+}
+
+/// Sets the foreground [NcRgb] 24-bit value of an [NcChannelPair],
+/// and marks it as not using the "default color".
+#[inline]
+pub fn channels_set_fg_rgb(channels: &mut NcChannelPair, rgb: NcRgb) {
+    let mut channel = channels_fchannel(*channels);
+    channel_set(&mut channel, rgb);
+    *channels = (channel as u64) << 32 | *channels & 0xffffffff_u64;
+}
+
+/// Sets the background [NcRgb] 24-bit value of an [NcChannelPair],
+/// , and marks it as not using the "default color".
 #[inline]
 pub fn channels_set_bg_rgb(channels: &mut NcChannelPair, rgb: NcRgb) {
     let mut channel = channels_bchannel(*channels);
@@ -213,25 +223,19 @@ pub fn channels_set_bg_rgb(channels: &mut NcChannelPair, rgb: NcRgb) {
     channels_set_bchannel(channels, channel);
 }
 
-/// Sets the [NcAlphaBits] of the foreground [NcChannel] of an [NcChannelPair].
+// Default ---------------------------------------------------------------------
+
+/// Is this [NcChannel] using the "default color" rather than RGB/palette-indexed?
 #[inline]
-pub fn channels_set_fg_alpha(channels: &mut NcChannelPair, alpha: NcAlphaBits) {
+pub fn channel_default_p(channel: NcChannel) -> bool {
-    let mut channel = channels_fchannel(*channels);
+    (channel & NCCELL_BGDEFAULT_MASK) == 0
-    channel_set_alpha(&mut channel, alpha);
-    *channels = (channel as NcChannelPair) << 32 | *channels & 0xffffffff_u64;
 }
 
-/// Sets the [NcAlphaBits] of the background [NcChannel] of an [NcChannelPair].
+/// Marks an [NcChannel] as using its "default color", which also marks it opaque.
 #[inline]
-pub fn channels_set_bg_alpha(channels: &mut NcChannelPair, alpha: NcAlphaBits) {
+pub fn channel_set_default(channel: &mut NcChannel) -> NcChannel {
-    let mut alpha_clean = alpha;
+    *channel &= !(NCCELL_BGDEFAULT_MASK | NCCELL_ALPHA_HIGHCONTRAST);
-    if alpha == NCCELL_ALPHA_HIGHCONTRAST {
+    *channel
-        // forbidden for background alpha, so makes it opaque
-        alpha_clean = NCCELL_ALPHA_OPAQUE;
-    }
-    let mut channel = channels_bchannel(*channels);
-    channel_set_alpha(&mut channel, alpha_clean);
-    channels_set_bchannel(channels, channel);
 }
 
 /// Is the foreground of an [NcChannelPair] using the "default foreground color"?
@@ -240,13 +244,6 @@ pub fn channels_fg_default_p(channels: NcChannelPair) -> bool {
     channel_default_p(channels_fchannel(channels))
 }
 
-/// Is the foreground of an [NcChannelPair] using an [indexed][NcPaletteIndex]
-/// [NcPalette][crate::NcPalette] color?
-#[inline]
-pub fn channels_fg_palindex_p(channels: NcChannelPair) -> bool {
-    channel_palindex_p(channels_fchannel(channels))
-}
-
 /// Is the background using the "default background color"? The "default
 /// background color" must generally be used to take advantage of
 /// terminal-effected transparency.
@@ -255,24 +252,46 @@ pub fn channels_bg_default_p(channels: NcChannelPair) -> bool {
     channel_default_p(channels_bchannel(channels))
 }
 
-/// Is the background of an [NcChannelPair] using an [indexed][NcPaletteIndex]
+/// Marks the foreground of an [NcChannelPair] as using its "default color",
+/// and returns the new [NcChannelPair].
+#[inline]
+pub fn channels_set_fg_default(channels: &mut NcChannelPair) -> NcChannelPair {
+    let mut channel = channels_fchannel(*channels);
+    channel_set_default(&mut channel);
+    *channels = (channel as u64) << 32 | *channels & 0xffffffff_u64;
+    *channels
+}
+
+/// Marks the background of an [NcChannelPair] as using its "default color",
+/// and returns the new [NcChannelPair].
+#[inline]
+pub fn channels_set_bg_default(channels: &mut NcChannelPair) -> NcChannelPair {
+    let mut channel = channels_bchannel(*channels);
+    channel_set_default(&mut channel);
+    channels_set_bchannel(channels, channel);
+    *channels
+}
+
+// Palette ---------------------------------------------------------------------
+
+/// Is this [NcChannel] using palette-indexed color rather than RGB?
+#[inline]
+pub fn channel_palindex_p(channel: NcChannel) -> bool {
+    !(channel_default_p(channel) && (channel & NCCELL_BG_PALETTE) == 0)
+}
+
+/// Is the foreground of an [NcChannelPair] using an [indexed][NcPaletteIndex]
 /// [NcPalette][crate::NcPalette] color?
 #[inline]
-pub fn channels_bg_palindex_p(channels: NcChannelPair) -> bool {
+pub fn channels_fg_palindex_p(channels: NcChannelPair) -> bool {
-    channel_palindex_p(channels_bchannel(channels))
+    channel_palindex_p(channels_fchannel(channels))
 }
 
-/// Sets an [NcCell]'s background [NcPaletteIndex].
+/// Is the background of an [NcChannelPair] using an [indexed][NcPaletteIndex]
-///
+/// [NcPalette][crate::NcPalette] color?
-/// Also sets [NCCELL_BG_PALETTE] and [NCCELL_ALPHA_OPAQUE],
-/// and clears out [NCCELL_BGDEFAULT_MASK].
 #[inline]
-pub fn channels_set_bg_palindex(channels: &mut NcChannelPair, index: NcPaletteIndex) {
+pub fn channels_bg_palindex_p(channels: NcChannelPair) -> bool {
-    *channels |= NCCELL_BGDEFAULT_MASK as NcChannelPair;
+    channel_palindex_p(channels_bchannel(channels))
-    *channels |= NCCELL_BG_PALETTE as NcChannelPair;
-    channels_set_bg_alpha(channels, NCCELL_ALPHA_OPAQUE);
-    *channels &= 0xffffffffff000000;
-    *channels |= index as NcChannelPair;
 }
 
 /// Sets an [NcCell]'s foreground [NcPaletteIndex].
@@ -288,22 +307,15 @@ pub fn channels_set_fg_palindex(channels: &mut NcChannelPair, index: NcPaletteIn
     *channels |= (index as NcChannelPair) << 32;
 }
 
-/// Marks the foreground of an [NcChannelPair] as using its "default color",
+/// Sets an [NcCell]'s background [NcPaletteIndex].
-/// and returns the new [NcChannelPair].
+///
-#[inline]
+/// Also sets [NCCELL_BG_PALETTE] and [NCCELL_ALPHA_OPAQUE],
-pub fn channels_set_fg_default(channels: &mut NcChannelPair) -> NcChannelPair {
+/// and clears out [NCCELL_BGDEFAULT_MASK].
-    let mut channel = channels_fchannel(*channels);
-    channel_set_default(&mut channel);
-    *channels = (channel as u64) << 32 | *channels & 0xffffffff_u64;
-    *channels
-}
-
-/// Marks the background of an [NcChannelPair] as using its "default color",
-/// and returns the new [NcChannelPair].
 #[inline]
-pub fn channels_set_bg_default(channels: &mut NcChannelPair) -> NcChannelPair {
+pub fn channels_set_bg_palindex(channels: &mut NcChannelPair, index: NcPaletteIndex) {
-    let mut channel = channels_bchannel(*channels);
+    *channels |= NCCELL_BGDEFAULT_MASK as NcChannelPair;
-    channel_set_default(&mut channel);
+    *channels |= NCCELL_BG_PALETTE as NcChannelPair;
-    channels_set_bchannel(channels, channel);
+    channels_set_bg_alpha(channels, NCCELL_ALPHA_OPAQUE);
-    *channels
+    *channels &= 0xffffffffff000000;
+    *channels |= index as NcChannelPair;
 }

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 {
     };
 }
 
-/// Converts an `&str` to `*mut CString`, for when `*const c_char` is needed.
+/// Converts `&str` to `*mut CString`, for when `*const c_char` is needed.
 #[macro_export]
 macro_rules! cstring {
     ($s:expr) => {

rust/src/notcurses/reimplemented.rs

@@ -1,14 +1,5 @@
 //! `notcurses_*` reimplemented functions.
 
-// pub use types::{
-//     NcLogLevel, Notcurses, NotcursesOptions, NCLOGLEVEL_DEBUG, NCLOGLEVEL_ERROR, NCLOGLEVEL_FATAL,
-//     NCLOGLEVEL_INFO, NCLOGLEVEL_PANIC, NCLOGLEVEL_SILENT, NCLOGLEVEL_TRACE, NCLOGLEVEL_VERBOSE,
-//     NCLOGLEVEL_WARNING, NCOPTION_INHIBIT_SETLOCALE, NCOPTION_NO_ALTERNATE_SCREEN,
-//     NCOPTION_NO_FONT_CHANGES, NCOPTION_NO_QUIT_SIGHANDLERS, NCOPTION_NO_WINCH_SIGHANDLER,
-//     NCOPTION_SUPPRESS_BANNERS, NCOPTION_VERIFY_SIXEL,
-// };
-//
-
 use core::ptr::null;
 
 use crate::{

rust/src/palette/mod.rs

@@ -21,7 +21,7 @@
 // + palette256_set
 // + palette256_set_rgb
 
-pub mod reimplemented;
+mod reimplemented;
 pub use reimplemented::*;
 
 /// NcPalette structure consisting of an array of 256 [`NcChannel`]s.

rust/src/plane/reimplemented.rs

@@ -15,18 +15,170 @@ use crate::{
     NcChannel, NcChannelPair, NcColor, NcPlane, NcResult, NcStyleMask, NCRESULT_ERR, NCRESULT_OK,
 };
 
-/// Return the column at which 'cols' columns ought start in order to be aligned
+// Alpha -----------------------------------------------------------------------
-/// according to 'align' within ncplane 'n'. Returns INT_MAX on invalid 'align'.
+
-/// Undefined behavior on negative 'cols'.
+/// Gets the foreground [NcAlphaBits] from the [NcPlane], shifted to LSBs.
-//
-// NOTE: [leave cols as i32](https://github.com/dankamongmen/notcurses/issues/904)
 #[inline]
-pub fn ncplane_align(plane: &NcPlane, align: NcAlign, cols: i32) -> i32 {
+pub fn ncplane_fg_alpha(plane: &NcPlane) -> NcAlphaBits {
-    notcurses_align(ncplane_dim_x(plane), align, cols)
+    channels_fg_alpha(unsafe { ncplane_channels(plane) })
 }
 
-/// Retrieve the current contents of the cell under the cursor into 'cell'.
+/// Gets the background [NcAlphaBits] from the [NcPlane], shifted to LSBs.
-/// This cell is invalidated if the associated plane is destroyed.
+#[inline]
+pub fn ncplane_bg_alpha(plane: &NcPlane) -> NcAlphaBits {
+    channels_bg_alpha(unsafe { ncplane_channels(plane) })
+}
+
+// NcChannel -------------------------------------------------------------------
+
+/// Gets the foreground [NcChannel] from an [NcPlane].
+#[inline]
+pub fn ncplane_fchannel(plane: &NcPlane) -> NcChannel {
+    channels_fchannel(unsafe { ncplane_channels(plane) })
+}
+
+/// Gets the background [NcChannel] from an [NcPlane].
+#[inline]
+pub fn ncplane_bchannel(plane: &NcPlane) -> NcChannel {
+    channels_bchannel(unsafe { ncplane_channels(plane) })
+}
+
+// NcColor ---------------------------------------------------------------------
+
+/// Gets the foreground [NcColor] RGB components from an [NcPlane].
+#[inline]
+pub fn ncplane_fg_rgb8(
+    plane: &NcPlane,
+    red: &mut NcColor,
+    green: &mut NcColor,
+    blue: &mut NcColor,
+) -> NcChannel {
+    channels_fg_rgb8(unsafe { ncplane_channels(plane) }, red, green, blue)
+}
+
+/// Gets the background [NcColor] RGB components from an [NcPlane].
+#[inline]
+pub fn ncplane_bg_rgb8(
+    plane: &NcPlane,
+    red: &mut NcColor,
+    green: &mut NcColor,
+    blue: &mut NcColor,
+) -> NcChannel {
+    channels_bg_rgb8(unsafe { ncplane_channels(plane) }, red, green, blue)
+}
+
+// NcRgb -----------------------------------------------------------------------
+
+/// Gets the foreground [NcRgb] from an [NcPlane], shifted to LSBs.
+#[inline]
+pub fn ncplane_fg_rgb(plane: &NcPlane) -> NcChannel {
+    channels_fg_rgb(unsafe { ncplane_channels(plane) })
+}
+
+/// Gets the background [NcRgb] from an [NcPlane], shifted to LSBs.
+#[inline]
+pub fn ncplane_bg_rgb(plane: &NcPlane) -> NcChannel {
+    channels_bg_rgb(unsafe { ncplane_channels(plane) })
+}
+
+// Default ---------------------------------------------------------------------
+
+/// Is the plane's foreground using the "default foreground color"?
+#[inline]
+pub fn ncplane_fg_default_p(plane: &NcPlane) -> bool {
+    channels_fg_default_p(unsafe { ncplane_channels(plane) })
+}
+
+/// Is the plane's background using the "default background color"?
+#[inline]
+pub fn ncplane_bg_default_p(plane: &NcPlane) -> bool {
+    channels_bg_default_p(unsafe { ncplane_channels(plane) })
+}
+
+// put & print -----------------------------------------------------------------
+
+/// Calls ncplane_putc_yx() for the current cursor location.
+#[inline]
+pub fn ncplane_putc(plane: &mut NcPlane, cell: &NcCell) -> NcResult {
+    unsafe { ncplane_putc_yx(plane, -1, -1, cell) }
+}
+
+/// Calls ncplane_putchar_yx() at the current cursor location.
+#[inline]
+pub fn ncplane_putchar(plane: &mut NcPlane, c: char) -> NcResult {
+    ncplane_putchar_yx(plane, -1, -1, c)
+}
+
+/// Replaces the [NcEgc] underneath us, but retain the styling.
+/// The current styling of the plane will not be changed.
+///
+/// Replace the [NcCell] at the specified coordinates with the provided 7-bit char.
+///
+/// Advance the cursor by 1. On success, returns 1. On failure, returns -1.
+/// This works whether the underlying char is signed or unsigned.
+#[inline]
+// TODO: test char is < 8bit (currently 32bit)
+pub fn ncplane_putchar_yx(plane: &mut NcPlane, y: i32, x: i32, c: char) -> NcResult {
+    unsafe {
+        let ce = NcCell::with_all(c, ncplane_styles(plane), ncplane_channels(plane));
+        ncplane_putc_yx(plane, y, x, &ce)
+    }
+}
+
+/// Calls `ncplane_putegc()` at the current cursor location.
+#[inline]
+pub fn ncplane_putegc(plane: &mut NcPlane, gcluster: i8, sbytes: &mut i32) -> NcResult {
+    unsafe { ncplane_putegc_yx(plane, -1, -1, &gcluster, sbytes) }
+}
+
+///
+#[inline]
+pub fn ncplane_putstr(plane: &mut NcPlane, string: &str) -> NcResult {
+    unsafe {
+        ncplane_putstr_yx(
+            plane,
+            -1,
+            -1,
+            CString::new(string.as_bytes())
+                .expect("Bad string")
+                .as_ptr(),
+        )
+    }
+}
+
+///
+#[inline]
+pub fn ncplane_putnstr(plane: &mut NcPlane, size: u64, gclustarr: &[u8]) -> NcResult {
+    unsafe {
+        ncplane_putnstr_yx(
+            plane,
+            -1,
+            -1,
+            size,
+            CString::new(gclustarr).expect("Bad string").as_ptr(),
+        )
+    }
+}
+
+/// The [NcPlane] equivalent of `vprintf(3)`.
+#[inline]
+pub fn ncplane_vprintf(plane: &mut NcPlane, format: &str, ap: &mut __va_list_tag) -> NcResult {
+    unsafe {
+        ncplane_vprintf_yx(
+            plane,
+            -1,
+            -1,
+            CString::new(format).expect("Bad string").as_ptr(),
+            ap,
+        )
+    }
+}
+
+// NcCell ----------------------------------------------------------------------
+
+/// Retrieves the current contents of the [NcCell] under the cursor.
+///
+/// This NcCell is invalidated if the associated NcPlane is destroyed.
 #[inline]
 pub fn ncplane_at_cursor_cell(plane: &mut NcPlane, cell: &mut NcCell) -> NcResult {
     let mut egc = unsafe { ncplane_at_cursor(plane, &mut cell.stylemask, &mut cell.channels) };
@@ -42,7 +194,7 @@ pub fn ncplane_at_cursor_cell(plane: &mut NcPlane, cell: &mut NcCell) -> NcResul
     result
 }
 
-/// Retrieve the current contents of the specified cell into 'cell'.
+/// Retrieves the current contents of the specified cell into 'cell'.
 /// This cell is invalidated if the associated plane is destroyed.
 #[inline]
 pub fn ncplane_at_yx_cell(plane: &mut NcPlane, y: i32, x: i32, cell: &mut NcCell) -> NcResult {
@@ -59,41 +211,9 @@ pub fn ncplane_at_yx_cell(plane: &mut NcPlane, y: i32, x: i32, cell: &mut NcCell
     result
 }
 
-/// Draw a box with its upper-left corner at the current cursor position, having
+// size & alignment ------------------------------------------------------------
-/// dimensions 'ylen'x'xlen'. See ncplane_box() for more information. The
-/// minimum box size is 2x2, and it cannot be drawn off-screen.
-#[inline]
-pub fn ncplane_box_sized(
-    plane: &mut NcPlane,
-    ul: &NcCell,
-    ur: &NcCell,
-    ll: &NcCell,
-    lr: &NcCell,
-    hline: &NcCell,
-    vline: &NcCell,
-    ylen: i32,
-    xlen: i32,
-    ctlword: u32,
-) -> NcResult {
-    let (mut y, mut x) = (0, 0);
-    unsafe {
-        ncplane_cursor_yx(plane, &mut y, &mut x);
-        ncplane_box(
-            plane,
-            ul,
-            ur,
-            ll,
-            lr,
-            hline,
-            vline,
-            y + ylen - 1,
-            x + xlen - 1,
-            ctlword,
-        )
-    }
-}
 
-///
+/// Gets the columns of the [NcPlane].
 #[inline]
 pub fn ncplane_dim_x(plane: &NcPlane) -> i32 {
     unsafe {
@@ -103,7 +223,8 @@ pub fn ncplane_dim_x(plane: &NcPlane) -> i32 {
     }
 }
 
-///
+/// Gets the rows of the [NcPlane].
+#[inline]
 #[inline]
 pub fn ncplane_dim_y(plane: &NcPlane) -> i32 {
     unsafe {
@@ -113,82 +234,59 @@ pub fn ncplane_dim_y(plane: &NcPlane) -> i32 {
     }
 }
 
-///
+/// Resizes the plane, retaining what data we can (everything, unless we're
+/// shrinking in some dimension). Keep the origin where it is.
 #[inline]
-pub fn ncplane_double_box(
+pub fn ncplane_resize_simple(plane: &mut NcPlane, ylen: i32, xlen: i32) -> NcResult {
-    plane: &mut NcPlane,
+    let (mut oldy, mut oldx) = (0, 0);
-    stylemask: NcStyleMask,
-    channels: NcChannelPair,
-    ystop: i32,
-    xstop: i32,
-    ctlword: u32,
-) -> NcResult {
-    #[allow(unused_assignments)]
-    let mut ret = NCRESULT_OK;
-
-    let mut ul = NcCell::new();
-    let mut ur = NcCell::new();
-    let mut ll = NcCell::new();
-    let mut lr = NcCell::new();
-    let mut hl = NcCell::new();
-    let mut vl = NcCell::new();
-
     unsafe {
-        ret = cells_double_box(
+        ncplane_dim_yx(plane, &mut oldy, &mut oldx);
-            plane,
-            stylemask as u32,
-            channels,
-            &mut ul,
-            &mut ur,
-            &mut ll,
-            &mut lr,
-            &mut hl,
-            &mut vl,
-        );
-        if ret == NCRESULT_OK {
-            ret = ncplane_box(plane, &ul, &ur, &ll, &lr, &hl, &vl, ystop, xstop, ctlword);
     }
-
+    let keepleny = {
-        cell_release(plane, &mut ul);
+        if oldy > ylen {
-        cell_release(plane, &mut ur);
+            ylen
-        cell_release(plane, &mut ll);
+        } else {
-        cell_release(plane, &mut lr);
+            oldy
-        cell_release(plane, &mut hl);
-        cell_release(plane, &mut vl);
         }
-    ret
+    };
+    let keeplenx = {
+        if oldx > xlen {
+            xlen
+        } else {
+            oldx
+        }
+    };
+    unsafe { ncplane_resize(plane, 0, 0, keepleny, keeplenx, 0, 0, ylen, xlen) }
 }
 
-///
+/// Returns the column at which 'cols' columns ought start in order to be aligned
+/// according to 'align' within ncplane 'n'. Returns INT_MAX on invalid 'align'.
+/// Undefined behavior on negative 'cols'.
+// NOTE: Leave cols as i32. See:
+// - > https://github.com/dankamongmen/notcurses/issues/920
+// - https://github.com/dankamongmen/notcurses/issues/904
 #[inline]
-pub fn ncplane_double_box_sized(
+pub fn ncplane_align(plane: &NcPlane, align: NcAlign, cols: i32) -> i32 {
-    plane: &mut NcPlane,
+    notcurses_align(ncplane_dim_x(plane), align, cols)
-    stylemask: NcStyleMask,
-    channels: NcChannelPair,
-    ylen: i32,
-    xlen: i32,
-    ctlword: u32,
-) -> NcResult {
-    let (mut y, mut x) = (0, 0);
-    unsafe {
-        ncplane_cursor_yx(plane, &mut y, &mut x);
-    }
-    ncplane_double_box(
-        plane,
-        stylemask,
-        channels,
-        y + ylen - 1,
-        x + xlen - 1,
-        ctlword,
-    )
 }
 
+// line ------------------------------------------------------------------------
+
 /// On error, return the negative number of cells drawn.
 #[inline]
 pub fn ncplane_hline(plane: &mut NcPlane, cell: &NcCell, len: i32) -> i32 {
     unsafe { ncplane_hline_interp(plane, cell, len, cell.channels, cell.channels) }
 }
 
+///
+/// On error, return the negative number of cells drawn.
+#[inline]
+pub fn ncplane_vline(plane: &mut NcPlane, cell: &NcCell, len: i32) -> i32 {
+    unsafe { ncplane_vline_interp(plane, cell, len, cell.channels, cell.channels) }
+}
+
+// perimeter -------------------------------------------------------------------
+
 ///
 #[inline]
 pub fn ncplane_perimeter(
@@ -255,32 +353,116 @@ pub fn ncplane_perimeter_double(
         cell_release(plane, &mut hl);
         cell_release(plane, &mut vl);
     }
-    ret
+    ret
+}
+
+///
+#[inline]
+pub fn ncplane_perimeter_rounded(
+    plane: &mut NcPlane,
+    stylemask: NcStyleMask,
+    channels: NcChannelPair,
+    ctlword: u32,
+) -> NcResult {
+    if unsafe { ncplane_cursor_move_yx(plane, 0, 0) } != NCRESULT_OK {
+        return NCRESULT_ERR;
+    }
+    let (mut dimy, mut dimx) = (0, 0);
+    unsafe {
+        ncplane_dim_yx(plane, &mut dimy, &mut dimx);
+    }
+    let mut ul = NcCell::new();
+    let mut ur = NcCell::new();
+    let mut ll = NcCell::new();
+    let mut lr = NcCell::new();
+    let mut hl = NcCell::new();
+    let mut vl = NcCell::new();
+    if unsafe {
+        cells_rounded_box(
+            plane,
+            stylemask as u32,
+            channels,
+            &mut ul,
+            &mut ur,
+            &mut ll,
+            &mut lr,
+            &mut hl,
+            &mut vl,
+        )
+    } != NCRESULT_OK
+    {
+        return NCRESULT_ERR;
+    }
+    let ret = ncplane_box_sized(plane, &ul, &ur, &ll, &lr, &hl, &vl, dimy, dimx, ctlword);
+    unsafe {
+        cell_release(plane, &mut ul);
+        cell_release(plane, &mut ur);
+        cell_release(plane, &mut ll);
+        cell_release(plane, &mut lr);
+        cell_release(plane, &mut hl);
+        cell_release(plane, &mut vl);
+    }
+    ret
+}
+
+// box -------------------------------------------------------------------------
+
+/// Draw a box with its upper-left corner at the current cursor position, having
+/// dimensions 'ylen'x'xlen'. See ncplane_box() for more information. The
+/// minimum box size is 2x2, and it cannot be drawn off-screen.
+#[inline]
+pub fn ncplane_box_sized(
+    plane: &mut NcPlane,
+    ul: &NcCell,
+    ur: &NcCell,
+    ll: &NcCell,
+    lr: &NcCell,
+    hline: &NcCell,
+    vline: &NcCell,
+    ylen: i32,
+    xlen: i32,
+    ctlword: u32,
+) -> NcResult {
+    let (mut y, mut x) = (0, 0);
+    unsafe {
+        ncplane_cursor_yx(plane, &mut y, &mut x);
+        ncplane_box(
+            plane,
+            ul,
+            ur,
+            ll,
+            lr,
+            hline,
+            vline,
+            y + ylen - 1,
+            x + xlen - 1,
+            ctlword,
+        )
+    }
 }
 
 ///
 #[inline]
-pub fn ncplane_perimeter_rounded(
+pub fn ncplane_double_box(
     plane: &mut NcPlane,
     stylemask: NcStyleMask,
     channels: NcChannelPair,
+    ystop: i32,
+    xstop: i32,
     ctlword: u32,
 ) -> NcResult {
-    if unsafe { ncplane_cursor_move_yx(plane, 0, 0) } != NCRESULT_OK {
+    #[allow(unused_assignments)]
-        return NCRESULT_ERR;
+    let mut ret = NCRESULT_OK;
-    }
+
-    let (mut dimy, mut dimx) = (0, 0);
-    unsafe {
-        ncplane_dim_yx(plane, &mut dimy, &mut dimx);
-    }
     let mut ul = NcCell::new();
     let mut ur = NcCell::new();
     let mut ll = NcCell::new();
     let mut lr = NcCell::new();
     let mut hl = NcCell::new();
     let mut vl = NcCell::new();
-    if unsafe {
+
-        cells_rounded_box(
+    unsafe {
+        ret = cells_double_box(
             plane,
             stylemask as u32,
             channels,
@@ -290,13 +472,11 @@ pub fn ncplane_perimeter_rounded(
             &mut lr,
             &mut hl,
             &mut vl,
-        )
+        );
-    } != NCRESULT_OK
+        if ret == NCRESULT_OK {
-    {
+            ret = ncplane_box(plane, &ul, &ur, &ll, &lr, &hl, &vl, ystop, xstop, ctlword);
-        return NCRESULT_ERR;
         }
-    let ret = ncplane_box_sized(plane, &ul, &ur, &ll, &lr, &hl, &vl, dimy, dimx, ctlword);
+
-    unsafe {
         cell_release(plane, &mut ul);
         cell_release(plane, &mut ur);
         cell_release(plane, &mut ll);
@@ -307,219 +487,29 @@ pub fn ncplane_perimeter_rounded(
     ret
 }
 
-/// Call ncplane_putc_yx() for the current cursor location.
-#[inline]
-pub fn ncplane_putc(plane: &mut NcPlane, cell: &NcCell) -> NcResult {
-    unsafe { ncplane_putc_yx(plane, -1, -1, cell) }
-}
-
-/// Call ncplane_putchar_yx() at the current cursor location.
-#[inline]
-pub fn ncplane_putchar(plane: &mut NcPlane, c: char) -> NcResult {
-    ncplane_putchar_yx(plane, -1, -1, c)
-}
-
-/// Replace the EGC underneath us, but retain the styling. The current styling
-/// of the plane will not be changed.
-///
-/// Replace the cell at the specified coordinates with the provided 7-bit char
-/// 'c'. Advance the cursor by 1. On success, returns 1. On failure, returns -1.
-/// This works whether the underlying char is signed or unsigned.
-#[inline]
-// TODO: test char is < 8bit (currently 32bit)
-pub fn ncplane_putchar_yx(plane: &mut NcPlane, y: i32, x: i32, c: char) -> NcResult {
-    unsafe {
-        let ce = NcCell::with_all(c, ncplane_styles(plane), ncplane_channels(plane));
-        ncplane_putc_yx(plane, y, x, &ce)
-    }
-}
-
-/// Call ncplane_putegc() at the current cursor location.
-#[inline]
-pub fn ncplane_putegc(plane: &mut NcPlane, gcluster: i8, sbytes: &mut i32) -> NcResult {
-    unsafe { ncplane_putegc_yx(plane, -1, -1, &gcluster, sbytes) }
-}
-
-///
-#[inline]
-pub fn ncplane_putstr(plane: &mut NcPlane, string: &str) -> NcResult {
-    unsafe {
-        ncplane_putstr_yx(
-            plane,
-            -1,
-            -1,
-            CString::new(string.as_bytes())
-                .expect("Bad string")
-                .as_ptr(),
-        )
-    }
-}
-
-///
-#[inline]
-pub fn ncplane_putnstr(plane: &mut NcPlane, size: u64, gclustarr: &[u8]) -> NcResult {
-    unsafe {
-        ncplane_putnstr_yx(
-            plane,
-            -1,
-            -1,
-            size,
-            CString::new(gclustarr).expect("Bad string").as_ptr(),
-        )
-    }
-}
-
-/// Resize the plane, retaining what data we can (everything, unless we're
-/// shrinking in some dimension). Keep the origin where it is.
-#[inline]
-pub fn ncplane_resize_simple(plane: &mut NcPlane, ylen: i32, xlen: i32) -> NcResult {
-    let (mut oldy, mut oldx) = (0, 0);
-    unsafe {
-        ncplane_dim_yx(plane, &mut oldy, &mut oldx);
-    }
-    let keepleny = {
-        if oldy > ylen {
-            ylen
-        } else {
-            oldy
-        }
-    };
-    let keeplenx = {
-        if oldx > xlen {
-            xlen
-        } else {
-            oldx
-        }
-    };
-    unsafe { ncplane_resize(plane, 0, 0, keepleny, keeplenx, 0, 0, ylen, xlen) }
-}
-
-///
-/// On error, return the negative number of cells drawn.
-#[inline]
-pub fn ncplane_vline(plane: &mut NcPlane, cell: &NcCell, len: i32) -> i32 {
-    unsafe { ncplane_vline_interp(plane, cell, len, cell.channels, cell.channels) }
-}
-
 ///
 #[inline]
-pub fn ncplane_vprintf(plane: &mut NcPlane, format: &str, ap: &mut __va_list_tag) -> NcResult {
+pub fn ncplane_double_box_sized(
-    unsafe {
-        ncplane_vprintf_yx(
-            plane,
-            -1,
-            -1,
-            CString::new(format).expect("Bad string").as_ptr(),
-            ap,
-        )
-    }
-}
-
-/// Draw a gradient with its upper-left corner at the current cursor position,
-/// having dimensions 'ylen'x'xlen'. See ncplane_gradient for more information.
-/// static inline int
-// XXX receive cells as u32? https://github.com/dankamongmen/notcurses/issues/920
-#[inline]
-pub fn ncplane_gradient_sized(
     plane: &mut NcPlane,
-    egc: &[u8],
     stylemask: NcStyleMask,
-    ul: u64,
+    channels: NcChannelPair,
-    ur: u64,
-    ll: u64,
-    lr: u64,
     ylen: i32,
     xlen: i32,
+    ctlword: u32,
 ) -> NcResult {
-    if ylen < 1 || xlen < 1 {
-        return NCRESULT_ERR;
-    }
     let (mut y, mut x) = (0, 0);
     unsafe {
         ncplane_cursor_yx(plane, &mut y, &mut x);
-        ncplane_gradient(
+    }
+    ncplane_double_box(
         plane,
-            CString::new(egc).expect("Bad EGC").as_ptr(),
+        stylemask,
-            stylemask as u32,
+        channels,
-            ul,
-            ur,
-            ll,
-            lr,
         y + ylen - 1,
         x + xlen - 1,
+        ctlword,
     )
 }
-}
-
-/// Extract the 32-bit working foreground channel from an ncplane.
-#[inline]
-pub fn ncplane_fchannel(plane: &NcPlane) -> NcChannel {
-    channels_fchannel(unsafe { ncplane_channels(plane) })
-}
-
-/// Extract the 32-bit working background channel from an ncplane.
-#[inline]
-pub fn ncplane_bchannel(plane: &NcPlane) -> NcChannel {
-    channels_bchannel(unsafe { ncplane_channels(plane) })
-}
-
-/// Extract 24 bits of working foreground RGB from an ncplane, shifted to LSBs.
-#[inline]
-pub fn ncplane_fg_rgb(plane: &NcPlane) -> NcChannel {
-    channels_fg_rgb(unsafe { ncplane_channels(plane) })
-}
-
-/// Extract 24 bits of working background RGB from an ncplane, shifted to LSBs.
-#[inline]
-pub fn ncplane_bg_rgb(plane: &NcPlane) -> NcChannel {
-    channels_bg_rgb(unsafe { ncplane_channels(plane) })
-}
-
-/// Extract 2 bits of foreground alpha from 'struct ncplane', shifted to LSBs.
-#[inline]
-pub fn ncplane_fg_alpha(plane: &NcPlane) -> NcAlphaBits {
-    channels_fg_alpha(unsafe { ncplane_channels(plane) })
-}
-
-/// Extract 2 bits of background alpha from 'struct ncplane', shifted to LSBs.
-#[inline]
-pub fn ncplane_bg_alpha(plane: &NcPlane) -> NcAlphaBits {
-    channels_bg_alpha(unsafe { ncplane_channels(plane) })
-}
-
-/// Is the plane's foreground using the "default foreground color"?
-#[inline]
-pub fn ncplane_fg_default_p(plane: &NcPlane) -> bool {
-    channels_fg_default_p(unsafe { ncplane_channels(plane) })
-}
-
-/// Is the plane's background using the "default background color"?
-#[inline]
-pub fn ncplane_bg_default_p(plane: &NcPlane) -> bool {
-    channels_bg_default_p(unsafe { ncplane_channels(plane) })
-}
-
-/// Extract 24 bits of foreground RGB from a plane, split into components.
-#[inline]
-pub fn ncplane_fg_rgb8(
-    plane: &NcPlane,
-    red: &mut NcColor,
-    green: &mut NcColor,
-    blue: &mut NcColor,
-) -> NcChannel {
-    channels_fg_rgb8(unsafe { ncplane_channels(plane) }, red, green, blue)
-}
-
-/// Extract 24 bits of background RGB from a plane, split into components.
-#[inline]
-pub fn ncplane_bg_rgb8(
-    plane: &NcPlane,
-    red: &mut NcColor,
-    green: &mut NcColor,
-    blue: &mut NcColor,
-) -> NcChannel {
-    channels_bg_rgb8(unsafe { ncplane_channels(plane) }, red, green, blue)
-}
 
 ///
 #[inline]
@@ -590,55 +580,42 @@ pub fn ncplane_rounded_box_sized(
     )
 }
 
-// static inline int
+// gradient --------------------------------------------------------------------
-// ncplane_printf(struct ncplane* n, const char* format, ...)
+
-//   __attribute__ ((format (printf, 2, 3)));
+/// Draw a gradient with its upper-left corner at the current cursor position,
-
+/// having dimensions 'ylen'x'xlen'. See ncplane_gradient for more information.
-// static inline int
+/// static inline int
-// ncplane_printf(struct ncplane* n, const char* format, ...){
+// XXX receive cells as u32? See:
-//   va_list va;
+// - https://github.com/dankamongmen/notcurses/issues/920
-//   va_start(va, format);
+// - https://github.com/dankamongmen/notcurses/issues/904
-//   int ret = ncplane_vprintf(n, format, va);
+#[inline]
-//   va_end(va);
+pub fn ncplane_gradient_sized(
-//   return ret;
+    plane: &mut NcPlane,
-// }
+    egc: &[u8],
-
+    stylemask: NcStyleMask,
-// static inline int
+    ul: u64,
-// ncplane_printf_yx(struct ncplane* n, int y, int x, const char* format, ...)
+    ur: u64,
-//   __attribute__ ((format (printf, 4, 5)));
+    ll: u64,
-
+    lr: u64,
-// static inline int
+    ylen: i32,
-// ncplane_printf_yx(struct ncplane* n, int y, int x, const char* format, ...){
+    xlen: i32,
-//   va_list va;
+) -> NcResult {
-//   va_start(va, format);
+    if ylen < 1 || xlen < 1 {
-//   int ret = ncplane_vprintf_yx(n, y, x, format, va);
+        return NCRESULT_ERR;
-//   va_end(va);
+    }
-//   return ret;
+    let (mut y, mut x) = (0, 0);
-// }
+    unsafe {
-
+        ncplane_cursor_yx(plane, &mut y, &mut x);
-// static inline int
+        ncplane_gradient(
-// ncplane_printf_aligned(struct ncplane* n, int y, ncalign_e align,
+            plane,
-//                        const char* format, ...)
+            CString::new(egc).expect("Bad EGC").as_ptr(),
-//   __attribute__ ((format (printf, 4, 5)));
+            stylemask as u32,
-
+            ul,
-// static inline int
+            ur,
-// ncplane_printf_aligned(struct ncplane* n, int y, ncalign_e align, const char* format, ...){
+            ll,
-//   va_list va;
+            lr,
-//   va_start(va, format);
+            y + ylen - 1,
-//   int ret = ncplane_vprintf_aligned(n, y, align, format, va);
+            x + xlen - 1,
-//   va_end(va);
+        )
-//   return ret;
+    }
-// }
+}
-
-// static inline int
-// ncplane_printf_stained(struct ncplane* n, const char* format, ...)
-//   __attribute__ ((format (printf, 2, 3)));
-
-// static inline int
-// ncplane_printf_stained(struct ncplane* n, const char* format, ...){
-//   va_list va;
-//   va_start(va, format);
-//   int ret = ncplane_vprintf_stained(n, format, va);
-//   va_end(va);
-//   return ret;
-// }

rust/src/widgets/menu/methods.rs

@@ -7,6 +7,7 @@ use crate::{
     NcPlane,
 };
 
+/// # `NcMenu` Constructors
 impl NcMenu {
     /// `NcMenu` simple constructor
     pub unsafe fn new<'a>(plane: &mut NcPlane) -> &'a mut Self {
@@ -19,6 +20,7 @@ impl NcMenu {
     }
 }
 
+/// # `NcMenuOptions` Constructors
 impl NcMenuOptions {
     /// `NcMenuOptions` simple constructor
     pub fn new() -> Self {
@@ -52,6 +54,7 @@ impl NcMenuOptions {
     }
 }
 
+/// # `NcMenuItem` Constructors
 impl NcMenuItem {
     /// `NcMenuItem` simple constructor
     pub fn new(mut desc: i8, shortcut: NcInput) -> Self {
@@ -65,6 +68,7 @@ impl NcMenuItem {
     }
 }
 
+/// # `NcMenuSection` Constructors
 impl NcMenuSection {
     /// `NcMenuSection` simple constructor
     pub fn new(name: &str, itemcount: i32, items: &mut [NcMenuItem], shortcut: NcInput) -> Self {

rust/src/widgets/reader/methods.rs

@@ -2,6 +2,7 @@
 
 use crate::{ncreader_create, NcPlane, NcReader, NcReaderOptions};
 
+/// # `NcReader` Constructors
 impl NcReader {
     /// `NcReader` simple constructor
     pub unsafe fn new<'a>(plane: &mut NcPlane) -> &'a mut Self {
@@ -14,6 +15,7 @@ impl NcReader {
     }
 }
 
+/// # `NcReaderOptions` Constructors
 impl NcReaderOptions {
     /// `NcReaderOptions` simple constructor
     pub fn new() -> Self {