Merge rust-bitcoin#4216: Replace underflow with overflow in doc comments

a273814 Replace underflow with overflow in doc comments (yancy) 2f897e2 Remove warning section (yancy) Pull request description: The use of underflow is misleading. Adding one to MAX and subtracting one from MIN are both considered an overflow. Note I tried to keep to 80 column line length so a paragraph needed some shuffling. closes rust-bitcoin#4187 ACKs for top commit: Kixunil: ACK a273814 tcharding: ACK a273814 apoelstra: ACK a273814; successfully ran local tests Tree-SHA512: 3d1fd3a6c3e11694d189086b6f9e14d55b912497dca8bac2153cc54afbbbee527cae354e60781f8b61591b13aa85fb9e490cea2e7aed3dd9d3e4335502ffb84b
tcharding · Mar 10, 2025 · 540038d · 540038d
2 parents 3bb1a7a + a273814
commit 540038d
Show file tree

Hide file tree

Showing 5 changed files with 6 additions and 17 deletions.
diff --git a/bitcoin/src/blockdata/script/instruction.rs b/bitcoin/src/blockdata/script/instruction.rs
@@ -231,7 +231,7 @@ impl<'a> InstructionIndices<'a> {
         let prev_remaining = self.remaining_bytes();
         let prev_pos = self.pos;
         let instruction = next_fn(self)?;
-        // No underflow: there must be less remaining bytes now than previously
+        // No overflow: there must be less remaining bytes now than previously
         let consumed = prev_remaining - self.remaining_bytes();
         // No overflow: sum will never exceed slice length which itself can't exceed `usize`
         self.pos += consumed;

diff --git a/bitcoin/src/taproot/serialized_signature.rs b/bitcoin/src/taproot/serialized_signature.rs
@@ -217,7 +217,7 @@ mod into_iter {
 
         #[inline]
         fn size_hint(&self) -> (usize, Option<usize>) {
-            // can't underflow thanks to the invariant
+            // can't overflow thanks to the invariant
             let len = self.signature.len() - self.pos;
             (len, Some(len))
         }

diff --git a/units/src/amount/mod.rs b/units/src/amount/mod.rs
@@ -588,8 +588,8 @@ enum DisplayStyle {
 
 /// Calculates the sum over the iterator using checked arithmetic.
 pub trait CheckedSum<R>: sealed::Sealed<R> {
-    /// Calculates the sum over the iterator using checked arithmetic. If an over or underflow would
-    /// happen it returns [`None`].
+    /// Calculates the sum over the iterator using checked arithmetic. If an
+    /// overflow happens it returns [`None`].
     fn checked_sum(self) -> Option<R>;
 }
 

diff --git a/units/src/amount/signed.rs b/units/src/amount/signed.rs
@@ -25,10 +25,10 @@ use super::{
 /// Warning!
 ///
 /// This type implements several arithmetic operations from [`core::ops`].
-/// To prevent errors due to overflow or underflow when using these operations,
+/// To prevent errors due to an overflow when using these operations,
 /// it is advised to instead use the checked arithmetic methods whose names
 /// start with `checked_`. The operations from [`core::ops`] that [`SignedAmount`]
-/// implements will panic when overflow or underflow occurs.
+/// implements will panic when an overflow occurs.
 ///
 /// # Examples
 ///

diff --git a/units/src/amount/unsigned.rs b/units/src/amount/unsigned.rs
@@ -22,17 +22,6 @@ use super::{
 /// conversion to various denominations. The [`Amount`] type does not implement [`serde`] traits
 /// but we do provide modules for serializing as satoshis or bitcoin.
 ///
-/// Warning!
-///
-/// This type implements several arithmetic operations from [`core::ops`].
-/// To prevent errors due to overflow or underflow when using these operations,
-/// it is advised to instead use the checked arithmetic methods whose names
-/// start with `checked_`. The operations from [`core::ops`] that [`Amount`]
-/// implements will panic when overflow or underflow occurs. Also note that
-/// since the internal representation of amounts is unsigned, subtracting below
-/// zero is considered an underflow and will cause a panic if you're not using
-/// the checked arithmetic methods.
-///
 /// # Examples
 ///
 /// ```