Merge rust-bitcoin/rust-bitcoin#4603: units: Add `must_use` to checked arithmetic functions

afc0ce6175 units: Add must_use to checked arithmetic functions (Tobin C. Harding)

Pull request description:

  The checked arithmetic functions all consume self so we use `must_use` to help users not miss this point.

  Most are done, add the missing ones.

ACKs for top commit:
  apoelstra:
    ACK afc0ce617554303d7fd25e052b039af44b6efc1c; successfully ran local tests

Tree-SHA512: 7105affff43827ed47a1c0b6e41a996aa538c7d53b891faf03e79a83164706d7e86db5fb184ac740fdf57bb43f8401a496cc64ea4da0da71eaa8c8cca16444c7

units/src/block.rs

@@ -88,11 +88,13 @@ impl BlockHeight {
     pub const fn to_u32(self) -> u32 { self.0 }
 
     /// Attempt to subtract two [`BlockHeight`]s, returning `None` in case of overflow.
+    #[must_use]
     pub fn checked_sub(self, other: Self) -> Option<BlockHeightInterval> {
         self.0.checked_sub(other.0).map(BlockHeightInterval)
     }
 
     /// Attempt to add an interval to this [`BlockHeight`], returning `None` in case of overflow.
+    #[must_use]
     pub fn checked_add(self, other: BlockHeightInterval) -> Option<Self> {
         self.0.checked_add(other.0).map(Self)
     }
@@ -147,9 +149,11 @@ impl BlockHeightInterval {
     pub const fn to_u32(self) -> u32 { self.0 }
 
     /// Attempt to subtract two [`BlockHeightInterval`]s, returning `None` in case of overflow.
+    #[must_use]
     pub fn checked_sub(self, other: Self) -> Option<Self> { self.0.checked_sub(other.0).map(Self) }
 
     /// Attempt to add two [`BlockHeightInterval`]s, returning `None` in case of overflow.
+    #[must_use]
     pub fn checked_add(self, other: Self) -> Option<Self> { self.0.checked_add(other.0).map(Self) }
 }
 
@@ -217,11 +221,13 @@ impl BlockMtp {
     }
 
     /// Attempt to subtract two [`BlockMtp`]s, returning `None` in case of overflow.
+    #[must_use]
     pub fn checked_sub(self, other: Self) -> Option<BlockMtpInterval> {
         self.0.checked_sub(other.0).map(BlockMtpInterval)
     }
 
     /// Attempt to add an interval to this [`BlockMtp`], returning `None` in case of overflow.
+    #[must_use]
     pub fn checked_add(self, other: BlockMtpInterval) -> Option<Self> {
         self.0.checked_add(other.0).map(Self)
     }
@@ -308,9 +314,11 @@ impl BlockMtpInterval {
     }
 
     /// Attempt to subtract two [`BlockMtpInterval`]s, returning `None` in case of overflow.
+    #[must_use]
     pub fn checked_sub(self, other: Self) -> Option<Self> { self.0.checked_sub(other.0).map(Self) }
 
     /// Attempt to add two [`BlockMtpInterval`]s, returning `None` in case of overflow.
+    #[must_use]
     pub fn checked_add(self, other: Self) -> Option<Self> { self.0.checked_add(other.0).map(Self) }
 }
 

units/src/fee.rs

@@ -161,6 +161,7 @@ impl FeeRate {
     /// enough instead of falling short if rounded down.
     ///
     /// Returns [`None`] if overflow occurred.
+    #[must_use]
     pub const fn checked_mul_by_weight(self, weight: Weight) -> Option<Amount> {
         let wu = weight.to_wu();
         if let Some(fee_kwu) = self.to_sat_per_kwu_floor().checked_mul(wu) {
@@ -348,6 +349,7 @@ impl Weight {
     /// enough instead of falling short if rounded down.
     ///
     /// Returns [`None`] if overflow occurred.
+    #[must_use]
     pub const fn checked_mul_by_fee_rate(self, fee_rate: FeeRate) -> Option<Amount> {
         fee_rate.checked_mul_by_weight(self)
     }