rust: add missing functions & constants; refactor

- implement methods for ncplane_resize_marginalized & notcurses_debug_caps.
- add constants NCPLANE_OPTION_MARGINALIZED & NCPLANE_OPTION_VERALIGNED.
- signature updates for NcChannel* & NcPixel trait methods.
- minor improvements.

rust/src/bindings.rs

@@ -322,6 +322,8 @@ pub use ffi::{
 //
 // // constants
 // NCPLANE_OPTION_HORALIGNED,
+// NCPLANE_OPTION_MARGINALIZED,
+// NCPLANE_OPTION_VERALIGNED
 
 #[doc(inline)]
 pub use ffi::{
@@ -389,6 +391,7 @@ pub use ffi::{
     ncplane_reparent,
     ncplane_reparent_family,
     ncplane_resize,
+    ncplane_resize_marginalized,
     ncplane_resize_maximize,
     ncplane_resize_realign,
     ncplane_resizecb,
@@ -712,6 +715,7 @@ pub use ffi::{
     notcurses_cursor_disable,
     notcurses_cursor_enable,
     notcurses_debug,
+    notcurses_debug_caps,
     notcurses_drop_planes,
     notcurses_getc,
     notcurses_init,

rust/src/channel/methods.rs

@@ -26,15 +26,15 @@ pub trait NcChannelMethods {
     fn r(&self) -> NcColor;
     fn g(&self) -> NcColor;
     fn b(&self) -> NcColor;
-    fn set_r(&mut self, r: NcColor) -> NcChannel;
-    fn set_g(&mut self, g: NcColor) -> NcChannel;
-    fn set_b(&mut self, b: NcColor) -> NcChannel;
+    fn set_r(&mut self, r: NcColor) -> Self;
+    fn set_g(&mut self, g: NcColor) -> Self;
+    fn set_b(&mut self, b: NcColor) -> Self;
 
     fn rgb(&self) -> NcRgb;
     fn set_rgb(&mut self, rgb: NcRgb) -> Self;
 
     fn default_p(&self) -> bool;
-    fn set_default(&mut self) -> NcChannel;
+    fn set_default(&mut self) -> Self;
 
     fn palindex_p(&self) -> bool;
 }
@@ -75,7 +75,7 @@ pub trait NcChannelPairMethods {
     fn with_rgb8_alpha_both(r: NcColor, g: NcColor, b: NcColor, alpha: NcAlphaBits) -> Self;
 
     // methods
-    fn combine(fchannel: NcChannel, bchannel: NcChannel) -> NcChannelPair;
+    fn combine(fchannel: NcChannel, bchannel: NcChannel) -> Self;
 
     fn fchannel(&self) -> NcChannel;
     fn bchannel(&self) -> NcChannel;
@@ -122,7 +122,7 @@ pub trait NcChannelPairMethods {
 
 // NcChannel -------------------------------------------------------------------
 
-/// # `NcChannel` Methods
+/// # NcChannel Methods
 impl NcChannelMethods for NcChannel {
     // Constructors
 
@@ -252,7 +252,7 @@ impl NcChannelMethods for NcChannel {
     /// *C style function: [channel_set_r()][crate::channel_set_r].*
     //
     // Not in the C API
-    fn set_r(&mut self, r: NcColor) -> NcChannel {
+    fn set_r(&mut self, r: NcColor) -> Self {
         crate::channel_set_r(self, r)
     }
 
@@ -261,7 +261,7 @@ impl NcChannelMethods for NcChannel {
     /// *C style function: [channel_set_g()][crate::channel_set_g].*
     //
     // Not in the C API
-    fn set_g(&mut self, g: NcColor) -> NcChannel {
+    fn set_g(&mut self, g: NcColor) -> Self {
         crate::channel_set_g(self, g)
     }
 
@@ -270,7 +270,7 @@ impl NcChannelMethods for NcChannel {
     /// *C style function: [channel_set_b()][crate::channel_set_b].*
     //
     // Not in the C API
-    fn set_b(&mut self, b: NcColor) -> NcChannel {
+    fn set_b(&mut self, b: NcColor) -> Self {
         crate::channel_set_b(self, b)
     }
 
@@ -306,7 +306,7 @@ impl NcChannelMethods for NcChannel {
     /// Marks an NcChannel as using its "default color", which also marks it opaque.
     ///
     /// *C style function: [channel_set_default()][crate::channel_set_default].*
-    fn set_default(&mut self) -> NcChannel {
+    fn set_default(&mut self) -> Self {
         crate::channel_set_default(self)
     }
 
@@ -322,7 +322,7 @@ impl NcChannelMethods for NcChannel {
 
 // NcChannelPair ---------------------------------------------------------------
 
-/// # `NcChannelPair` Methods
+/// # NcChannelPair Methods
 impl NcChannelPairMethods for NcChannelPair {
     // Constructors
 
@@ -423,7 +423,7 @@ impl NcChannelPairMethods for NcChannelPair {
     /// Combines two [NcChannel]s into an [NcChannelPair].
     ///
     /// *C style function: [channels_combine()][crate::channels_combine].*
-    fn combine(fchannel: NcChannel, bchannel: NcChannel) -> NcChannelPair {
+    fn combine(fchannel: NcChannel, bchannel: NcChannel) -> Self {
         crate::channels_combine(fchannel, bchannel)
     }
 
@@ -446,14 +446,14 @@ impl NcChannelPairMethods for NcChannelPair {
     /// Sets the foreground [NcChannel].
     ///
     /// *C style function: [channels_set_fchannel()][crate::channels_set_fchannel].*
-    fn set_fchannel(&mut self, fchannel: NcChannel) -> NcChannelPair {
+    fn set_fchannel(&mut self, fchannel: NcChannel) -> Self {
         crate::channels_set_fchannel(self, fchannel)
     }
 
     /// Sets the background [NcChannel].
     ///
     /// *C style function: [channels_set_bchannel()][crate::channels_set_bchannel].*
-    fn set_bchannel(&mut self, bchannel: NcChannel) -> NcChannelPair {
+    fn set_bchannel(&mut self, bchannel: NcChannel) -> Self {
         crate::channels_set_bchannel(self, bchannel)
     }
 
@@ -543,7 +543,7 @@ impl NcChannelPairMethods for NcChannelPair {
     /// marks the foreground [NcChannel] as not using the "default color".
     ///
     /// *C style function: [channels_set_fg_rgb8()][crate::channels_set_fg_rgb8].*
-    fn set_fg_rgb8(&mut self, r: NcColor, g: NcColor, b: NcColor) -> NcChannelPair {
+    fn set_fg_rgb8(&mut self, r: NcColor, g: NcColor, b: NcColor) -> Self {
         crate::channels_set_fg_rgb8(self, r, g, b)
     }
 
@@ -551,7 +551,7 @@ impl NcChannelPairMethods for NcChannelPair {
     /// marks the background [NcChannel] as not using the "default color".
     ///
     /// *C style function: [channels_set_bg_rgb8()][crate::channels_set_bg_rgb8].*
-    fn set_bg_rgb8(&mut self, r: NcColor, g: NcColor, b: NcColor) -> NcChannelPair {
+    fn set_bg_rgb8(&mut self, r: NcColor, g: NcColor, b: NcColor) -> Self {
         crate::channels_set_bg_rgb8(self, r, g, b)
     }
 
@@ -600,7 +600,7 @@ impl NcChannelPairMethods for NcChannelPair {
     /// Sets the foreground red [NcColor], and returns the new NcChannelPair.
     ///
     /// *(No equivalent C style function)*
-    fn fg_set_r(&mut self, r: NcColor) -> NcChannelPair {
+    fn fg_set_r(&mut self, r: NcColor) -> Self {
         let (_, g, b) = self.bg_rgb8();
         crate::channels_set_fg_rgb8(self, r, g, b)
     }
@@ -608,7 +608,7 @@ impl NcChannelPairMethods for NcChannelPair {
     /// Sets the foreground green [NcColor], and returns the new NcChannelPair.
     ///
     /// *(No equivalent C style function)*
-    fn fg_set_g(&mut self, g: NcColor) -> NcChannelPair {
+    fn fg_set_g(&mut self, g: NcColor) -> Self {
         let (r, _, b) = self.bg_rgb8();
         crate::channels_set_fg_rgb8(self, r, g, b)
     }
@@ -616,7 +616,7 @@ impl NcChannelPairMethods for NcChannelPair {
     /// Sets the foreground blue [NcColor], and returns the new NcChannelPair.
     ///
     /// *(No equivalent C style function)*
-    fn fg_set_b(&mut self, b: NcColor) -> NcChannelPair {
+    fn fg_set_b(&mut self, b: NcColor) -> Self {
         let (r, g, _) = self.bg_rgb8();
         crate::channels_set_fg_rgb8(self, r, g, b)
     }
@@ -624,7 +624,7 @@ impl NcChannelPairMethods for NcChannelPair {
     /// Sets the background red [NcColor], and returns the new NcChannelPair.
     ///
     /// *(No equivalent C style function)*
-    fn bg_set_r(&mut self, r: NcColor) -> NcChannelPair {
+    fn bg_set_r(&mut self, r: NcColor) -> Self {
         let (_, g, b) = self.bg_rgb8();
         crate::channels_set_bg_rgb8(self, r, g, b)
     }
@@ -632,7 +632,7 @@ impl NcChannelPairMethods for NcChannelPair {
     /// Sets the background green [NcColor], and returns the new NcChannelPair.
     ///
     /// *(No equivalent C style function)*
-    fn bg_set_g(&mut self, g: NcColor) -> NcChannelPair {
+    fn bg_set_g(&mut self, g: NcColor) -> Self {
         let (r, _, b) = self.bg_rgb8();
         crate::channels_set_bg_rgb8(self, r, g, b)
     }
@@ -640,7 +640,7 @@ impl NcChannelPairMethods for NcChannelPair {
     /// Sets the background blue [NcColor], and returns the new NcChannelPair.
     ///
     /// *(No equivalent C style function)*
-    fn bg_set_b(&mut self, b: NcColor) -> NcChannelPair {
+    fn bg_set_b(&mut self, b: NcColor) -> Self {
         let (r, g, _) = self.bg_rgb8();
         crate::channels_set_bg_rgb8(self, r, g, b)
     }
@@ -668,7 +668,7 @@ impl NcChannelPairMethods for NcChannelPair {
     /// returns the new [NcChannelPair].
     ///
     /// *C style function: [channels_set_fg_default()][crate::channels_set_fg_default].*
-    fn set_fg_default(&mut self) -> NcChannelPair {
+    fn set_fg_default(&mut self) -> Self {
         crate::channels_set_fg_default(self)
     }
 
@@ -676,7 +676,7 @@ impl NcChannelPairMethods for NcChannelPair {
     /// returns the new [NcChannelPair].
     ///
     /// *C style function: [channels_set_bg_default()][crate::channels_set_bg_default].*
-    fn set_bg_default(&mut self) -> NcChannelPair {
+    fn set_bg_default(&mut self) -> Self {
         crate::channels_set_bg_default(self)
     }
 

rust/src/notcurses/methods.rs

@@ -278,6 +278,17 @@ impl Notcurses {
         }
     }
 
+    /// Dumps selected configuration capabilities to 'debugfp'.
+    ///
+    /// Output is freeform, and subject to change.
+    ///
+    /// *C style function: [notcurses_debug_caps()][crate::notcurses_debug_caps].*
+    pub fn debug_caps(&self, debugfp: &mut NcFile) {
+        unsafe {
+            crate::notcurses_debug_caps(self, debugfp.as_nc_ptr());
+        }
+    }
+
     /// Destroys all [NcPlane]s other than the stdplane.
     ///
     /// *C style function: [notcurses_drop_planes()][crate::notcurses_drop_planes].*

rust/src/notcurses/mod.rs

@@ -1,7 +1,7 @@
 //! `Notcurses`
 
 // --- -------------------------------------------------------------------------
-// col 0:
+// col 0:   3
 // --------------
 //          1  X: wont do
 //          2  ~: WIP
@@ -12,14 +12,14 @@
 //             F: ffi function wrapped safely
 //          6  r: static function reimplemented in Rust
 //
-// col 2:  46
+// col 2:  48
 // --------------
-//         39  m: impl as a `Notcurses` method
-//          7  M: impl for the `FullMode` wrapper struct too
+//         38  m: impl as a `Notcurses` method
+//         10  M: impl for the `FullMode` wrapper struct too
 //
-// col 3:  14
+// col 3:  13
 // --------------
-//         14  t: tests done for the ffi or reimplemented funtion
+//         13  t: tests done for the ffi or reimplemented funtion
 //             T: tests done also for the m method
 //             Ŧ: tests done also for the M method wrapper struct
 // --- -------------------------------------------------------------------------
@@ -39,6 +39,7 @@
 // fm  notcurses_cursor_disable
 // fm  notcurses_cursor_enable
 // fmt notcurses_debug
+// fm  notcurses_debug_caps
 // fmt notcurses_drop_planes
 // fm  notcurses_getc
 // fMt notcurses_init

rust/src/pixel.rs

@@ -121,7 +121,7 @@ pub fn ncpixel_set_rgb8(pixel: &mut NcPixel, red: NcColor, green: NcColor, blue:
 // NOTE: waiting for: https://github.com/rust-lang/rust/issues/56546
 // to move doc comments to the trait and appear unhidden at the implementation.
 pub trait NcPixelMethods {
-    fn new(r: NcColor, g: NcColor, b: NcColor) -> NcPixel;
+    fn new(r: NcColor, g: NcColor, b: NcColor) -> Self;
     fn a(self) -> NcColor;
     fn b(self) -> NcColor;
     fn g(self) -> NcColor;
@@ -135,7 +135,7 @@ pub trait NcPixelMethods {
 
 impl NcPixelMethods for NcPixel {
     /// Constructs a libav-compatible ABGR pixel from [NcColor] RGB components.
-    fn new(red: NcColor, green: NcColor, blue: NcColor) -> NcPixel {
+    fn new(red: NcColor, green: NcColor, blue: NcColor) -> Self {
         ncpixel(red, green, blue)
     }
 

rust/src/plane/methods.rs

@@ -1382,6 +1382,20 @@ impl NcPlane {
         ]
     }
 
+    /// Suitable for use as a 'resizecb' with planes created with
+    /// [`NCPLANE_OPTION_MARGINALIZED`][crate::NCPLANE_OPTION_MARGINALIZED].
+    ///
+    /// This will resize this plane against its parent, attempting to enforce
+    /// the supplied margins.
+    ///
+    /// *C style function: [ncplane_resize_marginalized()][crate::ncplane_resize_marginalized].*
+    pub fn resize_marginalized(&mut self) -> NcResult<()> {
+        error![
+            unsafe { crate::ncplane_resize_marginalized(self) },
+            "NcPlane.resize_marginalized()"
+        ]
+    }
+
     /// Suitable for use as a 'resizecb', this will resize the plane
     /// to the visual region's size. It is used for the standard plane.
     ///

rust/src/plane/mod.rs

@@ -1,11 +1,11 @@
 //! `NcPlane`
 
-// functions already exported by bindgen : 108 (5 + 103)
-// -----------------------------------------------------
+// functions already exported by bindgen : 112
+// -------------------------------------------
 // (X) wont:  6
 // (D) depr:  4
 // (#) test: 13
-// (W) wrap: 81 of 101 (111 - 6 - 4)
+// (W) wrap: 82 of 102 (112 - 6 - 4)
 // -------------------------------------------
 //W  ncpile_bottom
 //W# ncpile_create
@@ -77,6 +77,7 @@
 //W  ncplane_reparent_family
 //W# ncplane_resize
 //W  ncplane_resizecb
+//W  ncplane_resize_marginalize
 //W  ncplane_resize_maximize
 //W  ncplane_resize_realign
 //W  ncplane_rgba
@@ -243,9 +244,22 @@ pub type NcPlane = crate::bindings::ffi::ncplane;
 /// Options struct for [`NcPlane`]
 pub type NcPlaneOptions = crate::bindings::ffi::ncplane_options;
 
-/// Horizontal alignment relative to the parent plane. Set alignment in 'x'.
+/// Horizontal alignment relative to the parent plane. Use NcAlign for 'x'.
 pub const NCPLANE_OPTION_HORALIGNED: u64 = crate::bindings::ffi::NCPLANE_OPTION_HORALIGNED as u64;
 
+/// Vertical alignment relative to the parent plane. Use NcAlign for 'y'.
+pub const NCPLANE_OPTION_VERALIGNED: u64 = crate::bindings::ffi::NCPLANE_OPTION_VERALIGNED as u64;
+
+/// Maximize relative to the parent plane, modulo the provided margins.
+///
+/// The margins are best-effort; the plane will always be at least 1 column by
+/// 1 row. If the margins can be effected, the plane will be sized to all
+/// remaining space. 'y' and 'x' are overloaded as the top and left margins
+/// when this flag is used. 'rows' and 'cols' must be 0 when this flag is
+/// used. This flag is exclusive with both of the alignment flags.
+pub const NCPLANE_OPTION_MARGINALIZED: u64 =
+    crate::bindings::ffi::NCPLANE_OPTION_MARGINALIZED as u64;
+
 /// I/O wrapper to dump file descriptor to [`NcPlane`]
 ///
 /// `type in C: ncfdplane (struct)`