First implementation of Posit::round_from(quire)

Now we have: `Quire::from(posit)`, `quire += posit`, and
`Posit::round_from(quire)`, so we have all the pieces to do a basic
summation using the quire! This is illustrated in the updated example
in the crate root doc.

However: this is a first draft implementation. Although correct it is
messy and not optimised enough. Will take this as a perf baseline and
use benchmarks to guide the cleanup and optimisations.

Author: andrepd

proptest-regressions/posit/quire/convert.txt

@@ -5,3 +5,13 @@
 # It is recommended to check this file in to source control so that
 # everyone who runs the test benefits from these saved cases.
 cc e4d920422cccfb5f67bd231bafb1ecc5b19450eb97a1f4ea410f0b1d90f6db05 # shrinks to a = Posit(0b11111111111111111111111111111111)
+cc 11716b72e748348a9454d6b6958c160e752deec6a219f134d3f5c5095b55a140 # shrinks to q = Quire(0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01)
+cc fc28201f1a1061fc8bb7f0399c2831434bf3babf9d84d0df020f1fe665610b8b # shrinks to q = Quire(0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00)
+cc 9c451acc1d3514c6b8c25d2f9cec13aa79921ae5c5efe54e170cb4cd01869df9 # shrinks to q = Quire(0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00)
+cc 2c51920351638dcc3a9632c5fb6b9de6b072a230bb6c63af42ac354a9b370020 # shrinks to q = Quire(0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00)
+cc 5d9a02c2439ea9189c15fa14c7b7af29a51cca93fdcfc499bf0ad6f8ded1f5fb # shrinks to q = Quire(0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00)
+cc 83c487d01ab7c1e3458d212f3d77d678fe771d4e3c3b74fba82268157b3cd356 # shrinks to q = Quire(0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00)
+cc 150843eb320314bb50f142889066c23ce5f52d2761a1549f280ea45ffd26bff0 # shrinks to p = Posit(0b00000000000000000000000000000000)
+cc c534a97df04b8c827048631656743571116e1a56b8261d4fc34d13ee49f44d52 # shrinks to q = Quire(0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00)
+cc 58843b9454f641826c2816646a2358c9bba5393d85356c69a2f62f74ee1331e2 # shrinks to q = Quire(0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00)
+cc 081a5a26de44e7544b62b8768229825db56efff8d02dad7e996dcb6b9361a550 # shrinks to q = Quire(0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00)

src/lib.rs

@@ -55,13 +55,13 @@
 //! use fast_posit::{q8, q16, q32, q64};
 //! let mut quire = q16::ZERO;  
 //! quire += p16::MAX;
-//! quire += p16::round_from(0.001); // Would overflow
+//! quire += p16::round_from(0.1);
 //! quire -= p16::MAX;
-//! //TODO let result = p16::from(quire);
+//! let result: p16 = (&quire).round_into();
 //! // Correct result with the quire, no issues with rounding errors.
-//! //TODO assert_eq!(result, p16::round_from(0.001))
+//! assert_eq!(result, p16::round_from(0.1));
 //! // The same sum without the quire would give a wrong result, due to double rounding.
-//! let posit = p16::MAX + p16::round_from(0.001) - p16::MAX;
+//! let posit = p16::MAX + p16::round_from(0.1) - p16::MAX;
 //! assert_eq!(posit, p16::ZERO);
 //!
 //! // Use a quire per thread to ensure the result is the same regardless of parallelisation!
@@ -76,7 +76,7 @@
 //! //TODO for thread in 1..8 {
 //! //TODO   quires[0] += quire[thread]
 //! //TODO }
-//! //TODO let result: p16 = quires[0].round_into();
+//! let result: p16 = (&quires[0]).round_into();
 //!
 //! // Use mixed-precision with no hassle; it's very cheap when the ES is the same.
 //! //TODO let mut quire = q64::ZERO;

src/posit/quire/basics.rs

@@ -20,12 +20,16 @@ impl<
     Self(bytes)
   }
 
-  /// Access the storage as an array of `u64`s. 
+  /// Access the storage as an array of **big-endian** `Int`s. 
+  ///
+  /// Limitation: even though the return size is known, we cannot return an `&[Int; N]` due to
+  /// limitations in the Rust type system. We have to hope that the compiler will inline and fold
+  /// the slice len :)
   #[inline]
-  pub(crate) const fn as_u64_array(&self) -> &[u64] {
+  pub(crate) const fn as_int_array<Int: crate::Int>(&self) -> &[Int] {
     const { assert!(SIZE % 8 == 0, "Quire SIZE must be a multiple of 64 bits (8 bytes)"); }
-    let ptr = self.0.as_ptr() as *const u64;
-    let len = SIZE / 8;
+    let ptr = self.0.as_ptr() as *const Int;
+    let len = SIZE / (Int::BITS as usize / 8);
     // SAFETY: ptr and len form a valid slice; the size and alignment is correct, and any bit
     // pattern is a valid u64 value.
     unsafe { core::slice::from_raw_parts(ptr, len) }
@@ -105,8 +109,8 @@ impl<
     // Therefore, for almost all cases where the quire is not NaR, we only need a compare and
     // branch. Only on when the quire is NaR, or in the rare cases where it's not NaR but still
     // starts with `0b1000…`, will we need to scan through the whole thing.
-    let quire = self.as_u64_array();
-    if quire[0] != (i64::MIN as u64).to_be() { return false }  // TODO mark likely?
+    let quire: &[i64] = self.as_int_array();
+    if quire[0] != i64::MIN.to_be() { return false }  // TODO mark likely?
     // Written in this awkward way because it's a `const fn`...
     let mut i = 1;
     while i < quire.len() {