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.
///
/// 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
/// do provide modules for serializing as satoshis or bitcoin.
/// conversion to various denominations. The [`SignedAmount`] 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`]
/// start with `checked_`. The operations from [`core::ops`] that [`SignedAmount`]
/// implements will panic when overflow or underflow occurs.
///
/// # Examples
@ -68,7 +68,7 @@ impl SignedAmount {
/// Gets the number of satoshis in this [`SignedAmount`].
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")]
pub fn from_btc(btc: f64) -> Result<SignedAmount, ParseAmountError> {
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
/// with denomination, use [`FromStr`].
/// Note: This only parses the value string. If you want to parse a string
/// containing the value with denomination, use [`FromStr`].
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))? {
// (negative, amount)
@ -128,7 +128,7 @@ impl SignedAmount {
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.
#[cfg(feature = "alloc")]
@ -136,7 +136,7 @@ impl SignedAmount {
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.
///
@ -150,8 +150,7 @@ impl SignedAmount {
#[cfg(feature = "alloc")]
pub fn to_btc(self) -> f64 { self.to_float_in(Denomination::Bitcoin) }
/// Convert this [`SignedAmount`] in floating-point notation with a given
/// denomination.
/// Converts this [`SignedAmount`] in floating-point notation in the given [`Denomination`].
///
/// # Errors
///
@ -168,7 +167,9 @@ impl SignedAmount {
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]
pub fn display_in(self, denomination: Denomination) -> 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
/// 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")]
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
/// with the abbreviation for the denomination.
/// Returns a formatted string representing this [`SignedAmount`] in the given [`Denomination`],
/// suffixed 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()
@ -206,7 +208,7 @@ impl SignedAmount {
// 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]
pub fn abs(self) -> SignedAmount { SignedAmount(self.0.abs()) }
@ -238,7 +240,7 @@ impl SignedAmount {
///
/// 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]
pub const fn checked_abs(self) -> Option<SignedAmount> {
// No `map()` in const context.
@ -250,7 +252,7 @@ impl SignedAmount {
/// Checked addition.
///
/// Returns [`None`] if overflow occurred.
/// Returns [`None`] if the sum is above [`SignedAmount::MAX`] or below [`SignedAmount::MIN`].
#[must_use]
pub const fn checked_add(self, rhs: SignedAmount) -> Option<SignedAmount> {
// No `map()` in const context.
@ -262,7 +264,8 @@ impl SignedAmount {
/// Checked subtraction.
///
/// Returns [`None`] if overflow occurred.
/// Returns [`None`] if the difference is above [`SignedAmount::MAX`] or below
/// [`SignedAmount::MIN`].
#[must_use]
pub const fn checked_sub(self, rhs: SignedAmount) -> Option<SignedAmount> {
// No `map()` in const context.
@ -274,7 +277,8 @@ impl SignedAmount {
/// Checked multiplication.
///
/// Returns [`None`] if overflow occurred.
/// Returns [`None`] if the product is above [`SignedAmount::MAX`] or below
/// [`SignedAmount::MIN`].
#[must_use]
pub const fn checked_mul(self, rhs: i64) -> Option<SignedAmount> {
// No `map()` in const context.

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

@ -199,8 +199,7 @@ impl Amount {
#[cfg(feature = "alloc")]
pub fn to_btc(self) -> f64 { self.to_float_in(Denomination::Bitcoin) }
/// Converts this [`Amount`] in floating-point notation in the given
/// [`Denomination`].
/// Converts this [`Amount`] in floating-point notation in the given [`Denomination`].
///
/// # Errors
///
@ -218,6 +217,8 @@ 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`].
#[must_use]
pub fn display_in(self, denomination: Denomination) -> Display {
Display {
@ -326,7 +327,7 @@ 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. See also [`Amount::checked_div_by_weight_floor`].
/// sufficient. See also [`Self::checked_div_by_weight_floor`].
///
/// Returns [`None`] if overflow occurred.
///
@ -359,7 +360,7 @@ impl Amount {
/// Checked weight floor 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.
#[cfg(feature = "alloc")]