Merge rust-bitcoin/rust-bitcoin#3539: Improve the `amount` module

81d8699b55 units: Put no_std up top (Tobin C. Harding)
3e332c3839 amount: Fix docs on FromStr (Tobin C. Harding)
5bec76aa51 amount: Fix rustdocs (Tobin C. Harding)
41c80cc476 amount: Improve docs on div by weight (Tobin C. Harding)
2b4a61739a Add type to debug output for Amount (Tobin C. Harding)
42e5043b33 Add from_int_btc group of functions (Tobin C. Harding)

Pull request description:

  Improve the `amount` module by doing:

  - Patch 1: Add/update `from_int_btc` and `from_int_btc_const` functions
  - Patch 2:  Add type to debug output for `Amount`
  - Patch 3: Fix incorrect docs
  - Patch 4: Make docs use correct style and be uniform across the two amount types
  - Patch 5: Fix docs on `FromStr`

ACKs for top commit:
  apoelstra:
    ACK 81d8699b55dad570247cb14d2b3eea64270a83cf; successfully ran local tests
  jamillambert:
    ACK 81d8699b55

Tree-SHA512: ddd6e02b4cd9a9aa8cbdd2d2f7ae289a6bcca9eb002ef0c6d83a6eca950b2cd08f5918286bb33e814f321e3bfe83fdf75ae051cf8f91ee45d3e4abe76c1c2a4c

bitcoin/examples/taproot-psbt.rs

@@ -49,7 +49,7 @@ const UTXO_1: P2trUtxo = P2trUtxo {
     script_pubkey: UTXO_SCRIPT_PUBKEY,
     pubkey: UTXO_PUBKEY,
     master_fingerprint: UTXO_MASTER_FINGERPRINT,
-    amount_in_sats: Amount::from_int_btc(50),
+    amount_in_sats: Amount::from_int_btc_const(50),
     derivation_path: BIP86_DERIVATION_PATH,
 };
 
@@ -60,7 +60,7 @@ const UTXO_2: P2trUtxo = P2trUtxo {
     script_pubkey: UTXO_SCRIPT_PUBKEY,
     pubkey: UTXO_PUBKEY,
     master_fingerprint: UTXO_MASTER_FINGERPRINT,
-    amount_in_sats: Amount::from_int_btc(50),
+    amount_in_sats: Amount::from_int_btc_const(50),
     derivation_path: BIP86_DERIVATION_PATH,
 };
 
@@ -71,7 +71,7 @@ const UTXO_3: P2trUtxo = P2trUtxo {
     script_pubkey: UTXO_SCRIPT_PUBKEY,
     pubkey: UTXO_PUBKEY,
     master_fingerprint: UTXO_MASTER_FINGERPRINT,
-    amount_in_sats: Amount::from_int_btc(50),
+    amount_in_sats: Amount::from_int_btc_const(50),
     derivation_path: BIP86_DERIVATION_PATH,
 };
 

units/src/amount/signed.rs

@@ -46,19 +46,49 @@ impl SignedAmount {
     /// The maximum value of an amount.
     pub const MAX: SignedAmount = SignedAmount(i64::MAX);
 
-    /// Create an [`SignedAmount`] with satoshi precision and the given number of satoshis.
+    /// Creates a [`SignedAmount`] with satoshi precision and the given number of satoshis.
     pub const fn from_sat(satoshi: i64) -> SignedAmount { SignedAmount(satoshi) }
 
     /// Gets the number of satoshis in this [`SignedAmount`].
     pub const fn to_sat(self) -> i64 { self.0 }
 
-    /// Convert from a value expressing bitcoins to an [`SignedAmount`].
+    /// Converts from a value expressing a whole number of bitcoin to a [`SignedAmount`].
     #[cfg(feature = "alloc")]
     pub fn from_btc(btc: f64) -> Result<SignedAmount, ParseAmountError> {
         SignedAmount::from_float_in(btc, Denomination::Bitcoin)
     }
 
-    /// Parse a decimal string as a value in the given denomination.
+    /// Converts from a value expressing a whole number of bitcoin to a [`SignedAmount`].
+    ///
+    /// # Errors
+    ///
+    /// The function errors if the argument multiplied by the number of sats
+    /// per bitcoin overflows an `i64` type.
+    pub fn from_int_btc(btc: i64) -> Result<SignedAmount, OutOfRangeError> {
+        match btc.checked_mul(100_000_000) {
+            Some(amount) => Ok(SignedAmount::from_sat(amount)),
+            None => Err(OutOfRangeError {
+                is_signed: true,
+                is_greater_than_max: true,
+            })
+        }
+    }
+
+    /// Converts from a value expressing a whole number of bitcoin to a [`SignedAmount`]
+    /// in const context.
+    ///
+    /// # Panics
+    ///
+    /// The function panics if the argument multiplied by the number of sats
+    /// per bitcoin overflows an `i64` type.
+    pub const fn from_int_btc_const(btc: i64) -> SignedAmount {
+        match btc.checked_mul(100_000_000) {
+            Some(amount) => SignedAmount::from_sat(amount),
+            None => panic!("checked_mul overflowed"),
+        }
+    }
+
+    /// Parses a decimal string as a value in the given denomination.
     ///
     /// Note: This only parses the value string.  If you want to parse a value
     /// with denomination, use [`FromStr`].
@@ -75,10 +105,10 @@ impl SignedAmount {
         }
     }
 
