rust: continue improving bindings and API

- use libc types and functions directly when possible
	- char32_t -> u32 -> char
	- size_t -> u64
	- free()
	- strcmp()
	NOTE: it seems libc::timespec doesn't work with notcurses_getc()
- rename types
  	- Input -> NcInput
	- Scale -> NcScale
- `suppuabize` function is now private.
- `bindings` module is now public.
- improve comments.

rust/src/bindings.rs

@@ -1,6 +1,8 @@
+//! bindgen generated bindings
+//!
 //
 // WARNING: DO NOT EXECUTE RUSTFMT ON THIS FILE.
-// Custom formatting is important for maintenance.
+// Custom formatting permits easier maintenance.
 //
 
 #![allow(dead_code)]
@@ -11,14 +13,13 @@ mod bindings {
     include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
 }
 
-// Miscellaneous type definitions and constants -------------------------------------------
+// Miscellaneous ---------------------------------------------------------------
 pub use bindings::{
+    // structs
     __va_list_tag,
     _IO_FILE,
-    char32_t, // TODO: remove & use u32
+
-    free,
+    // functions
-    size_t,
-    strcmp,
     timespec,
 };
 
@@ -607,5 +608,3 @@ pub use bindings::{
     sigprocmask,
     sigsuspend,
 };
-
-

rust/src/cells.rs

@@ -56,6 +56,8 @@
 //+ cell_wide_left_p
 //+ cell_wide_right_p
 
