Merge rust-bitcoin/rust-bitcoin#3381: Add FeeRate addition and subtraction traits

cb2146d5fa Implement FeeRate checked_sub (yancy)
212a751929 Implement FeeRate checked_add (yancy)
c967eabd43 Implement FeeRate SubAssign (yancy)
c3a8bfa98d Implement FeeRate AddAssign (yancy)
0e70870056 Implement FeeRate subtraction (yancy)
86359fe364 Implement FeeRate addition (yancy)

Pull request description:

  I can't think of a reason to not support addition and subtraction with `fee_rate`.  If two fee rates are added, the resulting units `sat/wu` units are viable.

  Without this, I have to do some shenanigans like:

  ```rust
  let tmp = fee_rate.to_sat_per_kwu();
  fee_rate = FeeRate::from_sat_per_kwu(tmp - 1);
  ```

ACKs for top commit:
  apoelstra:
    ACK cb2146d5fa successfully ran local tests
  tcharding:
    ACK cb2146d5fa

Tree-SHA512: 582c5e75e836df4a8aa00b928a9e81a04ba8c14a8986fac323f608d05468531b17034f42db23af57468b3220151bb6b37b90da4f1621571f011b89491070c619

units/src/fee_rate.rs

@@ -3,7 +3,7 @@
 //! Implements `FeeRate` and assoctiated features.
 
 use core::fmt;
-use core::ops::{Div, Mul};
+use core::ops::{Add, Sub, Div, Mul, AddAssign, SubAssign};
 
 #[cfg(feature = "arbitrary")]
 use arbitrary::{Arbitrary, Unstructured};
@@ -96,6 +96,16 @@ impl FeeRate {
         Some(Amount::from_sat(sats))
     }
 
+    /// Checked addition.
+    ///
+    /// Computes `self + rhs` returning [`None`] if overflow occured.
+    pub fn checked_add(self, rhs: u64) -> Option<Self> { self.0.checked_add(rhs).map(Self) }
+
+    /// Checked subtraction.
+    ///
+    /// Computes `self - rhs` returning [`None`] if overflow occured.
+    pub fn checked_sub(self, rhs: u64) -> Option<Self> { self.0.checked_sub(rhs).map(Self) }
+
     /// Calculates the fee by multiplying this fee rate by weight, in weight units, returning [`None`]
     /// if an overflow occurred.
     ///
@@ -135,6 +145,66 @@ impl From<FeeRate> for u64 {
     fn from(value: FeeRate) -> Self { value.to_sat_per_kwu() }
 }
 
+impl Add for FeeRate {
+    type Output = FeeRate;
+
+    fn add(self, rhs: FeeRate) -> Self::Output { FeeRate(self.0 + rhs.0) }
+}
+
+impl Add<FeeRate> for &FeeRate {
+    type Output = FeeRate;
+
+    fn add(self, other: FeeRate) -> <FeeRate as Add>::Output {
+        FeeRate(self.0 + other.0)
+    }
+}
+
+impl Add<&FeeRate> for FeeRate {
+    type Output = FeeRate;
+
+    fn add(self, other: &FeeRate) -> <FeeRate as Add>::Output {
+        FeeRate(self.0 + other.0)
+    }
+}
+
+impl<'a, 'b> Add<&'a FeeRate> for &'b FeeRate {
+    type Output = FeeRate;
+
+    fn add(self, other: &'a FeeRate) -> <FeeRate as Add>::Output {
+        FeeRate(self.0 + other.0)
+    }
+}
+
+impl Sub for FeeRate {
+    type Output = FeeRate;
+
+    fn sub(self, rhs: FeeRate) -> Self::Output { FeeRate(self.0 - rhs.0) }
+}
+
+impl Sub<FeeRate> for &FeeRate {
+    type Output = FeeRate;
+
+    fn sub(self, other: FeeRate) -> <FeeRate as Add>::Output {
+        FeeRate(self.0 - other.0)
+    }
+}
+
+impl Sub<&FeeRate> for FeeRate {
+    type Output = FeeRate;
+
+    fn sub(self, other: &FeeRate) -> <FeeRate as Add>::Output {
+        FeeRate(self.0 - other.0)
+    }
+}
+
+impl<'a, 'b> Sub<&'a FeeRate> for &'b FeeRate {
+    type Output = FeeRate;
+
+    fn sub(self, other: &'a FeeRate) -> <FeeRate as Add>::Output {
+        FeeRate(self.0 - other.0)
+    }
+}
+
 /// Computes the ceiling so that the fee computation is conservative.
 impl Mul<FeeRate> for Weight {
     type Output = Amount;
@@ -156,12 +226,94 @@ impl Div<Weight> for Amount {
     fn div(self, rhs: Weight) -> Self::Output { FeeRate(self.to_sat() * 1000 / rhs.to_wu()) }
 }
 
+impl AddAssign for FeeRate {
+    fn add_assign(&mut self, rhs: Self) { self.0 += rhs.0 }
+}
+
+impl AddAssign<&FeeRate> for FeeRate {
+    fn add_assign(&mut self, rhs: &FeeRate) { self.0 += rhs.0 }
+}
+
+impl SubAssign for FeeRate {
+    fn sub_assign(&mut self, rhs: Self) { self.0 -= rhs.0 }
+}
+
+impl SubAssign<&FeeRate> for FeeRate {
+    fn sub_assign(&mut self, rhs: &FeeRate) { self.0 -= rhs.0 }
+}
+
 crate::impl_parse_str_from_int_infallible!(FeeRate, u64, from_sat_per_kwu);
 
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    #[test]
+    #[allow(clippy::op_ref)]
+    fn addition() {
+        let one = FeeRate(1);
+        let two = FeeRate(2);
+        let three = FeeRate(3);
+
+        assert!(one + two == three);
+        assert!(&one + two == three);
+        assert!(one + &two == three);
+        assert!(&one + &two == three);
+    }
+
+    #[test]
+    #[allow(clippy::op_ref)]
+    fn subtract() {
+        let one = FeeRate(1);
+        let two = FeeRate(2);
+        let three = FeeRate(3);
+
+        assert!(three - two == one);
+        assert!(&three - two == one);
+        assert!(three - &two == one);
+        assert!(&three - &two == one);
+    }
+
+    #[test]
+    fn add_assign() {
+        let mut f = FeeRate(1);
+        f += FeeRate(2);
+        assert_eq!(f, FeeRate(3));
+
+        let mut f = FeeRate(1);
+        f += &FeeRate(2);
+        assert_eq!(f, FeeRate(3));
+    }
+
+    #[test]
+    fn sub_assign() {
+        let mut f = FeeRate(3);
+        f -= FeeRate(2);
+        assert_eq!(f, FeeRate(1));
+
+        let mut f = FeeRate(3);
+        f -= &FeeRate(2);
+        assert_eq!(f, FeeRate(1));
+    }
+
+    #[test]
+    fn checked_add() {
+        let f = FeeRate(1).checked_add(2).unwrap();
+        assert_eq!(FeeRate(3), f);
+
+        let f = FeeRate(u64::MAX).checked_add(1);
+        assert!(f.is_none());
+    }
+
+    #[test]
+    fn checked_sub() {
+        let f = FeeRate(2).checked_sub(1).unwrap();
+        assert_eq!(FeeRate(1), f);
+
+        let f = FeeRate::ZERO.checked_sub(1);
+        assert!(f.is_none());
+    }
+
     #[test]
     fn fee_rate_const_test() {
         assert_eq!(0, FeeRate::ZERO.to_sat_per_kwu());