-    /// Parses amounts with denomination suffix like they are produced with
+    /// Parses amounts with denomination suffix as produced by [`Self::to_string_with_denomination`]
-    /// [`Self::to_string_with_denomination`] or with [`fmt::Display`].
+    /// or with [`fmt::Display`].
-    /// If you want to parse only the amount without the denomination,
+    ///
-    /// use [`Self::from_str_in`].
+    /// If you want to parse only the amount without the denomination, use [`Self::from_str_in`].
     pub fn from_str_with_denomination(s: &str) -> Result<SignedAmount, ParseError> {
         let (amt, denom) = split_amount_and_denomination(s)?;
         SignedAmount::from_str_in(amt, denom).map_err(Into::into)
@@ -94,9 +124,15 @@ impl SignedAmount {
 
     /// Express this [`SignedAmount`] as a floating-point value in Bitcoin.
     ///
-    /// Equivalent to `to_float_in(Denomination::Bitcoin)`.
-    ///
     /// Please be aware of the risk of using floating-point numbers.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use bitcoin_units::amount::{SignedAmount, Denomination};
+    /// let amount = SignedAmount::from_sat(100_000);
+    /// assert_eq!(amount.to_btc(), amount.to_float_in(Denomination::Bitcoin))
+    /// ```
     #[cfg(feature = "alloc")]
     pub fn to_btc(self) -> f64 { self.to_float_in(Denomination::Bitcoin) }
 
@@ -118,7 +154,7 @@ impl SignedAmount {
         SignedAmount::from_str_in(&value.to_string(), denom)
     }
 
-    /// Create an object that implements [`fmt::Display`] using specified denomination.
+    /// Creates an object that implements [`fmt::Display`] using specified denomination.
     pub fn display_in(self, denomination: Denomination) -> Display {
         Display {
             sats_abs: self.unsigned_abs().to_sat(),
@@ -127,7 +163,7 @@ impl SignedAmount {
         }
     }
 
-    /// Create an object that implements [`fmt::Display`] dynamically selecting denomination.
+    /// Creates an object that implements [`fmt::Display`] dynamically selecting denomination.
     ///
     /// This will use BTC for values greater than or equal to 1 BTC and satoshis otherwise. To
     /// avoid confusion the denomination is always shown.
@@ -139,7 +175,7 @@ impl SignedAmount {
         }
     }
 
-    /// Format the value of this [`SignedAmount`] in the given denomination.
+    /// Formats the value of this [`SignedAmount`] in the given denomination.
     ///
     /// Does not include the denomination.
     #[rustfmt::skip]
@@ -148,14 +184,14 @@ impl SignedAmount {
         fmt_satoshi_in(self.unsigned_abs().to_sat(), self.is_negative(), f, denom, false, FormatOptions::default())
     }
 
-    /// Get a string number of this [`SignedAmount`] in the given denomination.
+    /// Returns a formatted string representing this [`SignedAmount`] in the given denomination.
     ///
     /// Does not include the denomination.
     #[cfg(feature = "alloc")]
     pub fn to_string_in(self, denom: Denomination) -> String { self.display_in(denom).to_string() }
 
-    /// Get a formatted string of this [`SignedAmount`] in the given denomination,
+    /// Returns a formatted string representing this [`Amount`] in the given denomination, suffixed
-    /// suffixed with the abbreviation for the denomination.
+    /// with the abbreviation for the denomination.
     #[cfg(feature = "alloc")]
     pub fn to_string_with_denomination(self, denom: Denomination) -> String {
         self.display_in(denom).show_denomination().to_string()
@@ -166,7 +202,7 @@ impl SignedAmount {
     /// Get the absolute value of this [`SignedAmount`].
     pub fn abs(self) -> SignedAmount { SignedAmount(self.0.abs()) }
 
-    /// Get the absolute value of this [`SignedAmount`] returning [`Amount`].
+    /// Gets the absolute value of this [`SignedAmount`] returning [`Amount`].
     pub fn unsigned_abs(self) -> Amount { Amount::from_sat(self.0.unsigned_abs()) }
 
     /// Returns a number representing sign of this [`SignedAmount`].
@@ -218,8 +254,7 @@ impl SignedAmount {
 
     /// Checked integer division.
     ///
-    /// Be aware that integer division loses the remainder if no exact division
+    /// Be aware that integer division loses the remainder if no exact division can be made.
-    /// can be made.
     ///
     /// Returns [`None`] if overflow occurred.
     pub fn checked_div(self, rhs: i64) -> Option<SignedAmount> {
@@ -361,12 +396,7 @@ impl FromStr for SignedAmount {
 
     /// Parses a string slice where the slice includes a denomination.
     ///
-    /// If the string slice is zero or negative zero, then no denomination is required.
+    /// If the returned value would be zero or negative zero, then no denomination is required.
-    ///
-    /// # Returns
-    ///
-    /// `Ok(Amount)` if the string amount and denomination parse successfully,
-    /// otherwise, return `Err(ParseError)`.
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         let result = SignedAmount::from_str_with_denomination(s);
 

units/src/amount/tests.rs

@@ -65,13 +65,13 @@ fn from_str_zero_without_denomination() {
 
 #[test]
 fn from_int_btc() {
-    let amt = Amount::from_int_btc(2);
+    let amt = Amount::from_int_btc_const(2);
     assert_eq!(Amount::from_sat(200_000_000), amt);
 }
 
 #[should_panic]
 #[test]
-fn from_int_btc_panic() { Amount::from_int_btc(u64::MAX); }
+fn from_int_btc_panic() { Amount::from_int_btc_const(u64::MAX); }
 
 #[test]
 fn test_signed_amount_try_from_amount() {

units/src/amount/unsigned.rs

@@ -46,9 +46,9 @@ impl Amount {
     /// Exactly one satoshi.
     pub const ONE_SAT: Amount = Amount(1);
     /// Exactly one bitcoin.
-    pub const ONE_BTC: Amount = Self::from_int_btc(1);
+    pub const ONE_BTC: Amount = Self::from_int_btc_const(1);
     /// The maximum value allowed as an amount. Useful for sanity checking.
-    pub const MAX_MONEY: Amount = Self::from_int_btc(21_000_000);
+    pub const MAX_MONEY: Amount = Self::from_int_btc_const(21_000_000);
     /// The minimum value of an amount.
     pub const MIN: Amount = Amount::ZERO;
     /// The maximum value of an amount.
@@ -62,20 +62,36 @@ impl Amount {
     /// Gets the number of satoshis in this [`Amount`].
     pub const fn to_sat(self) -> u64 { self.0 }
 
-    /// Converts from a value expressing bitcoins to an [`Amount`].
+    /// Converts from a value expressing a whole number of bitcoin to an [`Amount`].
     #[cfg(feature = "alloc")]
     pub fn from_btc(btc: f64) -> Result<Amount, ParseAmountError> {
         Amount::from_float_in(btc, Denomination::Bitcoin)
     }
 
-    /// Converts from a value expressing integer values of bitcoins to an [`Amount`]
+    /// Converts from a value expressing a whole number of bitcoin to an [`Amount`].
+    ///
+    /// # Errors
+    ///
+    /// The function errors if the argument multiplied by the number of sats
+    /// per bitcoin overflows a `u64` type.
+    pub fn from_int_btc(btc: u64) -> Result<Amount, OutOfRangeError> {
+        match btc.checked_mul(100_000_000) {
+            Some(amount) => Ok(Amount::from_sat(amount)),
+            None => Err(OutOfRangeError {
+                is_signed: false,
+                is_greater_than_max: true,
+            })
+        }
+    }
+
+    /// Converts from a value expressing a whole number of bitcoin to an [`Amount`]
     /// in const context.
     ///
     /// # Panics
     ///
     /// The function panics if the argument multiplied by the number of sats
-    /// per bitcoin overflows a u64 type.
+    /// per bitcoin overflows a `u64` type.
-    pub const fn from_int_btc(btc: u64) -> Amount {
+    pub const fn from_int_btc_const(btc: u64) -> Amount {
         match btc.checked_mul(100_000_000) {
             Some(amount) => Amount::from_sat(amount),
             None => panic!("checked_mul overflowed"),
@@ -95,10 +111,10 @@ impl Amount {
         Ok(Amount::from_sat(satoshi))
     }
 
-    /// Parses amounts with denomination suffix like they are produced with
+    /// Parses amounts with denomination suffix as produced by [`Self::to_string_with_denomination`]
-    /// [`Self::to_string_with_denomination`] or with [`fmt::Display`].
+    /// or with [`fmt::Display`].
-    /// If you want to parse only the amount without the denomination,
+    ///
-    /// use [`Self::from_str_in`].
+    /// If you want to parse only the amount without the denomination, use [`Self::from_str_in`].
     pub fn from_str_with_denomination(s: &str) -> Result<Amount, ParseError> {
         let (amt, denom) = split_amount_and_denomination(s)?;
         Amount::from_str_in(amt, denom).map_err(Into::into)
@@ -174,14 +190,14 @@ impl Amount {
         fmt_satoshi_in(self.to_sat(), false, f, denom, false, FormatOptions::default())
     }
 
-    /// Returns a formatted string of this [`Amount`] in the given denomination.
+    /// Returns a formatted string representing this [`Amount`] in the given denomination.
     ///
     /// Does not include the denomination.
     #[cfg(feature = "alloc")]
     pub fn to_string_in(self, denom: Denomination) -> String { self.display_in(denom).to_string() }
 
-    /// Returns a formatted string of this [`Amount`] in the given denomination,
+    /// Returns a formatted string representing this [`Amount`] in the given denomination, suffixed
-    /// suffixed with the abbreviation for the denomination.
+    /// with the abbreviation for the denomination.
     #[cfg(feature = "alloc")]
     pub fn to_string_with_denomination(self, denom: Denomination) -> String {
         self.display_in(denom).show_denomination().to_string()
@@ -210,8 +226,8 @@ impl Amount {
 
     /// Checked integer division.
     ///
-    /// Be aware that integer division loses the remainder if no exact division
+    /// Be aware that integer division loses the remainder if no exact division can be made.
-    /// can be made.
+    ///
     /// Returns [`None`] if overflow occurred.
     pub fn checked_div(self, rhs: u64) -> Option<Amount> { self.0.checked_div(rhs).map(Amount) }
 
@@ -219,9 +235,9 @@ impl Amount {
     ///
     /// 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.  If you wish to round-down, use the unchecked version instead.
+    /// sufficient. If you wish to round down use `amount / weight`.
     ///
-    /// [`None`] is returned if an overflow occurred.
+    /// Returns [`None`] if overflow occurred.
     #[cfg(feature = "alloc")]
     pub fn checked_div_by_weight(self, rhs: Weight) -> Option<FeeRate> {
         let sats = self.0.checked_mul(1000)?;
@@ -269,7 +285,9 @@ impl default::Default for Amount {
 }
 
 impl fmt::Debug for Amount {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { write!(f, "{} SAT", self.to_sat()) }
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "Amount({} SAT)", self.to_sat())
+    }
 }
 
 // No one should depend on a binding contract for Display for this type.
@@ -343,12 +361,7 @@ impl FromStr for Amount {
 
     /// Parses a string slice where the slice includes a denomination.
     ///
-    /// If the string slice is zero, then no denomination is required.
+    /// If the returned value would be zero or negative zero, then no denomination is required.
-    ///
-    /// # Returns
-    ///
-    /// `Ok(Amount)` if the string amount and denomination parse successfully,
-    /// otherwise, return `Err(ParseError)`.
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         let result = Amount::from_str_with_denomination(s);
 

units/src/fee_rate.rs

@@ -211,6 +211,10 @@ impl Mul<Weight> for FeeRate {
 impl Div<Weight> for Amount {
     type Output = FeeRate;
 
+    /// Truncating integer division.
+    ///
+    /// This is likely the wrong thing for a user dividing an amount by a weight. Consider using
+    /// `checked_div_by_weight` instead.
     fn div(self, rhs: Weight) -> Self::Output { FeeRate(self.to_sat() * 1000 / rhs.to_wu()) }
 }
 

units/src/lib.rs

@@ -4,6 +4,7 @@
 //!
 //! This library provides basic types used by the Rust Bitcoin ecosystem.
 
+#![no_std]
 // Experimental features we need.
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 // Coding conventions.
@@ -13,7 +14,6 @@
 // Exclude lints we don't think are valuable.
 #![allow(clippy::needless_question_mark)] // https://github.com/rust-bitcoin/rust-bitcoin/pull/2134
 #![allow(clippy::manual_range_contains)] // More readable than clippy's format.
-#![no_std]
 
 #[cfg(feature = "alloc")]
 extern crate alloc;