Fix rustdocs in SignedAmount
This commit is contained in:
parent
9cb302e477
commit
09e184015e
|
@ -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.
|
||||
|
|
|
@ -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")]
|
||||
|
|
Loading…
Reference in New Issue