From afc0ce617554303d7fd25e052b039af44b6efc1c Mon Sep 17 00:00:00 2001
From: "Tobin C. Harding" <me@tobin.cc>
Date: Mon, 9 Jun 2025 00:09:46 +1000
Subject: [PATCH] units: Add must_use to checked arithmetic functions

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.
---
 units/src/block.rs | 8 ++++++++
 units/src/fee.rs   | 2 ++
 2 files changed, 10 insertions(+)

diff --git a/units/src/block.rs b/units/src/block.rs
index 8eb193218..c4a02cd9a 100644
--- a/units/src/block.rs
+++ b/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) }
 }
 
diff --git a/units/src/fee.rs b/units/src/fee.rs
index 09bccb741..8248a9957 100644
--- a/units/src/fee.rs
+++ b/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)
     }