[rust] safely wrap ncmetric function & fix warnings

- fix warnings on doc generation from imported C API doc-comments
- fix remaining clippy warning

include/notcurses/notcurses.h

@@ -2821,7 +2821,7 @@ API struct ncplane* nctablet_plane(struct nctablet* t);
 // buffer to generate up to |[IB]PREFIXCOLUMNS| columns' worth of EGCs. The
 // characteristic can occupy up through |mult-1| characters (3 for 1000, 4 for
 // 1024). The mantissa can occupy either zero or two characters.
-//
+
 // Floating-point is never used, because an IEEE758 double can only losslessly
 // represent integers through 2^53-1.
 //

rust/build/build.rs

@@ -33,6 +33,7 @@ fn main() {
         // Remove warnings about improper_ctypes
         .blacklist_function("strtold")
         .blacklist_function("wcstold")
+        .blacklist_function("socketpair")
         // Don't derive the Copy trait on types with destructors.
         .no_copy("ncdirect")
         .no_copy("ncdplot")

rust/src/bindings.rs

@@ -287,6 +287,9 @@ pub use ffi::{
 //
 // already wrapped:
 //
+// // functions
+// ncmetric
+//
 // // constants
 // PREFIXCOLUMNS,
 // PREFIXSTRLEN,
@@ -295,8 +298,6 @@ pub use ffi::{
 // IPREFIXCOLUMNS,
 // IPREFIXSTRLEN,
 
-#[doc(inline)]
-pub use ffi::ncmetric;
 
 // ncmultiselector -------------------------------------------------------------
 //

rust/src/file.rs

@@ -87,6 +87,7 @@ impl NcFile {
     }
 
     /// `NcFile` constructor from a file produced by the libc crate
+    #[allow(clippy::missing_safety_doc)]
     pub unsafe fn from_libc(file: *mut FILE_LIBC) -> Self {
         NcFile {
             file_ptr: NonNull::new_unchecked(file),

rust/src/metric.rs

@@ -1,7 +1,43 @@
 //! `NcMetric`
 
+use crate::{cstring_mut, rstring};
+
 // TODO: clarify, update and visibilize doc-comments
 
+/// Takes an arbitrarily large number, and prints it into a fixed-size buffer by
+/// adding the necessary SI suffix.
+///
+/// Usually, pass a `|[IB]PREFIXSTRLEN+1|-sized` buffer to generate up to
+/// `|[IB]PREFIXCOLUMNS|` columns' worth of EGCs. The characteristic can occupy
+/// up through `|mult-1|` characters (3 for 1000, 4 for 1024).
+/// The mantissa can occupy either zero or two characters.
+///
+/// Floating-point is never used, because an IEEE758 double can only losslessly
+/// represent integers through 2^53-1.
+///
+/// 2^64-1 is 18446744073709551615, 18.45E(xa). KMGTPEZY thus suffice to handle
+/// an 89-bit uintmax_t. Beyond Z(etta) and Y(otta) lie lands unspecified by SI.
+/// 2^-63 is 0.000000000000000000108, 1.08a(tto). val: value to print decimal:
+/// scaling. '1' if none has taken place. buf: buffer in which string will be
+/// generated omitdec: inhibit printing of all-0 decimal portions mult: base of
+/// suffix system (almost always 1000 or 1024) uprefix: character to print
+/// following suffix ('i' for kibibytes basically). only printed if suffix is
+/// actually printed (input >= mult).
+///
+/// You are encouraged to consult notcurses_metric(3).
+///
+pub fn ncmetric(
+    val: u64,
+    decimal: u64,
+    buf: &str,
+    omitdec: i32,
+    mult: u64,
+    uprefix: i32,
+) -> &str {
+    let buf = cstring_mut![buf];
+    rstring![ crate::ffi::ncmetric(val, decimal, buf, omitdec, mult, uprefix) ]
+}
+
 // The number of columns is one fewer, as the STRLEN expressions must leave
 // an extra byte open in case 'µ' (U+00B5, 0xC2 0xB5) shows up.