Flesh out safety annotations

Author: andrepd

src/posit/basics.rs

@@ -76,8 +76,13 @@ impl<
     Self(Self::sign_extend(bits))
   }
 
-  /// As [`Self::from_bits`], but if `bits` is not a result of a [`Self::to_bits`] call, then
-  /// calling this function is undefined behaviour.
+  /// As [`Self::from_bits`], but does not check that `bits` is a valid bit pattern for `Self`.
+  ///
+  /// # Safety
+  ///
+  /// `bits` has to be a result of a [`Self::to_bits`] call, i.e. it has to be in the range 
+  /// `-1 << (N-1) .. 1 << (N-1) - 1`, or calling this function is *undefined behaviour*. Note
+  /// that if `Int::BITS == Self::BITS` this always holds.
   pub const unsafe fn from_bits_unchecked(bits: Int) -> Self {
     Self(bits)
   }
@@ -114,16 +119,19 @@ impl<
   /// and so on.
   pub(crate) const FRAC_DENOM: Int = const_as(1i128 << Self::FRAC_WIDTH);
 
-  /// The size of this Posit type in bits.
-  ///
-  /// Note: this is the logical size, not necessarily the size of the underlying type.
+  /// As [`Posit::BITS`].
   pub const BITS: u32 = Posit::<N, ES, Int>::BITS;
 
-  /// The number of exponent bits.
+  /// As [`Posit::ES`].
   pub const ES: u32 = Posit::<N, ES, Int>::ES;
 