+use libc::strcmp;
+
 use crate as nc;
 use nc::types::{
     AlphaBits, Cell, CellGcluster, Channel, ChannelPair, Color, IntResult, NcPlane, PaletteIndex,
@@ -284,7 +286,7 @@ pub fn cellcmp(plane1: &NcPlane, cell1: &Cell, plane2: &NcPlane, cell2: &Cell) -
         return true;
     }
     unsafe {
-        nc::strcmp(
+        strcmp(
             nc::cell_extended_gcluster(plane1, cell1),
             nc::cell_extended_gcluster(plane2, cell2),
         ) != 0

rust/src/input.rs

@@ -9,13 +9,13 @@
 //+ ncinput_equal_p
 
 use crate as nc;
-use nc::types::Input;
+use nc::types::NcInput;
 
 /// Compare two ncinput structs for data equality by doing a field-by-field
 /// comparison for equality (excepting seqnum).
 ///
 /// Returns true if the two are data-equivalent.
-pub fn ncinput_equal_p(n1: Input, n2: Input) -> bool {
+pub fn ncinput_equal_p(n1: NcInput, n2: NcInput) -> bool {
     if n1.id != n2.id {
         return false;
     }
@@ -26,9 +26,9 @@ pub fn ncinput_equal_p(n1: Input, n2: Input) -> bool {
     true
 }
 
-impl Input {
+impl NcInput {
-    pub fn new() -> Input {
+    pub fn new() -> NcInput {
-        Input {
+        NcInput {
             id: 0,
             y: 0,
             x: 0,

rust/src/key.rs

@@ -11,7 +11,11 @@
 
 use crate as nc;
 
-/// Is this char32_t a Supplementary Private Use Area-B codepoint?
+/// Is this u32 a Supplementary Private Use Area-B codepoint?
+///
+/// Links:
+/// - https://en.wikipedia.org/wiki/Private_Use_Areas
+/// - https://codepoints.net/supplementary_private_use_area-b
 #[inline]
 pub fn nckey_supppuab_p(w: u32) -> bool {
     w >= 0x100000 && w <= 0x10fffd

rust/src/keycodes.rs

@@ -4,7 +4,7 @@
 //  - https://github.com/rust-lang/rust-bindgen/issues/316
 //  - https://github.com/jethrogb/rust-cexpr/pull/15
 
-pub const fn suppuabize(w: u32) -> u32 {
+const fn suppuabize(w: u32) -> u32 {
     w + 0x100000
 }
 

rust/src/lib.rs

@@ -4,9 +4,11 @@
 #![no_std]
 #![allow(clippy::too_many_arguments)]
 
-// Include the bindgen bindings
+pub mod bindings;
-mod bindings;
+pub mod types;
+
 pub use bindings::*;
+pub use types::*;
 
 #[macro_use]
 mod macros;
@@ -21,7 +23,6 @@ mod notcurses;
 mod palette;
 mod pixel;
 mod plane;
-pub mod types; // re-exportable
 mod visual;
 
 pub use cells::*;
@@ -34,7 +35,6 @@ pub use notcurses::*;
 pub use palette::*;
 pub use pixel::*;
 pub use plane::*;
-pub use types::*;
 pub use visual::*;
 
 // TODO: move tests out

rust/src/notcurses.rs

@@ -55,7 +55,9 @@
 use core::ptr::null;
 
 use crate as nc;
-use nc::types::{Input, NcAlign, NcPlane, Notcurses, NCALIGN_CENTER, NCALIGN_LEFT};
+use nc::types::{NcAlign, NcInput, NcPlane, Notcurses, NCALIGN_CENTER, NCALIGN_LEFT};
+
+use nc::timespec; // NOTE: can't use libc::timespec with notcurses_getc(()
 
 /// return the offset into 'availcols' at which 'cols' ought be output given the requirements of 'align'
 #[inline]
@@ -75,26 +77,26 @@ pub fn notcurses_align(availcols: i32, align: NcAlign, cols: i32) -> i32 {
 /// 'input' may be NULL if the caller is uninterested in event details.
 /// If no event is ready, returns 0.
 #[inline]
-pub fn notcurses_getc_nblock(nc: &mut Notcurses, input: &mut Input) -> nc::char32_t {
+pub fn notcurses_getc_nblock(nc: &mut Notcurses, input: &mut NcInput) -> char {
     unsafe {
         let mut sigmask = nc::sigset_t { __val: [0; 16] };
         nc::sigfillset(&mut sigmask);
-        let ts = nc::timespec {
+        let ts = timespec {
             tv_sec: 0,
             tv_nsec: 0,
         };
-        nc::notcurses_getc(nc, &ts, &mut sigmask, input)
+        core::char::from_u32_unchecked(nc::notcurses_getc(nc, &ts, &mut sigmask, input))
     }
 }
 
 /// 'input' may be NULL if the caller is uninterested in event details.
 /// Blocks until an event is processed or a signal is received.
 #[inline]
-pub fn notcurses_getc_nblocking(nc: &mut Notcurses, input: &mut Input) -> nc::char32_t {
+pub fn notcurses_getc_nblocking(nc: &mut Notcurses, input: &mut NcInput) -> char {
     unsafe {
         let mut sigmask = nc::sigset_t { __val: [0; 16] };
         nc::sigemptyset(&mut sigmask);
-        nc::notcurses_getc(nc, null(), &mut sigmask, input)
+        core::char::from_u32_unchecked(nc::notcurses_getc(nc, null(), &mut sigmask, input))
     }
 }
 
@@ -117,7 +119,7 @@ pub fn notcurses_term_dim_yx(nc: &Notcurses, rows: &mut i32, cols: &mut i32) {
 }
 
 // TODO
-// pub unsafe fn notcurses_start() -> *mut Notcurses {
+// pub unsafe fn notcurses_new() -> *mut Notcurses {
 //     nc::notcurses_init(core::ptr::null(), libc_stdout())
 // }
 

rust/src/plane.rs

@@ -153,6 +153,7 @@ use core::ffi::c_void;
 use core::ptr::null_mut;
 
 use cstr_core::CString;
+use libc::free;
 
 use crate as nc;
 use nc::types::{
@@ -181,7 +182,7 @@ pub fn nplane_at_cursor_cell(plane: &mut NcPlane, cell: &mut Cell) -> IntResult
     let result: IntResult = unsafe { nc::cell_load(plane, cell, egc) };
     if result < 0 {
         unsafe {
-            nc::free(&mut egc as *mut _ as *mut c_void);
+            free(&mut egc as *mut _ as *mut c_void);
         }
     }
     result
@@ -200,7 +201,7 @@ pub fn ncplane_at_yx_cell(plane: &mut NcPlane, y: i32, x: i32, cell: &mut Cell)
     let result: IntResult = unsafe { nc::cell_load(plane, cell, egc) };
     cell.channels = channels;
     unsafe {
-        nc::free(&mut egc as *mut _ as *mut c_void);
+        free(&mut egc as *mut _ as *mut c_void);
     }
     result
 }
@@ -480,7 +481,7 @@ pub fn ncplane_putstr(plane: &mut NcPlane, gclustarr: &[u8]) -> IntResult {
 
 ///
 #[inline]
-pub fn ncplane_putnstr(plane: &mut NcPlane, size: nc::size_t, gclustarr: &[u8]) -> IntResult {
+pub fn ncplane_putnstr(plane: &mut NcPlane, size: u64, gclustarr: &[u8]) -> IntResult {
     unsafe {
         nc::ncplane_putnstr_yx(
             plane,

rust/src/types.rs

@@ -270,16 +270,16 @@ pub const NCBLIT_DEFAULT: NcBlitter = nc::ncblitter_e_NCBLIT_DEFAULT;
 pub const NCBLIT_SIXEL: NcBlitter = nc::ncblitter_e_NCBLIT_SIXEL;
 
 /// Type alias of ncscale_e
-pub type Scale = nc::ncscale_e;
+pub type NcScale = nc::ncscale_e;
 
 /// Maintain original size
-pub const NCSCALE_NONE: Scale = nc::ncscale_e_NCSCALE_NONE;
+pub const NCSCALE_NONE: NcScale = nc::ncscale_e_NCSCALE_NONE;
 
 /// Maintain aspect ratio
-pub const NCSCALE_SCALE: Scale = nc::ncscale_e_NCSCALE_SCALE;
+pub const NCSCALE_SCALE: NcScale = nc::ncscale_e_NCSCALE_SCALE;
 
 /// Throw away aspect ratio
-pub const NCSCALE_STRETCH: Scale = nc::ncscale_e_NCSCALE_STRETCH;
+pub const NCSCALE_STRETCH: NcScale = nc::ncscale_e_NCSCALE_STRETCH;
 
 /// Type alias of ncdirect (direct mode)
 pub type NcDirect = nc::ncdirect;
@@ -304,4 +304,4 @@ pub const NCDIRECT_INHIBIT_SETLOCALE: NcDirectFlags =
 pub type Notcurses = nc::bindings::notcurses;
 
 /// Type alias of ncinput
-pub type Input = nc::ncinput;
+pub type NcInput = nc::ncinput;

rust/src/visual.rs

@@ -26,14 +26,14 @@
 // ncvisual_default_blitter
 
 use crate as nc;
-use nc::types::{NCBLIT_1x1, NCBLIT_2x1, NCBLIT_2x2, NcBlitter, Scale, NCSCALE_STRETCH};
+use nc::types::{NCBLIT_1x1, NCBLIT_2x1, NCBLIT_2x2, NcBlitter, NcScale, NCSCALE_STRETCH};
 
 /// Returns the best default blitter available
 ///
 /// NCBLIT_3x2 is better image quality, especially for large images, but
 /// it's not the general default because it doesn't preserve aspect ratio.
 /// NCSCALE_STRETCH throws away aspect ratio, and can safely use NCBLIT_3x2.
-pub fn ncvisual_default_blitter(utf8: bool, scale: Scale) -> NcBlitter {
+pub fn ncvisual_default_blitter(utf8: bool, scale: NcScale) -> NcBlitter {
     if utf8 {
         if scale == NCSCALE_STRETCH {
             return NCBLIT_2x2;