Merge rust-bitcoin#5326: Backport checked div by weight to 0.32.x

e8ce988 Add checked weight division to Amount (yancy)

Pull request description:

  For comparison, in units 1.0 rc, the counterpart test is here: https://github.com/rust-bitcoin/rust-bitcoin/blob/master/units/src/fee.rs#L190


ACKs for top commit:
  apoelstra:
    ACK e8ce988; successfully ran local tests; noting that `div_ceil` is not yet available in the 0.32.x MSRV
  tcharding:
    ACK e8ce988


Tree-SHA512: 381b57c2dcc3c46ca61f88a16caa0d8a396efa5be7b0f13ad1dc30412da14dd35cb7afbaca140970193eeb44f952bd2aea50b4bb0f519a6336db196bad62400d

Author: apoelstra

units/src/amount.rs

@@ -18,6 +18,9 @@ use ::serde::{Deserialize, Serialize};
 use internals::error::InputString;
 use internals::write_err;
 
+#[cfg(feature = "alloc")]
+use crate::{FeeRate, Weight};
+
 /// A set of denominations in which amounts can be expressed.
 ///
 /// # Examples
@@ -1039,6 +1042,34 @@ impl Amount {
     /// Returns [None] if overflow occurred.
     pub fn checked_div(self, rhs: u64) -> Option<Amount> { self.0.checked_div(rhs).map(Amount) }
 
+    /// Checked weight ceiling division.
+    ///
+    /// Be aware that integer division loses the remainder if no exact division
+    /// can be made.  This method rounds up ensuring the transaction fee-rate is
+    /// sufficient.  See also [`Amount::div_by_weight_floor`].
+    ///
+    /// [`None`] is returned if an overflow occurred.
+    #[cfg(feature = "alloc")]
+    pub fn div_by_weight_ceil(self, rhs: Weight) -> Option<FeeRate> {
+        let sats = self.0.checked_mul(1000)?;
+        let wu = rhs.to_wu();
+
+        let fee_rate = sats.checked_add(wu.checked_sub(1)?)?.checked_div(wu)?;
+        Some(FeeRate::from_sat_per_kwu(fee_rate))
+    }
+
+    /// Checked weight floor division.
+    ///
+    /// Be aware that integer division loses the remainder if no exact division
+    /// can be made.  See also [`Amount::div_by_weight_ceil`].
+    ///
+    /// Returns [`None`] if overflow occurred.
+    #[cfg(feature = "alloc")]
+    pub fn div_by_weight_floor(self, rhs: Weight) -> Option<FeeRate> {
+        let fee_rate = self.0.checked_mul(1_000)?.checked_div(rhs.to_wu())?;
+        Some(FeeRate::from_sat_per_kwu(fee_rate))
+    }
+
     /// Checked remainder.
     ///
     /// Returns [None] if overflow occurred.
@@ -2117,6 +2148,48 @@ mod tests {
         assert_eq!(ssat(-6).checked_div(2), Some(ssat(-3)));
     }
 
+    #[cfg(feature = "alloc")]
+    #[test]
+    fn amount_checked_div_by_weight_ceil() {
+        let weight = Weight::from_kwu(1).unwrap();
+        let fee_rate = Amount::from_sat(1).div_by_weight_ceil(weight).unwrap();
+        // 1 sats / 1,000 wu = 1 sats/kwu
+        assert_eq!(fee_rate, FeeRate::from_sat_per_kwu(1));
+
+        let weight = Weight::from_wu(381);
+        let fee_rate = Amount::from_sat(329).div_by_weight_ceil(weight).unwrap();
+        // 329 sats / 381 wu = 863.5 sats/kwu
+        // round up to 864
+        assert_eq!(fee_rate, FeeRate::from_sat_per_kwu(864));
+
+        let fee_rate = Amount::MAX.div_by_weight_ceil(weight);
+        assert!(fee_rate.is_none());
+
+        let fee_rate = Amount::ONE_SAT.div_by_weight_ceil(Weight::ZERO);
+        assert!(fee_rate.is_none());
+    }
+
+    #[cfg(feature = "alloc")]
+    #[test]
+    fn amount_checked_div_by_weight_floor() {
+        let weight = Weight::from_kwu(1).unwrap();
+        let fee_rate = Amount::from_sat(1).div_by_weight_floor(weight).unwrap();
+        // 1 sats / 1,000 wu = 1 sats/kwu
+        assert_eq!(fee_rate, FeeRate::from_sat_per_kwu(1));
+
+        let weight = Weight::from_wu(381);
+        let fee_rate = Amount::from_sat(329).div_by_weight_floor(weight).unwrap();
+        // 329 sats / 381 wu = 863.5 sats/kwu
+        // round down to 863
+        assert_eq!(fee_rate, FeeRate::from_sat_per_kwu(863));
+
+        let fee_rate = Amount::MAX.div_by_weight_floor(weight);
+        assert!(fee_rate.is_none());
+
+        let fee_rate = Amount::ONE_SAT.div_by_weight_floor(Weight::ZERO);
+        assert!(fee_rate.is_none());
+    }
+
     #[test]
     #[cfg(not(debug_assertions))]
     fn unchecked_amount_add() {