pub struct Amount(/* private fields */);Expand description
An amount.
The Amount 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.
Warning!
This type implements several arithmetic operations from core::ops.
To prevent errors due to an overflow 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
implements will panic when an overflow occurs.
§Examples
use serde::{Serialize, Deserialize};
use bitcoin_units::Amount;
#[derive(Serialize, Deserialize)]
struct Foo {
// If you are using `rust-bitcoin` then `bitcoin::amount::serde::as_sat` also works.
#[serde(with = "bitcoin_units::amount::serde::as_sat")] // Also `serde::as_btc`.
amount: Amount,
}Implementations§
Source§impl Amount
impl Amount
Sourcepub const fn from_sat(satoshi: u64) -> Result<Self, OutOfRangeError>
pub const fn from_sat(satoshi: u64) -> Result<Self, OutOfRangeError>
Constructs a new Amount from the given number of satoshis.
§Errors
If satoshi is outside of valid range (greater than Self::MAX_MONEY).
§Examples
let amount = Amount::from_sat(sat)?;
assert_eq!(amount.to_sat(), sat);Source§impl Amount
impl Amount
Sourcepub const MAX_MONEY: Self = Self::MAX
pub const MAX_MONEY: Self = Self::MAX
The maximum value allowed as an amount. Useful for sanity checking.
Sourcepub const SIZE: usize = 8
pub const SIZE: usize = 8
The number of bytes that an amount contributes to the size of a transaction.
Sourcepub const fn from_sat_u32(satoshi: u32) -> Self
pub const fn from_sat_u32(satoshi: u32) -> Self
Constructs a new Amount with satoshi precision and the given number of satoshis.
Accepts an u32 which is guaranteed to be in range for the type, but which can only
represent roughly 0 to 42.95 BTC.
Sourcepub fn from_btc(btc: f64) -> Result<Self, ParseAmountError>
pub fn from_btc(btc: f64) -> Result<Self, ParseAmountError>
Sourcepub fn from_int_btc<T: Into<u16>>(whole_bitcoin: T) -> Self
pub fn from_int_btc<T: Into<u16>>(whole_bitcoin: T) -> Self
Converts from a value expressing a whole number of bitcoin to an Amount.
Sourcepub const fn from_btc_u16(whole_bitcoin: u16) -> Self
pub const fn from_btc_u16(whole_bitcoin: u16) -> Self
Converts from a value expressing a whole number of bitcoin to an Amount
in const context.
Sourcepub fn from_str_in(
s: &str,
denom: Denomination,
) -> Result<Self, ParseAmountError>
pub fn from_str_in( s: &str, denom: Denomination, ) -> Result<Self, ParseAmountError>
Parses a decimal string as a value in the given Denomination.
Note: This only parses the value string. If you want to parse a string
containing the value with denomination, use FromStr.
§Errors
If the amount is too precise, negative, or greater than 21,000,000.
Sourcepub fn from_str_with_denomination(s: &str) -> Result<Self, ParseError>
pub fn from_str_with_denomination(s: &str) -> Result<Self, ParseError>
Parses amounts with denomination suffix as produced by Self::to_string_with_denomination
or with fmt::Display.
If you want to parse only the amount without the denomination, use Self::from_str_in.
§Errors
If the amount is too big, too precise or negative.
§Examples
let amount = Amount::from_str_with_denomination("0.1 BTC")?;
assert_eq!(amount, Amount::from_sat(10_000_000)?);Sourcepub fn to_float_in(self, denom: Denomination) -> f64
pub fn to_float_in(self, denom: Denomination) -> f64
Expresses this Amount as a floating-point value in the given Denomination.
Please be aware of the risk of using floating-point numbers.
§Examples
let amount = Amount::from_sat(100_000)?;
assert_eq!(amount.to_float_in(Denomination::Bitcoin), 0.001);Sourcepub fn from_float_in(
value: f64,
denom: Denomination,
) -> Result<Self, ParseAmountError>
pub fn from_float_in( value: f64, denom: Denomination, ) -> Result<Self, ParseAmountError>
Converts this Amount in floating-point notation in the given Denomination.
§Errors
If the amount is too big, too precise or negative.
Please be aware of the risk of using floating-point numbers.
Sourcepub fn display_in(self, denomination: Denomination) -> Display
pub fn display_in(self, denomination: Denomination) -> Display
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
let amount = Amount::from_sat(10_000_000)?;
let mut output = String::new();
let _ = write!(&mut output, "{}", amount.display_in(Denomination::Bitcoin));
assert_eq!(output, "0.1");Sourcepub fn display_dynamic(self) -> Display
pub fn display_dynamic(self) -> Display
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.
Sourcepub fn to_string_in(self, denom: Denomination) -> String
pub fn to_string_in(self, denom: Denomination) -> String
Returns a formatted string representing this Amount in the given Denomination.
Returned string does not include the denomination.
§Examples
let amount = Amount::from_sat(10_000_000)?;
assert_eq!(amount.to_string_in(Denomination::Bitcoin), "0.1");Sourcepub fn to_string_with_denomination(self, denom: Denomination) -> String
pub fn to_string_with_denomination(self, denom: Denomination) -> String
Returns a formatted string representing this Amount in the given Denomination,
suffixed with the abbreviation for the denomination.
§Examples
let amount = Amount::from_sat(10_000_000)?;
assert_eq!(amount.to_string_with_denomination(Denomination::Bitcoin), "0.1 BTC");Sourcepub const fn checked_add(self, rhs: Self) -> Option<Self>
pub const fn checked_add(self, rhs: Self) -> Option<Self>
Checked addition.
Returns None if the sum is larger than Amount::MAX.
Sourcepub const fn checked_sub(self, rhs: Self) -> Option<Self>
pub const fn checked_sub(self, rhs: Self) -> Option<Self>
Checked subtraction.
Returns None if overflow occurred.
Sourcepub const fn checked_mul(self, rhs: u64) -> Option<Self>
pub const fn checked_mul(self, rhs: u64) -> Option<Self>
Checked multiplication.
Returns None if the product is larger than Amount::MAX.
Sourcepub const fn checked_div(self, rhs: u64) -> Option<Self>
pub const fn checked_div(self, rhs: u64) -> Option<Self>
Checked integer division.
Be aware that integer division loses the remainder if no exact division can be made.
Returns None if overflow occurred.
Sourcepub const fn checked_rem(self, rhs: u64) -> Option<Self>
pub const fn checked_rem(self, rhs: u64) -> Option<Self>
Checked remainder.
Returns None if overflow occurred.
Sourcepub fn to_signed(self) -> SignedAmount
pub fn to_signed(self) -> SignedAmount
Converts to a signed amount.
Sourcepub fn signed_sub(self, rhs: Self) -> SignedAmount
pub fn signed_sub(self, rhs: Self) -> SignedAmount
Infallibly subtracts one Amount from another returning a SignedAmount.
Since SignedAmount::MIN is equivalent to -Amount::MAX subtraction of two signed amounts
can never overflow a SignedAmount.
Sourcepub const fn div_by_weight_floor(self, weight: Weight) -> NumOpResult<FeeRate>
pub const fn div_by_weight_floor(self, weight: Weight) -> NumOpResult<FeeRate>
Checked weight floor division.
Be aware that integer division loses the remainder if no exact division
can be made. See also Self::div_by_weight_ceil.
Sourcepub const fn div_by_weight_ceil(self, weight: Weight) -> NumOpResult<FeeRate>
pub const fn div_by_weight_ceil(self, weight: Weight) -> NumOpResult<FeeRate>
Checked weight ceiling 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
sufficient. See also Self::div_by_weight_floor.
§Examples
let amount = Amount::from_sat(10)?;
let weight = Weight::from_wu(300);
let fee_rate = amount.div_by_weight_ceil(weight).expect("valid fee rate");
assert_eq!(fee_rate, FeeRate::from_sat_per_kwu(34));Sourcepub const fn div_by_fee_rate_floor(
self,
fee_rate: FeeRate,
) -> NumOpResult<Weight>
pub const fn div_by_fee_rate_floor( self, fee_rate: FeeRate, ) -> NumOpResult<Weight>
Checked fee rate floor division.
Computes the maximum weight that would result in a fee less than or equal to this amount
at the given fee_rate. Uses floor division to ensure the resulting weight doesn’t cause
the fee to exceed the amount.
Sourcepub const fn div_by_fee_rate_ceil(
self,
fee_rate: FeeRate,
) -> NumOpResult<Weight>
pub const fn div_by_fee_rate_ceil( self, fee_rate: FeeRate, ) -> NumOpResult<Weight>
Checked fee rate ceiling division.
Computes the minimum weight that would result in a fee greater than or equal to this amount
at the given fee_rate. Uses ceiling division to ensure the resulting weight is sufficient.
Trait Implementations§
Source§impl AddAssign<Amount> for NumOpResult<Amount>
impl AddAssign<Amount> for NumOpResult<Amount>
Source§fn add_assign(&mut self, rhs: Amount)
fn add_assign(&mut self, rhs: Amount)
+= operation. Read moreSource§impl<'a> Arbitrary<'a> for Amount
Available on crate feature arbitrary only.
impl<'a> Arbitrary<'a> for Amount
arbitrary only.Source§fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self>
fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self>
Self from the given unstructured data. Read moreSource§fn arbitrary_take_rest(u: Unstructured<'a>) -> Result<Self, Error>
fn arbitrary_take_rest(u: Unstructured<'a>) -> Result<Self, Error>
Self from the entirety of the given
unstructured data. Read moreSource§fn size_hint(depth: usize) -> (usize, Option<usize>)
fn size_hint(depth: usize) -> (usize, Option<usize>)
Unstructured this type
needs to construct itself. Read moreSource§fn try_size_hint(
depth: usize,
) -> Result<(usize, Option<usize>), MaxRecursionReached>
fn try_size_hint( depth: usize, ) -> Result<(usize, Option<usize>), MaxRecursionReached>
Unstructured this type
needs to construct itself. Read moreSource§impl From<Amount> for SignedAmount
impl From<Amount> for SignedAmount
Source§impl Ord for Amount
impl Ord for Amount
Source§impl PartialOrd for Amount
impl PartialOrd for Amount
Source§impl SubAssign<Amount> for NumOpResult<Amount>
impl SubAssign<Amount> for NumOpResult<Amount>
Source§fn sub_assign(&mut self, rhs: Amount)
fn sub_assign(&mut self, rhs: Amount)
-= operation. Read more