Merge pull request #322 from DaniPopes/more-clippies

chore: warn on `missing_docs` and `clippy::missing_inline_in_public_items`

Author: prestwich

src/add.rs

@@ -53,6 +53,7 @@ impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS> {
     /// Returns a tuple of the addition along with a boolean indicating whether
     /// an arithmetic overflow would occur. If an overflow would have occurred
     /// then the wrapped value is returned.
+    #[inline]
     #[must_use]
     pub fn overflowing_add(mut self, rhs: Self) -> (Self, bool) {
         if BITS == 0 {
@@ -87,6 +88,7 @@ impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS> {
     /// Returns a tuple of the subtraction along with a boolean indicating
     /// whether an arithmetic overflow would occur. If an overflow would have
     /// occurred then the wrapped value is returned.
+    #[inline]
     #[must_use]
     pub fn overflowing_sub(mut self, rhs: Self) -> (Self, bool) {
         if BITS == 0 {
@@ -168,6 +170,7 @@ impl<const BITS: usize, const LIMBS: usize> Neg for &Uint<BITS, LIMBS> {
 }
 
 impl<const BITS: usize, const LIMBS: usize> Sum<Self> for Uint<BITS, LIMBS> {
+    #[inline]
     fn sum<I>(iter: I) -> Self
     where
         I: Iterator<Item = Self>,
@@ -177,6 +180,7 @@ impl<const BITS: usize, const LIMBS: usize> Sum<Self> for Uint<BITS, LIMBS> {
 }
 
 impl<'a, const BITS: usize, const LIMBS: usize> Sum<&'a Self> for Uint<BITS, LIMBS> {
+    #[inline]
     fn sum<I>(iter: I) -> Self
     where
         I: Iterator<Item = &'a Self>,

src/algorithms/div/knuth.rs

@@ -17,6 +17,7 @@ use core::u64;
 /// # Panics
 ///
 /// May panic if the above requirements are not met.
+#[inline]
 #[allow(clippy::many_single_char_names)]
 pub fn div_nxm_normalized(numerator: &mut [u64], divisor: &[u64]) {
     debug_assert!(divisor.len() >= 2);
@@ -83,6 +84,7 @@ pub fn div_nxm_normalized(numerator: &mut [u64], divisor: &[u64]) {
 /// # Panics
 ///
 /// May panic if the above requirements are not met.
+#[inline]
 #[allow(clippy::many_single_char_names)]
 pub fn div_nxm(numerator: &mut [u64], divisor: &mut [u64]) {
     debug_assert!(divisor.len() >= 3);

src/algorithms/gcd/matrix.rs

@@ -21,6 +21,7 @@ impl Matrix {
     pub const IDENTITY: Self = Self(1, 0, 0, 1, true);
 
     /// Returns the matrix product `self * other`.
+    #[inline]
     #[allow(clippy::suspicious_operation_groupings)]
     #[must_use]
     pub const fn compose(self, other: Self) -> Self {
@@ -34,6 +35,7 @@ impl Matrix {
     }
 
     /// Applies the matrix to a `Uint`.
+    #[inline]
     pub fn apply<const BITS: usize, const LIMBS: usize>(
         &self,
         a: &mut Uint<BITS, LIMBS>,
@@ -60,6 +62,7 @@ impl Matrix {
     }
 
     /// Applies the matrix to a `u128`.
+    #[inline]
     #[must_use]
     pub const fn apply_u128(&self, a: u128, b: u128) -> (u128, u128) {
         // Intermediate values can overflow but the final result will fit, so we
@@ -90,6 +93,7 @@ impl Matrix {
     /// # Panics
     ///
     /// Panics if `b > a`.
+    #[inline]
     #[must_use]
     pub fn from<const BITS: usize, const LIMBS: usize>(
         a: Uint<BITS, LIMBS>,
@@ -119,6 +123,7 @@ impl Matrix {
     /// Panics if `r1 < r0`.
     // OPT: Would this be faster using extended binary gcd?
     // See <https://en.algorithmica.org/hpc/algorithms/gcd>
+    #[inline]
     #[must_use]
     pub fn from_u64(mut r0: u64, mut r1: u64) -> Self {
         debug_assert!(r0 >= r1);
@@ -162,6 +167,7 @@ impl Matrix {
     ///
     /// Panics if `a0` does not have the highest bit set.
     /// Panics if `a0 < a1`.
+    #[inline]
     #[must_use]
     #[allow(clippy::redundant_else)]
     #[allow(clippy::cognitive_complexity)] // REFACTOR: Improve
@@ -299,6 +305,7 @@ impl Matrix {
     /// simplest out of these solutions.
     // OPT: We can update r0 and r1 in place. This won't remove the partially
     // redundant call to lehmer_update, but it reduces memory usage.
+    #[inline]
     #[must_use]
     pub fn from_u128_prefix(r0: u128, r1: u128) -> Self {
         debug_assert!(r0 >= r1);

src/algorithms/gcd/mod.rs

@@ -12,6 +12,7 @@ use core::mem::swap;
 /// **Warning.** This struct is not part of the stable API.
 ///
 /// See [`gcd_extended`] for documentation.
+#[inline]
 #[must_use]
 pub fn gcd<const BITS: usize, const LIMBS: usize>(
     mut a: Uint<BITS, LIMBS>,
@@ -58,6 +59,7 @@ pub fn gcd<const BITS: usize, const LIMBS: usize>(
 ///
 /// See also `mpn_gcdext_lehmer_n` in GMP.
 /// <https://gmplib.org/repo/gmp-6.1/file/tip/mpn/generic/gcdext_lehmer.c#l146>
+#[inline]
 #[must_use]
 pub fn gcd_extended<const BITS: usize, const LIMBS: usize>(
     mut a: Uint<BITS, LIMBS>,
@@ -136,6 +138,7 @@ pub fn gcd_extended<const BITS: usize, const LIMBS: usize>(
 /// It differs from `gcd_extended` in that it only computes the required
 /// cofactor, and returns `None` if the GCD is not one (i.e. when `num` does
 /// not have an inverse).
+#[inline]
 #[must_use]
 pub fn inv_mod<const BITS: usize, const LIMBS: usize>(
     num: Uint<BITS, LIMBS>,

src/algorithms/mod.rs

@@ -3,6 +3,8 @@
 //! **Warning.** Most functions in this module are currently not considered part
 //! of the stable API and may be changed or removed in future minor releases.
 
+#![allow(missing_docs)] // TODO: document algorithms
+
 mod add;
 pub mod div;
 mod gcd;

src/algorithms/mul.rs

@@ -2,6 +2,7 @@
 
 use crate::algorithms::{ops::sbb, DoubleWord};
 
+#[inline]
 #[allow(clippy::cast_possible_truncation)] // Intentional truncation.
 #[allow(dead_code)] // Used for testing
 pub fn addmul_ref(result: &mut [u64], a: &[u64], b: &[u64]) -> bool {
@@ -225,6 +226,7 @@ fn mac(lhs: &mut u64, a: u64, b: u64, c: u64) -> u64 {
 }
 
 /// Computes `lhs *= a` and returns the carry.
+#[inline]
 pub fn mul_nx1(lhs: &mut [u64], a: u64) -> u64 {
     let mut carry = 0;
     for lhs in &mut *lhs {

src/algorithms/mul_redc.rs

@@ -3,6 +3,7 @@ use core::iter::zip;
 
 /// See Handbook of Applied Cryptography, Algorithm 14.32, p. 601.
 #[allow(clippy::cognitive_complexity)] // REFACTOR: Improve
+#[inline]
 pub fn mul_redc(a: &[u64], b: &[u64], result: &mut [u64], m: &[u64], inv: u64) {
     debug_assert!(!m.is_empty());
     debug_assert_eq!(a.len(), m.len());

src/base_convert.rs

@@ -23,9 +23,10 @@ pub enum BaseConvertError {
 impl std::error::Error for BaseConvertError {}
 
 impl fmt::Display for BaseConvertError {
+    #[inline]
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
-            Self::Overflow => write!(f, "The value is too large to fit the target type"),
+            Self::Overflow => f.write_str("The value is too large to fit the target type"),
             Self::InvalidBase(base) => {
                 write!(f, "The requested number base {base} is less than two")
             }
@@ -156,6 +157,7 @@ impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS> {
     /// * [`BaseConvertError::InvalidDigit`] if a digit is out of range.
     /// * [`BaseConvertError::Overflow`] if the number is too large to
     /// fit.
+    #[inline]
     pub fn from_base_be<I: IntoIterator<Item = u64>>(
         base: u64,
         digits: I,

src/bit_arr.rs

@@ -52,18 +52,21 @@ impl<const BITS: usize, const LIMBS: usize> Bits<BITS, LIMBS> {
     /// types.
     pub const ZERO: Self = Self(Uint::<BITS, LIMBS>::ZERO);
 
+    /// Returns the inner [Uint].
     #[must_use]
     #[inline(always)]
     pub const fn into_inner(self) -> Uint<BITS, LIMBS> {
         self.0
     }
 
+    /// Returns a reference to the inner [Uint].
     #[must_use]
     #[inline(always)]
     pub const fn as_uint(&self) -> &Uint<BITS, LIMBS> {
         &self.0
     }
 
+    /// Returns a mutable reference to the inner [Uint].
     #[must_use]
     #[inline(always)]
     pub fn as_uint_mut(&mut self) -> &mut Uint<BITS, LIMBS> {
@@ -259,6 +262,7 @@ impl<const BITS: usize, const LIMBS: usize> Bits<BITS, LIMBS> {
 impl<const BITS: usize, const LIMBS: usize> Index<usize> for Bits<BITS, LIMBS> {
     type Output = bool;
 
+    #[inline]
     fn index(&self, index: usize) -> &Self::Output {
         if self.0.bit(index) {
             &true
@@ -271,6 +275,7 @@ impl<const BITS: usize, const LIMBS: usize> Index<usize> for Bits<BITS, LIMBS> {
 impl<const BITS: usize, const LIMBS: usize> Not for Bits<BITS, LIMBS> {
     type Output = Self;
 
+    #[inline]
     fn not(self) -> Self {
         self.0.not().into()
     }
@@ -279,6 +284,7 @@ impl<const BITS: usize, const LIMBS: usize> Not for Bits<BITS, LIMBS> {
 impl<const BITS: usize, const LIMBS: usize> Not for &Bits<BITS, LIMBS> {
     type Output = Bits<BITS, LIMBS>;
 
+    #[inline]
     fn not(self) -> Bits<BITS, LIMBS> {
         self.0.not().into()
     }

src/bits.rs

@@ -83,6 +83,7 @@ impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS> {
     /// Reverses the order of bits in the integer. The least significant bit
     /// becomes the most significant bit, second least-significant bit becomes
     /// second most-significant bit, etc.
+    #[inline]
     #[must_use]
     pub fn reverse_bits(mut self) -> Self {
         self.limbs.reverse();
@@ -97,6 +98,7 @@ impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS> {
 
     /// Returns the number of leading zeros in the binary representation of
     /// `self`.
+    #[inline]
     #[must_use]
     pub fn leading_zeros(&self) -> usize {
         self.as_limbs()
@@ -113,13 +115,15 @@ impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS> {
 
     /// Returns the number of leading ones in the binary representation of
     /// `self`.
+    #[inline]
     #[must_use]
     pub fn leading_ones(&self) -> usize {
         (self.not()).leading_zeros()
     }
 
     /// Returns the number of trailing zeros in the binary representation of
     /// `self`.
+    #[inline]
     #[must_use]
     pub fn trailing_zeros(&self) -> usize {
         self.as_limbs()
@@ -132,6 +136,7 @@ impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS> {
 
     /// Returns the number of trailing ones in the binary representation of
     /// `self`.
+    #[inline]
     #[must_use]
     pub fn trailing_ones(&self) -> usize {
         self.as_limbs()
@@ -143,6 +148,7 @@ impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS> {
     }
 
     /// Returns the number of ones in the binary representation of `self`.
+    #[inline]
     #[must_use]
     pub fn count_ones(&self) -> usize {
         self.as_limbs()
@@ -183,6 +189,7 @@ impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS> {
     ///
     /// If `self` is $<≥> 2^{63}$, then `exponent` will be zero and `bits` will
     /// have leading zeros.
+    #[inline]
     #[must_use]
     pub fn most_significant_bits(&self) -> (u64, usize) {
         let first_set_limb = self
@@ -245,6 +252,7 @@ impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS> {
     ///
     /// Note: This differs from [`u64::overflowing_shl`] which returns `true` if
     /// the shift is larger than `BITS` (which is IMHO not very useful).
+    #[inline]
     #[must_use]
     pub fn overflowing_shl(mut self, rhs: usize) -> (Self, bool) {
         let (limbs, bits) = (rhs / 64, rhs % 64);
@@ -341,6 +349,7 @@ impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS> {
     ///
     /// Note: This differs from [`u64::overflowing_shr`] which returns `true` if
     /// the shift is larger than `BITS` (which is IMHO not very useful).
+    #[inline]
     #[must_use]
     pub fn overflowing_shr(mut self, rhs: usize) -> (Self, bool) {
         let (limbs, bits) = (rhs / 64, rhs % 64);
@@ -399,6 +408,7 @@ impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS> {
     }
 
     /// Arithmetic shift right by `rhs` bits.
+    #[inline]
     #[must_use]
     pub fn arithmetic_shr(self, rhs: usize) -> Self {
         if BITS == 0 {
@@ -414,6 +424,7 @@ impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS> {
 
     /// Shifts the bits to the left by a specified amount, `rhs`, wrapping the
     /// truncated bits to the end of the resulting integer.
+    #[inline]
     #[must_use]
     #[allow(clippy::missing_const_for_fn)] // False positive
     pub fn rotate_left(self, rhs: usize) -> Self {
@@ -424,6 +435,8 @@ impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS> {
         self << rhs | self >> (BITS - rhs)
     }
 
+    /// Shifts the bits to the right by a specified amount, `rhs`, wrapping the
+    /// truncated bits to the beginning of the resulting integer.
     #[inline(always)]
     #[must_use]
     pub fn rotate_right(self, rhs: usize) -> Self {
@@ -438,6 +451,7 @@ impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS> {
 impl<const BITS: usize, const LIMBS: usize> Not for Uint<BITS, LIMBS> {
     type Output = Self;
 
+    #[inline]
     fn not(mut self) -> Self::Output {
         if BITS == 0 {
             return Self::ZERO;
@@ -453,6 +467,7 @@ impl<const BITS: usize, const LIMBS: usize> Not for Uint<BITS, LIMBS> {
 impl<const BITS: usize, const LIMBS: usize> Not for &Uint<BITS, LIMBS> {
     type Output = Uint<BITS, LIMBS>;
 
+    #[inline]
     fn not(self) -> Self::Output {
         (*self).not()
     }
@@ -471,6 +486,7 @@ macro_rules! impl_bit_op {
         impl<const BITS: usize, const LIMBS: usize> $trait_assign<&Uint<BITS, LIMBS>>
             for Uint<BITS, LIMBS>
         {
+            #[inline]
             fn $fn_assign(&mut self, rhs: &Uint<BITS, LIMBS>) {
                 for (limb, &rhs) in self.limbs.iter_mut().zip(rhs.as_limbs()) {
                     u64::$fn_assign(limb, rhs);

src/bytes.rs

@@ -89,6 +89,7 @@ impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS> {
     /// Rust issue [#60551].
     ///
     /// [#60551]: https://github.com/rust-lang/rust/issues/60551
+    #[inline]
     #[must_use]
     pub fn to_le_bytes<const BYTES: usize>(&self) -> [u8; BYTES] {
         // TODO: Use a `const {}` block for this assertion
@@ -280,8 +281,8 @@ impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS> {
 /// This needs to be public because it is used in the `Uint` type,
 /// specifically in the [`to_be_bytes()`][Uint::to_be_bytes] and related
 /// functions.
-#[must_use]
 #[inline]
+#[must_use]
 pub const fn nbytes(bits: usize) -> usize {
     (bits + 7) / 8
 }