From 78f1628bf6702c808cb769372df7742daf0e1731 Mon Sep 17 00:00:00 2001 From: "Jamil Lambert, PhD" Date: Wed, 18 Dec 2024 16:05:35 +0000 Subject: [PATCH] Add Examples to rustdocs --- units/src/amount/signed.rs | 68 ++++++++++++++++++++++++++++++++++++ units/src/amount/unsigned.rs | 27 ++++++++++++++ 2 files changed, 95 insertions(+) diff --git a/units/src/amount/signed.rs b/units/src/amount/signed.rs index 8a0845edd..867c42634 100644 --- a/units/src/amount/signed.rs +++ b/units/src/amount/signed.rs @@ -63,12 +63,35 @@ impl SignedAmount { pub const MAX: Self = SignedAmount::MAX_MONEY; /// Constructs a new [`SignedAmount`] with satoshi precision and the given number of satoshis. + /// + /// # Examples + /// + /// ``` + /// # use bitcoin_units::SignedAmount; + /// let amount = SignedAmount::from_sat(-100_000); + /// assert_eq!(amount.to_sat(), -100_000); + /// ``` pub const fn from_sat(satoshi: i64) -> SignedAmount { SignedAmount(satoshi) } /// Gets the number of satoshis in this [`SignedAmount`]. + /// + /// # Examples + /// + /// ``` + /// # use bitcoin_units::SignedAmount; + /// assert_eq!(SignedAmount::ONE_BTC.to_sat(), 100_000_000); + /// ``` pub const fn to_sat(self) -> i64 { self.0 } /// Converts from a value expressing a decimal number of bitcoin to a [`SignedAmount`]. + /// + /// # Examples + /// + /// ``` + /// # use bitcoin_units::SignedAmount; + /// let amount = SignedAmount::from_btc(-0.01).expect("we know 0.01 is valid"); + /// assert_eq!(amount.to_sat(), -1_000_000); + /// ``` #[cfg(feature = "alloc")] pub fn from_btc(btc: f64) -> Result { SignedAmount::from_float_in(btc, Denomination::Bitcoin) @@ -123,6 +146,15 @@ impl SignedAmount { /// or with [`fmt::Display`]. /// /// If you want to parse only the amount without the denomination, use [`Self::from_str_in`]. + /// + /// # Examples + /// + /// ``` + /// # use bitcoin_units::{amount, SignedAmount}; + /// let amount = SignedAmount::from_str_with_denomination("0.1 BTC")?; + /// assert_eq!(amount, SignedAmount::from_sat(10_000_000)); + /// # Ok::<_, amount::ParseError>(()) + /// ``` pub fn from_str_with_denomination(s: &str) -> Result { let (amt, denom) = split_amount_and_denomination(s)?; SignedAmount::from_str_in(amt, denom).map_err(Into::into) @@ -131,6 +163,14 @@ impl SignedAmount { /// Expresses this [`SignedAmount`] as a floating-point value in the given [`Denomination`]. /// /// 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_float_in(Denomination::Bitcoin), 0.001) + /// ``` #[cfg(feature = "alloc")] pub fn to_float_in(self, denom: Denomination) -> f64 { self.to_string_in(denom).parse::().unwrap() @@ -170,6 +210,18 @@ impl SignedAmount { /// Constructs a new object that implements [`fmt::Display`] in the given [`Denomination`]. /// /// This function is useful if you do not wish to allocate. See also [`Self::to_string_in`]. + /// + /// # Examples + /// + /// ``` + /// # use bitcoin_units::amount::{SignedAmount, Denomination}; + /// # use std::fmt::Write; + /// let amount = SignedAmount::from_sat(10_000_000); + /// let mut output = String::new(); + /// write!(&mut output, "{}", amount.display_in(Denomination::Bitcoin))?; + /// assert_eq!(output, "0.1"); + /// # Ok::<(), std::fmt::Error>(()) + /// ``` #[must_use] pub fn display_in(self, denomination: Denomination) -> Display { Display { @@ -196,11 +248,27 @@ impl SignedAmount { /// Returns a formatted string representing this [`SignedAmount`] in the given [`Denomination`]. /// /// Returned string does not include the denomination. + /// + /// # Examples + /// + /// ``` + /// # use bitcoin_units::amount::{SignedAmount, Denomination}; + /// let amount = SignedAmount::from_sat(10_000_000); + /// assert_eq!(amount.to_string_in(Denomination::Bitcoin), "0.1") + /// ``` #[cfg(feature = "alloc")] pub fn to_string_in(self, denom: Denomination) -> String { self.display_in(denom).to_string() } /// Returns a formatted string representing this [`SignedAmount`] in the given [`Denomination`], /// suffixed with the abbreviation for the denomination. + /// + /// # Examples + /// + /// ``` + /// # use bitcoin_units::amount::{SignedAmount, Denomination}; + /// let amount = SignedAmount::from_sat(10_000_000); + /// assert_eq!(amount.to_string_with_denomination(Denomination::Bitcoin), "0.1 BTC") + /// ``` #[cfg(feature = "alloc")] pub fn to_string_with_denomination(self, denom: Denomination) -> String { self.display_in(denom).show_denomination().to_string() diff --git a/units/src/amount/unsigned.rs b/units/src/amount/unsigned.rs index bb2a3d3e6..49edb71be 100644 --- a/units/src/amount/unsigned.rs +++ b/units/src/amount/unsigned.rs @@ -81,6 +81,13 @@ impl Amount { pub const fn from_sat(satoshi: u64) -> Amount { Amount(satoshi) } /// Gets the number of satoshis in this [`Amount`]. + /// + /// # Examples + /// + /// ``` + /// # use bitcoin_units::Amount; + /// assert_eq!(Amount::ONE_BTC.to_sat(), 100_000_000); + /// ``` pub const fn to_sat(self) -> u64 { self.0 } /// Converts from a value expressing a decimal number of bitcoin to an [`Amount`]. @@ -90,6 +97,14 @@ impl Amount { /// If the amount is too big, too precise or negative. /// /// Please be aware of the risk of using floating-point numbers. + /// + /// # Examples + /// + /// ``` + /// # use bitcoin_units::Amount; + /// let amount = Amount::from_btc(0.01).expect("we know 0.01 is valid"); + /// assert_eq!(amount.to_sat(), 1_000_000); + /// ``` #[cfg(feature = "alloc")] pub fn from_btc(btc: f64) -> Result { Amount::from_float_in(btc, Denomination::Bitcoin) @@ -219,6 +234,18 @@ impl Amount { /// Constructs a new object that implements [`fmt::Display`] in the given [`Denomination`]. /// /// This function is useful if you do not wish to allocate. See also [`Self::to_string_in`]. + /// + /// # Examples + /// + /// ``` + /// # use bitcoin_units::amount::{Amount, Denomination}; + /// # use std::fmt::Write; + /// let amount = Amount::from_sat(10_000_000); + /// let mut output = String::new(); + /// write!(&mut output, "{}", amount.display_in(Denomination::Bitcoin))?; + /// assert_eq!(output, "0.1"); + /// # Ok::<(), std::fmt::Error>(()) + /// ``` #[must_use] pub fn display_in(self, denomination: Denomination) -> Display { Display {