milksad
/
rust-bitcoin-unsafe-fast
14
0
Fork 0
Code Issues Pull Requests Activity

Fix rustdocs in SignedAmount

This commit is contained in:
Jamil Lambert, PhD 2024-12-18 15:54:43 +00:00
parent 9cb302e477
commit 09e184015e
No known key found for this signature in database
GPG Key ID: 54DC29234AB5D2C0
2 changed files with 31 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
units/src/amount/signed.rs
View File

@ -19,15 +19,15 @@ use super::{
/// A signed amount. /// A signed amount.
/// ///
/// The [`SignedAmount`] type can be used to express Bitcoin amounts that support arithmetic and /// The [`SignedAmount`] type can be used to express Bitcoin amounts that support arithmetic and
/// conversion to various denominations. The `Amount` type does not implement `serde` traits but we /// conversion to various denominations. The [`SignedAmount`] type does not implement [`serde`]
/// do provide modules for serializing as satoshis or bitcoin. /// traits but we do provide modules for serializing as satoshis or bitcoin.
/// ///
/// Warning! /// Warning!
/// ///
/// This type implements several arithmetic operations from [`core::ops`]. /// 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 overflow or underflow when using these operations,
/// it is advised to instead use the checked arithmetic methods whose names /// it is advised to instead use the checked arithmetic methods whose names
/// start with `checked_`. The operations from [`core::ops`] that [`Amount`] /// start with `checked_`. The operations from [`core::ops`] that [`SignedAmount`]
/// implements will panic when overflow or underflow occurs. /// implements will panic when overflow or underflow occurs.
/// ///
/// # Examples /// # Examples
@ -68,7 +68,7 @@ impl SignedAmount {
/// Gets the number of satoshis in this [`SignedAmount`]. /// Gets the number of satoshis in this [`SignedAmount`].
pub const fn to_sat(self) -> i64 { self.0 } pub const fn to_sat(self) -> i64 { self.0 }
/// Converts from a value expressing a whole number of bitcoin to a [`SignedAmount`]. /// Converts from a value expressing a decimal number of bitcoin to a [`SignedAmount`].
#[cfg(feature = "alloc")] #[cfg(feature = "alloc")]
pub fn from_btc(btc: f64) -> Result<SignedAmount, ParseAmountError> { pub fn from_btc(btc: f64) -> Result<SignedAmount, ParseAmountError> {
SignedAmount::from_float_in(btc, Denomination::Bitcoin) SignedAmount::from_float_in(btc, Denomination::Bitcoin)
@ -101,10 +101,10 @@ impl SignedAmount {
} }
} }
/// Parses a decimal string as a value in the given denomination. /// 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 /// Note: This only parses the value string. If you want to parse a string
/// with denomination, use [`FromStr`]. /// containing the value with denomination, use [`FromStr`].
pub fn from_str_in(s: &str, denom: Denomination) -> Result<SignedAmount, ParseAmountError> { pub fn from_str_in(s: &str, denom: Denomination) -> Result<SignedAmount, ParseAmountError> {
match parse_signed_to_satoshi(s, denom).map_err(|error| error.convert(true))? { match parse_signed_to_satoshi(s, denom).map_err(|error| error.convert(true))? {
// (negative, amount) // (negative, amount)
@ -128,7 +128,7 @@ impl SignedAmount {
SignedAmount::from_str_in(amt, denom).map_err(Into::into) SignedAmount::from_str_in(amt, denom).map_err(Into::into)
} }
/// Express this [`SignedAmount`] as a floating-point value in the given denomination. /// Expresses this [`SignedAmount`] as a floating-point value in the given [`Denomination`].
/// ///
/// Please be aware of the risk of using floating-point numbers. /// Please be aware of the risk of using floating-point numbers.
#[cfg(feature = "alloc")] #[cfg(feature = "alloc")]
@ -136,7 +136,7 @@ impl SignedAmount {
self.to_string_in(denom).parse::<f64>().unwrap() self.to_string_in(denom).parse::<f64>().unwrap()
} }
/// Express this [`SignedAmount`] as a floating-point value in Bitcoin. /// Expresses this [`SignedAmount`] as a floating-point value in Bitcoin.
/// ///
/// Please be aware of the risk of using floating-point numbers. /// Please be aware of the risk of using floating-point numbers.
/// ///
@ -150,8 +150,7 @@ impl SignedAmount {
#[cfg(feature = "alloc")] #[cfg(feature = "alloc")]
pub fn to_btc(self) -> f64 { self.to_float_in(Denomination::Bitcoin) } pub fn to_btc(self) -> f64 { self.to_float_in(Denomination::Bitcoin) }
/// Convert this [`SignedAmount`] in floating-point notation with a given /// Converts this [`SignedAmount`] in floating-point notation in the given [`Denomination`].
/// denomination.
/// ///
/// # Errors /// # Errors
/// ///
@ -168,7 +167,9 @@ impl SignedAmount {
SignedAmount::from_str_in(&value.to_string(), denom) SignedAmount::from_str_in(&value.to_string(), denom)
} }
/// Constructs a new object that implements [`fmt::Display`] using specified denomination. /// 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`].
#[must_use] #[must_use]
pub fn display_in(self, denomination: Denomination) -> Display { pub fn display_in(self, denomination: Denomination) -> Display {
Display { Display {
@ -178,7 +179,8 @@ impl SignedAmount {
} }
} }
/// Constructs a new object that implements [`fmt::Display`] dynamically selecting denomination. /// Constructs a new 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 /// This will use BTC for values greater than or equal to 1 BTC and satoshis otherwise. To
/// avoid confusion the denomination is always shown. /// avoid confusion the denomination is always shown.
@ -191,14 +193,14 @@ impl SignedAmount {
} }
} }
/// Returns a formatted string representing this [`SignedAmount`] in the given denomination. /// Returns a formatted string representing this [`SignedAmount`] in the given [`Denomination`].
/// ///
/// Does not include the denomination. /// Returned string does not include the denomination.
#[cfg(feature = "alloc")] #[cfg(feature = "alloc")]
pub fn to_string_in(self, denom: Denomination) -> String { self.display_in(denom).to_string() } pub fn to_string_in(self, denom: Denomination) -> String { self.display_in(denom).to_string() }
/// Returns a formatted string representing this [`Amount`] in the given denomination, suffixed /// Returns a formatted string representing this [`SignedAmount`] in the given [`Denomination`],
/// with the abbreviation for the denomination. /// suffixed with the abbreviation for the denomination.
#[cfg(feature = "alloc")] #[cfg(feature = "alloc")]
pub fn to_string_with_denomination(self, denom: Denomination) -> String { pub fn to_string_with_denomination(self, denom: Denomination) -> String {
self.display_in(denom).show_denomination().to_string() self.display_in(denom).show_denomination().to_string()
@ -206,7 +208,7 @@ impl SignedAmount {
// Some arithmetic that doesn't fit in [`core::ops`] traits. // Some arithmetic that doesn't fit in [`core::ops`] traits.
/// Get the absolute value of this [`SignedAmount`]. /// Gets the absolute value of this [`SignedAmount`].
#[must_use] #[must_use]
pub fn abs(self) -> SignedAmount { SignedAmount(self.0.abs()) } pub fn abs(self) -> SignedAmount { SignedAmount(self.0.abs()) }
@ -238,7 +240,7 @@ impl SignedAmount {
/// ///
/// Consider using `unsigned_abs` which is often more practical. /// Consider using `unsigned_abs` which is often more practical.
/// ///
/// Returns [`None`] if overflow occurred. (`self == MIN`) /// Returns [`None`] if overflow occurred. (`self == i64::MIN`)
#[must_use] #[must_use]
pub const fn checked_abs(self) -> Option<SignedAmount> { pub const fn checked_abs(self) -> Option<SignedAmount> {
// No `map()` in const context. // No `map()` in const context.
@ -250,7 +252,7 @@ impl SignedAmount {
/// Checked addition. /// Checked addition.
/// ///
/// Returns [`None`] if overflow occurred. /// Returns [`None`] if the sum is above [`SignedAmount::MAX`] or below [`SignedAmount::MIN`].
#[must_use] #[must_use]
pub const fn checked_add(self, rhs: SignedAmount) -> Option<SignedAmount> { pub const fn checked_add(self, rhs: SignedAmount) -> Option<SignedAmount> {
// No `map()` in const context. // No `map()` in const context.
@ -262,7 +264,8 @@ impl SignedAmount {
/// Checked subtraction. /// Checked subtraction.
/// ///
/// Returns [`None`] if overflow occurred. /// Returns [`None`] if the difference is above [`SignedAmount::MAX`] or below
/// [`SignedAmount::MIN`].
#[must_use] #[must_use]
pub const fn checked_sub(self, rhs: SignedAmount) -> Option<SignedAmount> { pub const fn checked_sub(self, rhs: SignedAmount) -> Option<SignedAmount> {
// No `map()` in const context. // No `map()` in const context.
@ -274,7 +277,8 @@ impl SignedAmount {
/// Checked multiplication. /// Checked multiplication.
/// ///
/// Returns [`None`] if overflow occurred. /// Returns [`None`] if the product is above [`SignedAmount::MAX`] or below
/// [`SignedAmount::MIN`].
#[must_use] #[must_use]
pub const fn checked_mul(self, rhs: i64) -> Option<SignedAmount> { pub const fn checked_mul(self, rhs: i64) -> Option<SignedAmount> {
// No `map()` in const context. // No `map()` in const context.

9
units/src/amount/unsigned.rs
View File

@ -199,8 +199,7 @@ impl Amount {
#[cfg(feature = "alloc")] #[cfg(feature = "alloc")]
pub fn to_btc(self) -> f64 { self.to_float_in(Denomination::Bitcoin) } pub fn to_btc(self) -> f64 { self.to_float_in(Denomination::Bitcoin) }
/// Converts this [`Amount`] in floating-point notation in the given /// Converts this [`Amount`] in floating-point notation in the given [`Denomination`].
/// [`Denomination`].
/// ///
/// # Errors /// # Errors
/// ///
@ -218,6 +217,8 @@ impl Amount {
} }
/// Constructs a new object that implements [`fmt::Display`] in the given [`Denomination`]. /// 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`].
#[must_use] #[must_use]
pub fn display_in(self, denomination: Denomination) -> Display { pub fn display_in(self, denomination: Denomination) -> Display {
Display { Display {
@ -326,7 +327,7 @@ impl Amount {
/// ///
/// 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. This method rounds up ensuring the transaction fee-rate is /// can be made. This method rounds up ensuring the transaction fee-rate is
/// sufficient. See also [`Amount::checked_div_by_weight_floor`]. /// sufficient. See also [`Self::checked_div_by_weight_floor`].
/// ///
/// Returns [`None`] if overflow occurred. /// Returns [`None`] if overflow occurred.
/// ///
@ -359,7 +360,7 @@ impl Amount {
/// Checked weight floor division. /// Checked weight floor 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. See also [`Amount::checked_div_by_weight_ceil`]. /// can be made. See also [`Self::checked_div_by_weight_ceil`].
/// ///
/// Returns [`None`] if overflow occurred. /// Returns [`None`] if overflow occurred.
#[cfg(feature = "alloc")] #[cfg(feature = "alloc")]