crypto-bigint 0.7.8

//! Limb subtraction

use crate::{
    Checked, CheckedSub, CtOption, Limb, Sub, SubAssign, SubMod, Wrapping, WrappingSub, word,
};

impl Limb {
    /// Computes `self - (rhs + borrow)`, returning the result along with the new borrow.
    #[deprecated(since = "0.7.0", note = "please use `borrowing_sub` instead")]
    #[must_use]
    pub const fn sbb(self, rhs: Limb, borrow: Limb) -> (Limb, Limb) {
        self.borrowing_sub(rhs, borrow)
    }

    /// Computes `self - (rhs + borrow)`, returning the result along with the new borrow.
    #[inline(always)]
    #[must_use]
    pub const fn borrowing_sub(self, rhs: Limb, borrow: Limb) -> (Limb, Limb) {
        let (res, borrow) = word::borrowing_sub(self.0, rhs.0, word::choice_from_msb(borrow.0));
        (Limb(res), Limb(word::choice_to_mask(borrow)))
    }

    /// Perform saturating subtraction.
    #[inline]
    #[must_use]
    pub const fn saturating_sub(&self, rhs: Self) -> Self {
        Limb(self.0.saturating_sub(rhs.0))
    }

    /// Perform wrapping subtraction, discarding underflow and wrapping around
    /// the boundary of the type.
    #[inline(always)]
    #[must_use]
    pub const fn wrapping_sub(&self, rhs: Self) -> Self {
        Limb(self.0.wrapping_sub(rhs.0))
    }
}

impl CheckedSub for Limb {
    #[inline]
    fn checked_sub(&self, rhs: &Self) -> CtOption<Self> {
        let (result, underflow) = self.borrowing_sub(*rhs, Limb::ZERO);
        CtOption::new(result, underflow.is_zero())
    }
}

impl Sub for Limb {
    type Output = Self;

    #[inline]
    fn sub(self, rhs: Self) -> Self {
        self.checked_sub(&rhs)
            .expect("attempted to subtract with underflow")
    }
}

impl Sub<&Self> for Limb {
    type Output = Self;

    #[inline]
    fn sub(self, rhs: &Self) -> Self {
        self - *rhs
    }
}

impl SubAssign for Limb {
    #[inline]
    fn sub_assign(&mut self, rhs: Self) {
        *self = *self - rhs;
    }
}

impl SubAssign<&Self> for Limb {
    #[inline]
    fn sub_assign(&mut self, rhs: &Self) {
        *self = *self - *rhs;
    }
}

impl SubAssign for Wrapping<Limb> {
    #[inline]
    fn sub_assign(&mut self, other: Self) {
        *self = *self - other;
    }
}

impl SubAssign<&Wrapping<Limb>> for Wrapping<Limb> {
    #[inline]
    fn sub_assign(&mut self, other: &Self) {
        *self = *self - other;
    }
}

impl SubAssign for Checked<Limb> {
    #[inline]
    fn sub_assign(&mut self, other: Self) {
        *self = *self - other;
    }
}

impl SubAssign<&Checked<Limb>> for Checked<Limb> {
    #[inline]
    fn sub_assign(&mut self, other: &Self) {
        *self = *self - other;
    }
}

impl WrappingSub for Limb {
    #[inline]
    fn wrapping_sub(&self, v: &Self) -> Self {
        self.wrapping_sub(*v)
    }
}

impl SubMod for Limb {
    type Output = Self;

    fn sub_mod(&self, rhs: &Self, p: &crate::NonZero<Self>) -> Self::Output {
        let (res, borrow) = self.borrowing_sub(*rhs, Limb::ZERO);
        Self::select(res, res.wrapping_add(p.get()), borrow.is_nonzero())
    }
}

#[cfg(test)]
mod tests {
    use crate::{CheckedSub, Limb};

    #[test]
    fn borrowing_sub_boundary_values() {
        use crate::{Limb, Word};

        let msb = 1 << (Word::BITS - 1);
        let values = [0, 1, 2, msb - 1, msb, msb + 1, Word::MAX - 1, Word::MAX];
        let borrows = [0, 1, msb, Word::MAX];

        for lhs in values {
            for rhs in values {
                for borrow in borrows {
                    let (ret, borrow1) = lhs.overflowing_sub(borrow >> (Word::BITS - 1));
                    let (expected, borrow2) = ret.overflowing_sub(rhs);
                    let expected_borrow = Word::from(borrow1 | borrow2).wrapping_neg();

                    assert_eq!(
                        Limb(lhs).borrowing_sub(Limb(rhs), Limb(borrow)),
                        (Limb(expected), Limb(expected_borrow)),
                        "lhs={lhs:#x}, rhs={rhs:#x}, borrow={borrow:#x}"
                    );
                }
            }
        }
    }

    #[test]
    fn borrowing_sub_no_borrow() {
        let (res, borrow) = Limb::ONE.borrowing_sub(Limb::ONE, Limb::ZERO);
        assert_eq!(res, Limb::ZERO);
        assert_eq!(borrow, Limb::ZERO);
    }

    #[test]
    fn borrowing_sub_with_borrow() {
        let (res, borrow) = Limb::ZERO.borrowing_sub(Limb::ONE, Limb::ZERO);

        assert_eq!(res, Limb::MAX);
        assert_eq!(borrow, Limb::MAX);
    }

    #[test]
    fn wrapping_sub_no_borrow() {
        assert_eq!(Limb::ONE.wrapping_sub(Limb::ONE), Limb::ZERO);
    }

    #[test]
    fn wrapping_sub_with_borrow() {
        assert_eq!(Limb::ZERO.wrapping_sub(Limb::ONE), Limb::MAX);
    }

    #[test]
    fn checked_sub_ok() {
        let result = Limb::ONE.checked_sub(&Limb::ONE);
        assert_eq!(result.unwrap(), Limb::ZERO);
    }

    #[test]
    fn checked_sub_overflow() {
        let result = Limb::ZERO.checked_sub(&Limb::ONE);
        assert!(!bool::from(result.is_some()));
    }
}