[rust] rename several constructor methods

For semantic consistency with the Rust API guidelines.

- rename most `NcChannel` & `NcCell` methods starting with `with_`* to `from_`*.
- update examples.

rust/examples/direct-cursor.rs

@@ -17,7 +17,7 @@ fn main() -> NcResult<()> {
     println!("terminal size (rows, cols): {}, {}", rows, cols);
 
     let mut channels =
-        NcChannelPair::combine(NcChannel::with_rgb(0xAA2244), NcChannel::with_rgb(0x112233));
+        NcChannelPair::combine(NcChannel::from_rgb(0xAA2244), NcChannel::from_rgb(0x112233));
     dm.putstr(channels, "The current coordinates are")?;
 
     for _n in 0..40 {

rust/examples/full-planes.rs

@@ -11,18 +11,18 @@ fn main() -> NcResult<()> {
     assert_eq![(t_rows, t_cols), stdplane.dim_yx()];
 
     // set the standard plane's base cell's foreground and background colors
-    let channels = NcChannelPair::with_rgb(0x88aa00, 0x222288);
+    let channels = NcChannelPair::from_rgb(0x88aa00, 0x222288);
     stdplane.set_base("x", 0, channels)?;
     rsleep![&mut nc, 0, 500];
 
     // add a green plane to the stdplane's pile
     let plane_green = NcPlane::new_bound(&mut stdplane, 0, 0, 16, 30)?;
-    plane_green.set_base("·", 0, NcChannelPair::with_rgb(0x224411, 0x229922))?;
+    plane_green.set_base("·", 0, NcChannelPair::from_rgb(0x224411, 0x229922))?;
     rsleep![&mut nc, 0, 800];
 
     // add a smaller red plane, a bit displaced to the bottom right
     let plane_red = NcPlane::new_bound(&mut stdplane, 8, 12, 10, 20)?;
-    plane_red.set_base("~", 0, NcChannelPair::with_rgb(0xaadd2b, 0x882222))?;
+    plane_red.set_base("~", 0, NcChannelPair::from_rgb(0xaadd2b, 0x882222))?;
     rsleep![&mut nc, 0, 800];
 
     // write something

rust/examples/poc-menu.rs

@@ -44,7 +44,7 @@ fn main() -> NcResult<()> {
     menu_top.item_set_status("Schwarzgerät", "Disabled", false)?;
     menu_top.item_set_status("Schwarzgerät", "Restart", false)?;
 
-    stdplane.set_base("x", 0, NcChannelPair::with_rgb(0x88aa00, 0x000088))?;
+    stdplane.set_base("x", 0, NcChannelPair::from_rgb(0x88aa00, 0x000088))?;
 
     nc.render()?;
 

rust/src/cells/methods.rs

@@ -10,10 +10,10 @@ use crate::NcChannel;
 
 /// # NcCell constructors
 impl NcCell {
-    /// New NcCell, expects a 7-bit [char].
+    /// New `NcCell`, expects a 7-bit [`char`].
     #[inline]
     #[allow(clippy::unnecessary_cast)]
-    pub const fn with_char7b(ch: char) -> Self {
+    pub const fn from_char7b(ch: char) -> Self {
         NcCell {
             gcluster: (ch as u32).to_le(),
             gcluster_backstop: 0 as NcEgcBackstop,
@@ -23,31 +23,31 @@ impl NcCell {
         }
     }
 
-    /// New NcCell, expects an [NcPlane] and a [char].
+    /// New `NcCell`, expects an [`NcPlane`] and a [`char`].
     #[inline]
-    pub fn with_char(ch: char, plane: &mut NcPlane) -> Self {
+    pub fn from_char(ch: char, plane: &mut NcPlane) -> Self {
         let mut cell = Self::new();
         let result = unsafe { nccell_load(plane, &mut cell, cstring![ch.to_string()]) };
         debug_assert_ne![NCRESULT_ERR, result];
         cell
     }
 
-    /// New NcCell, expects an [NcPlane] and a &[str].
+    /// New `NcCell`, expects an [`NcPlane`] and a &[`str`].
     #[inline]
-    pub fn with_str(plane: &mut NcPlane, string: &str) -> Self {
+    pub fn from_str(plane: &mut NcPlane, string: &str) -> Self {
         let mut cell = Self::new();
         let result = unsafe { nccell_load(plane, &mut cell, cstring![string]) };
         debug_assert_ne![NCRESULT_ERR, result];
         cell
     }
 
-    /// New empty NcCell.
+    /// New empty `NcCell`.
     #[inline]
     pub const fn new() -> Self {
-        Self::with_char7b(0 as char)
+        Self::from_char7b(0 as char)
     }
 
-    /// Breaks the UTF-8 string in `egc` down, setting up this NcCell,
+    /// Breaks the UTF-8 string in `egc` down, setting up this `NcCell`,
     /// and returns the number of bytes copied out of `egc`.
     ///
     /// The styling of the cell is left untouched, but any resources are released.
@@ -81,7 +81,7 @@ impl NcCell {
         error![bytes, "", bytes as u32]
     }
 
-    /// Duplicate this NcCell into another one.
+    /// Duplicate this `NcCell` into another one.
     ///
     /// Both must be or will be bound to `common_plane`.
     ///
@@ -90,7 +90,7 @@ impl NcCell {
         error![unsafe { crate::nccell_duplicate(common_plane, target, self) }]
     }
 
-    /// Initializes (zeroes out) the NcCell.
+    /// Initializes (zeroes out) this `NcCell`.
     ///
     /// *C style function: [nccell_init()][crate::nccell_init].*
     #[inline]
@@ -111,7 +111,7 @@ impl NcCell {
 // -----------------------------------------------------------------------------
 /// ## NcCell methods: bg|fg `NcChannel`s manipulation.
 impl NcCell {
-    /// Returns the [`NcChannelPair`] of the NcCell.
+    /// Returns the [`NcChannelPair`] of this `NcCell`.
     ///
     /// *(No equivalent C style function)*
     pub fn channels(&mut self, plane: &mut NcPlane) -> NcChannelPair {

rust/src/cells/test/methods.rs

@@ -8,11 +8,11 @@ use serial_test::serial;
 #[serial]
 fn constructors() -> crate::NcResult<()> {
     let _c1 = NcCell::new();
-    let _c2 = NcCell::with_char7b('C');
+    let _c2 = NcCell::from_char7b('C');
 
     let nc = Nc::new()?;
     let plane = NcPlane::new(nc, 0, 0, 10, 10)?;
-    let _c3 = NcCell::with_char('௵', plane);
+    let _c3 = NcCell::from_char('௵', plane);
     nc.stop()?;
     Ok(())
 }

rust/src/channel/methods.rs

@@ -8,10 +8,10 @@ pub trait NcChannelMethods {
     // constructors
     fn new() -> Self;
     fn with_default() -> Self;
-    fn with_rgb(rgb: NcRgb) -> Self;
+    fn from_rgb(rgb: NcRgb) -> Self;
-    fn with_rgb_alpha(rgb: NcRgb, alpha: NcAlphaBits) -> Self;
+    fn from_rgb_alpha(rgb: NcRgb, alpha: NcAlphaBits) -> Self;
-    fn with_rgb8(r: NcComponent, g: NcComponent, b: NcComponent) -> Self;
+    fn from_rgb8(r: NcComponent, g: NcComponent, b: NcComponent) -> Self;
-    fn with_rgb8_alpha(r: NcComponent, g: NcComponent, b: NcComponent, alpha: NcAlphaBits) -> Self;
+    fn from_rgb8_alpha(r: NcComponent, g: NcComponent, b: NcComponent, alpha: NcAlphaBits) -> Self;
 
     // methods
     fn fcombine(&self, bchannel: NcChannel) -> NcChannelPair;
@@ -46,16 +46,16 @@ pub trait NcChannelPairMethods {
     // constructors
     fn new() -> Self;
     fn with_default() -> Self;
-    fn with_rgb(fg_rgb: NcRgb, bg_rgb: NcRgb) -> Self;
+    fn from_rgb(fg_rgb: NcRgb, bg_rgb: NcRgb) -> Self;
-    fn with_rgb_both(rgb: NcRgb) -> Self;
+    fn from_rgb_both(rgb: NcRgb) -> Self;
-    fn with_rgb_alpha(
+    fn from_rgb_alpha(
         fg_rgb: NcRgb,
         fg_alpha: NcAlphaBits,
         bg_rgb: NcRgb,
         bg_alpha: NcAlphaBits,
     ) -> Self;
-    fn with_rgb_alpha_both(rgb: NcRgb, alpha: NcAlphaBits) -> Self;
+    fn from_rgb_alpha_both(rgb: NcRgb, alpha: NcAlphaBits) -> Self;
-    fn with_rgb8(
+    fn from_rgb8(
         fg_r: NcComponent,
         fg_g: NcComponent,
         fg_b: NcComponent,
@@ -63,8 +63,8 @@ pub trait NcChannelPairMethods {
         bg_g: NcComponent,
         bg_b: NcComponent,
     ) -> Self;
-    fn with_rgb8_both(r: NcComponent, g: NcComponent, b: NcComponent) -> Self;
+    fn from_rgb8_both(r: NcComponent, g: NcComponent, b: NcComponent) -> Self;
-    fn with_rgb8_alpha(
+    fn from_rgb8_alpha(
         fg_r: NcComponent,
         fg_g: NcComponent,
         fg_b: NcComponent,
@@ -74,7 +74,7 @@ pub trait NcChannelPairMethods {
         bg_b: NcComponent,
         bg_alpha: NcAlphaBits,
     ) -> Self;
-    fn with_rgb8_alpha_both(
+    fn from_rgb8_alpha_both(
         r: NcComponent,
         g: NcComponent,
         b: NcComponent,
@@ -148,22 +148,22 @@ impl NcChannelMethods for NcChannel {
     }
 
     /// New NcChannel, expects [`NcRgb`].
-    fn with_rgb(rgb: NcRgb) -> Self {
+    fn from_rgb(rgb: NcRgb) -> Self {
         Self::new().set(rgb)
     }
 
     /// New NcChannel, expects [`NcRgb`] & [`NcAlphaBits`].
-    fn with_rgb_alpha(rgb: NcRgb, alpha: NcAlphaBits) -> Self {
+    fn from_rgb_alpha(rgb: NcRgb, alpha: NcAlphaBits) -> Self {
         Self::new().set(rgb).set_alpha(alpha)
     }
 
     /// New NcChannel, expects three RGB [`NcComponent`] components.
-    fn with_rgb8(r: NcComponent, g: NcComponent, b: NcComponent) -> Self {
+    fn from_rgb8(r: NcComponent, g: NcComponent, b: NcComponent) -> Self {
         Self::new().set_rgb8(r, g, b)
     }
 
     /// New NcChannel, expects three RGB [`NcComponent`] components & [`NcAlphaBits`].
-    fn with_rgb8_alpha(r: NcComponent, g: NcComponent, b: NcComponent, alpha: NcAlphaBits) -> Self {
+    fn from_rgb8_alpha(r: NcComponent, g: NcComponent, b: NcComponent, alpha: NcAlphaBits) -> Self {
         Self::new().set_rgb8(r, g, b).set_alpha(alpha)
     }
 
@@ -367,39 +367,39 @@ impl NcChannelPairMethods for NcChannelPair {
 
     /// New NcChannel, expects two separate [`NcRgb`]s for the foreground
     /// and background channels.
-    fn with_rgb(fg_rgb: NcRgb, bg_rgb: NcRgb) -> Self {
+    fn from_rgb(fg_rgb: NcRgb, bg_rgb: NcRgb) -> Self {
-        Self::combine(NcChannel::with_rgb(fg_rgb), NcChannel::with_rgb(bg_rgb))
+        Self::combine(NcChannel::from_rgb(fg_rgb), NcChannel::from_rgb(bg_rgb))
     }
 
     /// New NcChannelPair, expects a single [`NcRgb`] for both foreground
     /// and background channels.
-    fn with_rgb_both(rgb: NcRgb) -> Self {
+    fn from_rgb_both(rgb: NcRgb) -> Self {
         let channel = NcChannel::new().set(rgb);
         Self::combine(channel, channel)
     }
 
     /// New NcChannel, expects two separate [`NcRgb`] & [`NcAlphaBits`] for the
     /// foreground and background channels.
-    fn with_rgb_alpha(
+    fn from_rgb_alpha(
         fg_rgb: NcRgb,
         fg_alpha: NcAlphaBits,
         bg_rgb: NcRgb,
         bg_alpha: NcAlphaBits,
     ) -> Self {
         Self::combine(
-            NcChannel::with_rgb(fg_rgb).set_alpha(fg_alpha),
+            NcChannel::from_rgb(fg_rgb).set_alpha(fg_alpha),
-            NcChannel::with_rgb(bg_rgb).set_alpha(bg_alpha),
+            NcChannel::from_rgb(bg_rgb).set_alpha(bg_alpha),
         )
     }
 
     /// New NcChannel, expects [`NcRgb`] & [`NcAlphaBits`] for both channels.
-    fn with_rgb_alpha_both(rgb: NcRgb, alpha: NcAlphaBits) -> Self {
+    fn from_rgb_alpha_both(rgb: NcRgb, alpha: NcAlphaBits) -> Self {
         let channel = NcChannel::new().set(rgb).set_alpha(alpha);
         Self::combine(channel, channel)
     }
 
     /// New NcChannelPair, expects three RGB [`NcComponent`] components for each channel.
-    fn with_rgb8(
+    fn from_rgb8(
         fg_r: NcComponent,
         fg_g: NcComponent,
         fg_b: NcComponent,
@@ -408,21 +408,21 @@ impl NcChannelPairMethods for NcChannelPair {
         bg_b: NcComponent,
     ) -> Self {
         Self::combine(
-            NcChannel::with_rgb8(fg_r, fg_g, fg_b),
+            NcChannel::from_rgb8(fg_r, fg_g, fg_b),
-            NcChannel::with_rgb8(bg_r, bg_g, bg_b),
+            NcChannel::from_rgb8(bg_r, bg_g, bg_b),
         )
     }
 
     /// New NcChannelPair, expects three RGB [`NcComponent`] components for both
     /// the foreground and background channels.
-    fn with_rgb8_both(r: NcComponent, g: NcComponent, b: NcComponent) -> Self {
+    fn from_rgb8_both(r: NcComponent, g: NcComponent, b: NcComponent) -> Self {
         let channel = NcChannel::new().set_rgb8(r, g, b);
         Self::combine(channel, channel)
     }
 
     /// New NcChannelPair, expects three RGB [`NcComponent`] components & [`NcAlphaBits`]
     /// for both foreground and background channels.
-    fn with_rgb8_alpha(
+    fn from_rgb8_alpha(
         fg_r: NcComponent,
         fg_g: NcComponent,
         fg_b: NcComponent,
@@ -433,13 +433,13 @@ impl NcChannelPairMethods for NcChannelPair {
         bg_alpha: NcAlphaBits,
     ) -> Self {
         Self::combine(
-            NcChannel::with_rgb8_alpha(fg_r, fg_g, fg_b, fg_alpha),
+            NcChannel::from_rgb8_alpha(fg_r, fg_g, fg_b, fg_alpha),
-            NcChannel::with_rgb8_alpha(bg_r, bg_g, bg_b, bg_alpha),
+            NcChannel::from_rgb8_alpha(bg_r, bg_g, bg_b, bg_alpha),
         )
     }
 
     /// New NcChannel, expects three RGB [`NcComponent`] components.
-    fn with_rgb8_alpha_both(
+    fn from_rgb8_alpha_both(
         r: NcComponent,
         g: NcComponent,
         b: NcComponent,

rust/src/plane/reimplemented.rs

@@ -207,7 +207,7 @@ pub fn ncplane_putc(plane: &mut NcPlane, cell: &NcCell) -> NcIntResult {
 #[inline]
 pub fn ncplane_putchar(plane: &mut NcPlane, ch: char) -> NcIntResult {
     unsafe {
-        let cell = NcCell::with_char(ch, plane);
+        let cell = NcCell::from_char(ch, plane);
         crate::ncplane_putc_yx(plane, -1, -1, &cell)
     }
 }
@@ -219,7 +219,7 @@ pub fn ncplane_putchar(plane: &mut NcPlane, ch: char) -> NcIntResult {
 #[inline]
 pub fn ncplane_putchar_yx(plane: &mut NcPlane, y: NcDim, x: NcDim, ch: char) -> NcIntResult {
     unsafe {
-        let cell = NcCell::with_char(ch, plane);
+        let cell = NcCell::from_char(ch, plane);
         crate::ncplane_putc_yx(plane, y as i32, x as i32, &cell)
     }
 }