docs: a few usage examples for div

src/uint/div.rs

@@ -84,6 +84,19 @@ impl<const LIMBS: usize> Uint<LIMBS> {
     ///
     /// When used with a fixed `rhs`, this function is constant-time with respect
     /// to `self`.
+    ///
+    /// ### Usage:
+    /// ```
+    /// use crypto_bigint::{U448, CtChoice, Limb};
+    ///
+    /// let a = U448::from(20_u64);
+    /// let b = U448::from(6_u64);
+    /// let (remainder, is_some) = a.const_rem(&b);
+    ///
+    /// // Verify the result
+    /// assert_eq!(remainder, U448::from(2_u64));
+    /// assert!(<CtChoice as Into<bool>>::into(is_some));
+    /// ```
     pub const fn const_rem(&self, rhs: &Self) -> (Self, CtChoice) {
         let mb = rhs.bits_vartime();
         let mut bd = Self::BITS - mb;
@@ -111,6 +124,21 @@ impl<const LIMBS: usize> Uint<LIMBS> {
     ///
     /// When used with a fixed `rhs`, this function is constant-time with respect
     /// to `self`.
+    ///
+    /// ### Usage:
+    /// ```
+    /// use crypto_bigint::{U448, CtChoice};
+    ///
+    /// let lower = U448::from(15_u64); // Lower part of the wide integer
+    /// let upper = U448::from(0_u64);  // Upper part of the wide integer
+    /// let rhs = U448::from(7_u64);    // Modulus
+    ///
+    /// let (remainder, is_some) = U448::const_rem_wide((lower, upper), &rhs);
+    ///
+    /// // Verify the result
+    /// assert_eq!(remainder, U448::from(1_u64));
+    /// assert!(<CtChoice as Into<bool>>::into(is_some));
+    /// ```
     pub const fn const_rem_wide(lower_upper: (Self, Self), rhs: &Self) -> (Self, CtChoice) {
         let mb = rhs.bits_vartime();
 
@@ -142,6 +170,19 @@ impl<const LIMBS: usize> Uint<LIMBS> {
 
     /// Computes `self` % 2^k. Faster than reduce since its a power of 2.
     /// Limited to 2^16-1 since Uint doesn't support higher.
+    /// TODO: this is not constant-time.
+    ///
+    /// ### Usage:
+    /// ```
+    /// use crypto_bigint::{U448, Limb};
+    ///
+    /// let a = U448::from(10_u64);
+    /// let k = 3; // 2^3 = 8
+    /// let remainder = a.rem2k(k);
+    ///
+    /// // As 10 % 8 = 2
+    /// assert_eq!(remainder, U448::from(2_u64));
+    /// ```
     pub const fn rem2k(&self, k: u32) -> Self {
         let highest = (LIMBS - 1) as u32;
         let index = k / Limb::BITS;
@@ -167,13 +208,38 @@ impl<const LIMBS: usize> Uint<LIMBS> {
     }
 
     /// Computes self / rhs, returns the quotient, remainder.
+    ///
+    /// ### Usage:
+    /// ```
+    /// use crypto_bigint::{U448, NonZero};
+    ///
+    /// let a = U448::from(8_u64);
+    /// let res = NonZero::new(U448::from(4_u64))
+    ///    .map(|b| a.div_rem(&b))
+    ///    .expect("Division by zero");
+    ///
+    /// assert_eq!(res.0, U448::from(2_u64));
+    /// assert_eq!(res.1, U448::from(0_u64));
+    /// ```
     pub fn div_rem(&self, rhs: &NonZero<Self>) -> (Self, Self) {
         // Since `rhs` is nonzero, this should always hold.
         let (q, r, _c) = self.ct_div_rem(rhs);
         (q, r)
     }
 
     /// Computes self % rhs, returns the remainder.
+    ///
+    /// ### Usage:
+    /// ```
+    /// use crypto_bigint::{U448, NonZero};
+    ///
+    /// let a = U448::from(8_u64);
+    /// let remainder = NonZero::new(U448::from(3_u64))
+    ///     .map(|b| a.rem(&b))
+    ///     .expect("Modulo by zero");
+    ///
+    /// assert_eq!(remainder, U448::from(2_u64));
+    /// ```
     pub fn rem(&self, rhs: &NonZero<Self>) -> Self {
         // Since `rhs` is nonzero, this should always hold.
         let (r, _c) = self.const_rem(rhs);
@@ -185,6 +251,17 @@ impl<const LIMBS: usize> Uint<LIMBS> {
     /// This function exists, so that all operations are accounted for in the wrapping operations.
     ///
     /// Panics if `rhs == 0`.
+    ///
+    /// ### Usage:
+    /// ```
+    /// use crypto_bigint::U448;
+    ///
+    /// let a = U448::from(10_u64);
+    /// let b = U448::from(2_u64);
+    /// let quotient = a.wrapping_div(&b);
+    ///
+    /// assert_eq!(quotient, U448::from(5_u64));
+    /// ```
     pub const fn wrapping_div(&self, rhs: &Self) -> Self {
         let (q, _, c) = self.ct_div_rem(rhs);
         assert!(c.is_true_vartime(), "divide by zero");
@@ -193,6 +270,21 @@ impl<const LIMBS: usize> Uint<LIMBS> {
 
     /// Perform checked division, returning a [`CtOption`] which `is_some`
     /// only if the rhs != 0
+    ///
+    /// ### Usage:
+    /// ```
+    /// use crypto_bigint::{U448, NonZero, subtle::{CtOption, Choice}};
+    ///
+    /// let a = U448::from(8_u64);
+    /// let result = NonZero::new(U448::from(4_u64))
+    ///     .map(|b| a.div_rem(&b))
+    ///     .expect("Division by zero");
+    ///
+    /// assert_eq!(result.0, U448::from(2_u64));
+    ///
+    /// // Check division by zero
+    /// let zero = U448::from(0_u64);
+    /// assert!(<Choice as Into<bool>>::into(a.checked_div(&zero).is_none()), "Should be None for division by zero");
     pub fn checked_div(&self, rhs: &Self) -> CtOption<Self> {
         NonZero::new(*rhs).map(|rhs| {
             let (q, _r) = self.div_rem(&rhs);
@@ -205,6 +297,17 @@ impl<const LIMBS: usize> Uint<LIMBS> {
     /// This function exists, so that all operations are accounted for in the wrapping operations.
     ///
     /// Panics if `rhs == 0`.
+    ///
+    /// ### Usage:
+    /// ```
+    /// use crypto_bigint::U448;
+    ///
+    /// let a = U448::from(10_u64);
+    /// let b = U448::from(3_u64);
+    /// let remainder = a.wrapping_rem(&b);
+    ///
+    /// assert_eq!(remainder, U448::from(1_u64));
+    /// ```
     pub const fn wrapping_rem(&self, rhs: &Self) -> Self {
         let (r, c) = self.const_rem(rhs);
         assert!(c.is_true_vartime(), "modulo zero");
@@ -213,6 +316,21 @@ impl<const LIMBS: usize> Uint<LIMBS> {
 
     /// Perform checked reduction, returning a [`CtOption`] which `is_some`
     /// only if the rhs != 0
+    ///
+    /// ### Usage:
+    /// ```
+    /// use crypto_bigint::{U448, NonZero, subtle::{Choice,CtOption}};
+    ///
+    /// let a = U448::from(10_u64);
+    /// let remainder_option = NonZero::new(U448::from(3_u64))
+    ///     .map(|b| a.rem(&b));
+    ///
+    /// assert!(<Choice as Into<bool>>::into(remainder_option.is_some()), "Reduction by zero");
+    ///
+    /// // Check reduction by zero
+    /// let zero = U448::from(0_u64);
+    /// assert!(<Choice as Into<bool>>::into(a.checked_rem(&zero).is_none()), "Should be None for reduction by zero");
+    /// ```
     pub fn checked_rem(&self, rhs: &Self) -> CtOption<Self> {
         NonZero::new(*rhs).map(|rhs| self.rem(&rhs))
     }