-  /// Checks whether `self` is normalised, i.e. whether `self.frac` starts with `0b01` or `0b10`,
-  /// and `self.exp >> ES` starts with `0b00` or `0b11` (which is guaranteed if `ES > 0`).
+  /// As [`Posit::JUNK_BITS`].
+  pub(crate) const JUNK_BITS: u32 = Posit::<N, ES, Int>::ES;
+
+  /// Checks whether `self` is "normalised", i.e. whether 
+  ///
+  /// - `self.frac` starts with `0b01` or `0b10`, and
+  /// - `self.exp >> ES` starts with `0b00` or `0b11` (which is guaranteed if `ES > 0`).
   pub(crate) fn is_normalised(self) -> bool {
     let frac = self.frac >> Self::FRAC_WIDTH;
     let exp = self.exp >> Self::FRAC_WIDTH;

src/posit/convert/int.rs

@@ -4,7 +4,10 @@ use crate::underlying::const_as;
 
 /// The kernel for converting a _signed_ int to a posit.
 ///
-/// If `int` is `FromInt::ZERO` or `FromInt::MIN`, calling this function is *undefined behaviour*.
+/// # Safety
+///
+/// `int` cannot be `FromInt::ZERO` or `FromInt::MIN`, or calling this function is *undefined
+/// behaviour*.
 #[inline]
 unsafe fn round_from_signed_kernel<
   FromInt: crate::Int,
@@ -54,7 +57,10 @@ unsafe fn round_from_signed_kernel<
 /// The kernel for converting an _unsigned_ int to a posit (note it takes a signed int as
 /// argument though).
 ///
-/// If `int` is `FromInt::ZERO` or `FromInt::MIN`, calling this function is *undefined behaviour*.
+/// # Safety
+///
+/// `int` cannot be `FromInt::ZERO` or `FromInt::MIN`, or calling this function is *undefined
+/// behaviour*.
 #[inline]
 unsafe fn round_from_unsigned_kernel<
   FromInt: crate::Int,

src/posit/decode.rs

@@ -7,7 +7,10 @@ impl<
 > Posit<N, ES, Int> {
   /// Decode a posit **which is not 0 or NaR** into its constituent `frac`tion and `exp`onent.
   ///
-  /// `self` cannot be 0 or NaR, or calling this is undefined behaviour.
+  /// # Safety
+  ///
+  /// `self` cannot be [0](Self::ZERO) or [NaR](Self::NAR), or calling this function is *undefined
+  /// behaviour*.
   pub(crate) unsafe fn decode_regular(self) -> Decoded<N, ES, Int> {
     // This routine is central to nearly every nontrivial algorithm, so it's critical to get right!
     // With care, we can make it as small as ~20 instructions and ~7 cycles throughput on a modern

src/posit/encode.rs

@@ -5,8 +5,6 @@ impl<
   const ES: u32,
   Int: crate::Int,
 > Decoded<N, ES, Int> {
-  const JUNK_BITS: u32 = Posit::<N, ES, Int>::JUNK_BITS;
-
   /// Encode a posit, rounding if necessary. The rounding rule is always the same: "round to
   /// nearest, round ties to even bit pattern, never round to 0 (i.e. never over- or under-flow)".
   ///
@@ -17,6 +15,11 @@ impl<
   /// This function is suitable for encoding a [`Decoded`] that might need rounding to produce a
   /// valid Posit (for example, if it was obtained from doing an arithmetic operation). If you
   /// don't need to round, see [`Self::encode_regular`].
+  ///
+  /// # Safety
+  ///
+  /// [`self.is_normalised()`](Self::is_normalised) has to hold, or calling this function
+  /// is *undefined behaviour*.
   pub(crate) unsafe fn encode_regular_round(self, mut sticky: Int) -> Posit<N, ES, Int> {
     debug_assert!(
       self.is_normalised(),
@@ -200,6 +203,11 @@ impl<
   /// [`Posit::decode_regular`], or that was otherwise crafted as a valid Posit. If if might need
   /// rounding (for instance, if you obtained it from doing an arithmetic operation), see
   /// [`Self::encode_regular_round`].
+  ///
+  /// # Safety
+  ///
+  /// [`self.is_normalised()`](Self::is_normalised) has to hold, or calling this function
+  /// is *undefined behaviour*.
   #[inline]
   pub(crate) unsafe fn encode_regular(self) -> Posit<N, ES, Int> {
     debug_assert!(

src/posit/ops/add.rs

@@ -5,7 +5,13 @@ impl<
   const ES: u32,
   Int: crate::Int,
 > Posit<N, ES, Int> {
-  /// `x` and `y` cannot be symmetrical, or calling this function is *undefined behaviour*.
+  /// Return a [normalised](Decoded::is_normalised) `Decoded` that's the result of adding `x` and
+  /// `y`, plus the sticky bit.
+  ///
+  /// # Safety
+  ///
+  /// `x` and `y` have to be [normalised](Decoded::is_normalised) and cannot be symmetrical, or
+  /// calling this function is *undefined behaviour*.
   #[inline]
   pub(crate) unsafe fn add_kernel(x: Decoded<N, ES, Int>, y: Decoded<N, ES, Int>) -> (Decoded<N, ES, Int>, Int) {
     // Adding two numbers in the form `x.frac × 2^x.exp` and `y.exp × 2^y.exp` is easy, if only
@@ -73,6 +79,7 @@ impl<
     // To do this we use our trusty `leading_run_minus_one`, since we want to detect that the
     // number starts with n 0s followed by a 1 or n 1s followed by a 0, and shift them so that
     // it's just a 01 or a 10.
+    //
     // SAFETY: x and y are not symmetrical (precondition), so `frac` cannot be 0
     let underflow = unsafe { frac.leading_run_minus_one() };
     let frac = frac << underflow as u32;
@@ -108,7 +115,7 @@ impl<
       let b = unsafe { other.decode_regular() };
       // SAFETY: `self` and `other` aren't symmetrical
       let (result, sticky) = unsafe { Self::add_kernel(a, b) };
-      // SAFETY: `result` does not have an underflowing `frac`
+      // SAFETY: `result.is_normalised()` holds
       unsafe { result.encode_regular_round(sticky) }
     }
   }

src/posit/ops/div.rs

@@ -5,6 +5,13 @@ impl<
   const ES: u32,
   Int: crate::Int,
 > Posit<N, ES, Int> {
+  /// Return a [normalised](Decoded::is_normalised) `Decoded` that's the result of dividing `x` by
+  /// `y`, plus the sticky bit.
+  ///
+  /// # Safety
+  ///
+  /// `x` and `y` have to be [normalised](Decoded::is_normalised), or calling this function
+  /// is *undefined behaviour*.
   #[inline]
   pub(crate) unsafe fn div_kernel(x: Decoded<N, ES, Int>, y: Decoded<N, ES, Int>) -> (Decoded<N, ES, Int>, Int) {
     // Let's use ÷ to denote true mathematical division, and / denote integer division *that rounds
@@ -58,7 +65,7 @@ impl<
       let a = unsafe { self.decode_regular() };
       let b = unsafe { other.decode_regular() };
       let (result, sticky) = unsafe { Self::div_kernel(a, b) };
-      // SAFETY: `result` does not have an underflowing `frac`
+      // SAFETY: `result.is_normalised()` holds
       unsafe { result.encode_regular_round(sticky) }
     }
   }

src/posit/ops/mul.rs

@@ -5,6 +5,13 @@ impl<
   const ES: u32,
   Int: crate::Int,
 > Posit<N, ES, Int> {
+  /// Return a [normalised](Decoded::is_normalised) `Decoded` that's the result of multiplying `x`
+  /// and `y`, plus the sticky bit.
+  ///
+  /// # Safety
+  ///
+  /// `x` and `y` have to be [normalised](Decoded::is_normalised), or calling this function
+  /// is *undefined behaviour*.
   #[inline]
   pub(crate) unsafe fn mul_kernel(x: Decoded<N, ES, Int>, y: Decoded<N, ES, Int>) -> (Decoded<N, ES, Int>, Int) {
     // Multiplying two numbers in the form `frac × 2^exp` is much easier than adding them. We have
@@ -63,7 +70,7 @@ impl<
       let b = unsafe { other.decode_regular() };
       // SAFETY: `self` and `other` aren't symmetrical
       let (result, sticky) = unsafe { Self::mul_kernel(a, b) };
-      // SAFETY: `result` does not have an underflowing `frac`
+      // SAFETY: `result.is_normalised()` holds
       unsafe { result.encode_regular_round(sticky) }
     }
   }

src/posit/quire/add.rs

@@ -22,7 +22,7 @@ impl<
   ///
   /// # Safety
   ///
-  /// `limbs.len() * size_of::<Int>() + offset < SIZE`, otherwise calling this function
+  /// `limbs.len() * size_of::<Int>() + offset < SIZE` must hold, or calling this function
   /// is *undefined behaviour*.
   pub(crate) unsafe fn accumulate<const L: usize, Int: crate::Int>(
     &mut self,
@@ -82,7 +82,7 @@ impl<
   ///
   /// # Safety
   ///
-  /// `x` must be the result of a [`Posit::decode_regular`] call, otherwise calling this function
+  /// `x` must be the result of a [`Posit::decode_regular`] call, or calling this function
   /// is *undefined behaviour*.
   pub(crate) unsafe fn accumulate_decoded<Int: crate::Int>(&mut self, x: Decoded<N, ES, Int>) {
     debug_assert!(x.exp <= Posit::<N, ES, Int>::MAX_EXP + Int::ONE);