Struct bdk_chain::bitcoin::amount::Amount

pub struct Amount(/* private fields */);
Expand description

Amount

The Amount type can be used to express Bitcoin amounts that support arithmetic and conversion to various denominations.

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 implements will panic when overflow or underflow occurs. Also note that since the internal representation of amounts is unsigned, subtracting below zero is considered an underflow and will cause a panic if you’re not using the checked arithmetic methods.

Implementations§

§

impl Amount

pub const ZERO: Amount = _

The zero amount.

pub const ONE_SAT: Amount = _

Exactly one satoshi.

pub const ONE_BTC: Amount = _

Exactly one bitcoin.

pub const MAX_MONEY: Amount = _

The maximum value allowed as an amount. Useful for sanity checking.

pub const MIN: Amount = Amount::ZERO

The minimum value of an amount.

pub const MAX: Amount = _

The maximum value of an amount.

pub const SIZE: usize = 8usize

The number of bytes that an amount contributes to the size of a transaction.

pub const fn from_sat(satoshi: u64) -> Amount

Create an Amount with satoshi precision and the given number of satoshis.

pub fn to_sat(self) -> u64

Gets the number of satoshis in this Amount.

pub fn from_btc(btc: f64) -> Result<Amount, ParseAmountError>

Convert from a value expressing bitcoins to an Amount.

pub const fn from_int_btc(btc: u64) -> Amount

Convert from a value expressing integer values of bitcoins to an Amount in const context.

§Panics

The function panics if the argument multiplied by the number of sats per bitcoin overflows a u64 type.

pub fn from_str_in( s: &str, denom: Denomination ) -> Result<Amount, ParseAmountError>

Parse 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.

pub fn from_str_with_denomination(s: &str) -> Result<Amount, ParseError>

Parses amounts with denomination suffix like they are produced with 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.

pub fn to_float_in(self, denom: Denomination) -> f64

Express this Amount as a floating-point value in the given denomination.

Please be aware of the risk of using floating-point numbers.

pub fn to_btc(self) -> f64

Express this Amount as a floating-point value in Bitcoin.

Please be aware of the risk of using floating-point numbers.

§Examples
let amount = Amount::from_sat(100_000);
assert_eq!(amount.to_btc(), amount.to_float_in(Denomination::Bitcoin))

pub fn from_float_in( value: f64, denom: Denomination ) -> Result<Amount, ParseAmountError>

Convert this Amount in floating-point notation with a given denomination. Can return error if the amount is too big, too precise or negative.

Please be aware of the risk of using floating-point numbers.

pub fn display_in(self, denomination: Denomination) -> Display

Create an object that implements fmt::Display using specified denomination.

pub fn display_dynamic(self) -> Display

Create an 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.

pub fn fmt_value_in( self, f: &mut dyn Write, denom: Denomination ) -> Result<(), Error>

Format the value of this Amount in the given denomination.

Does not include the denomination.

pub fn to_string_in(self, denom: Denomination) -> String

Get a string number of this Amount in the given denomination.

Does not include the denomination.

pub fn to_string_with_denomination(self, denom: Denomination) -> String

Get a formatted string of this Amount in the given denomination, suffixed with the abbreviation for the denomination.

pub fn checked_add(self, rhs: Amount) -> Option<Amount>

Checked addition.

Returns None if overflow occurred.

pub fn checked_sub(self, rhs: Amount) -> Option<Amount>

Checked subtraction.

Returns None if overflow occurred.

pub fn checked_mul(self, rhs: u64) -> Option<Amount>

Checked multiplication.

Returns None if overflow occurred.

pub fn checked_div(self, rhs: u64) -> Option<Amount>

Checked integer division.

Be aware that integer division loses the remainder if no exact division can be made. Returns None if overflow occurred.

pub fn checked_rem(self, rhs: u64) -> Option<Amount>

Checked remainder.

Returns None if overflow occurred.

pub fn unchecked_add(self, rhs: Amount) -> Amount

Unchecked addition.

Computes self + rhs. Panics in debug mode, wraps in release mode.

pub fn unchecked_sub(self, rhs: Amount) -> Amount

Unchecked subtraction.

Computes self - rhs. Panics in debug mode, wraps in release mode.

pub fn to_signed(self) -> Result<SignedAmount, OutOfRangeError>

Convert to a signed amount.

Trait Implementations§

§

impl Add for Amount

§

type Output = Amount

The resulting type after applying the + operator.
§

fn add(self, rhs: Amount) -> <Amount as Add>::Output

Performs the + operation. Read more
§

impl AddAssign for Amount

§

fn add_assign(&mut self, other: Amount)

Performs the += operation. Read more
§

impl Clone for Amount

§

fn clone(&self) -> Amount

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
§

impl Debug for Amount

§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
§

impl Decodable for Amount

§

fn consensus_decode<R>(r: &mut R) -> Result<Amount, Error>
where R: Read + ?Sized,

Decode an object with a well-defined format. Read more
§

fn consensus_decode_from_finite_reader<R>(reader: &mut R) -> Result<Self, Error>
where R: Read + ?Sized,

Decode Self from a size-limited reader. Read more
§

impl Default for Amount

§

fn default() -> Amount

Returns the “default value” for a type. Read more
§

impl<'de> Deserialize<'de> for Amount

§

fn deserialize<__D>( __deserializer: __D ) -> Result<Amount, <__D as Deserializer<'de>>::Error>
where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more
§

impl Display for Amount

§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
§

impl Div<Weight> for Amount

§

type Output = FeeRate

The resulting type after applying the / operator.
§

fn div(self, rhs: Weight) -> <Amount as Div<Weight>>::Output

Performs the / operation. Read more
§

impl Div<u64> for Amount

§

type Output = Amount

The resulting type after applying the / operator.
§

fn div(self, rhs: u64) -> <Amount as Div<u64>>::Output

Performs the / operation. Read more
§

impl DivAssign<u64> for Amount

§

fn div_assign(&mut self, rhs: u64)

Performs the /= operation. Read more
§

impl Encodable for Amount

§

fn consensus_encode<W>(&self, w: &mut W) -> Result<usize, Error>
where W: Write + ?Sized,

Encodes an object with a well-defined format. Read more
§

impl FromStr for Amount

§

type Err = ParseError

The associated error which can be returned from parsing.
§

fn from_str(s: &str) -> Result<Amount, <Amount as FromStr>::Err>

Parses a string s to return a value of this type. Read more
§

impl Hash for Amount

§

fn hash<__H>(&self, state: &mut __H)
where __H: Hasher,

Feeds this value into the given Hasher. Read more
1.3.0 · source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
§

impl Mul<u64> for Amount

§

type Output = Amount

The resulting type after applying the * operator.
§

fn mul(self, rhs: u64) -> <Amount as Mul<u64>>::Output

Performs the * operation. Read more
§

impl MulAssign<u64> for Amount

§

fn mul_assign(&mut self, rhs: u64)

Performs the *= operation. Read more
§

impl Ord for Amount

§

fn cmp(&self, other: &Amount) -> Ordering

This method returns an Ordering between self and other. Read more
1.21.0 · source§

fn max(self, other: Self) -> Self
where Self: Sized,

Compares and returns the maximum of two values. Read more
1.21.0 · source§

fn min(self, other: Self) -> Self
where Self: Sized,

Compares and returns the minimum of two values. Read more
1.50.0 · source§

fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized + PartialOrd,

Restrict a value to a certain interval. Read more
§

impl PartialEq for Amount

§

fn eq(&self, other: &Amount) -> bool

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
§

impl PartialOrd for Amount

§

fn partial_cmp(&self, other: &Amount) -> Option<Ordering>

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · source§

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · source§

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more
§

impl Rem<u64> for Amount

§

type Output = Amount

The resulting type after applying the % operator.
§

fn rem(self, modulus: u64) -> Amount

Performs the % operation. Read more
§

impl RemAssign<u64> for Amount

§

fn rem_assign(&mut self, modulus: u64)

Performs the %= operation. Read more
§

impl SerdeAmount for Amount

§

fn ser_sat<S>( self, s: S, _: Token ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>
where S: Serializer,

§

fn des_sat<'d, D>( d: D, _: Token ) -> Result<Amount, <D as Deserializer<'d>>::Error>
where D: Deserializer<'d>,

§

fn ser_btc<S>( self, s: S, _: Token ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>
where S: Serializer,

§

fn des_btc<'d, D>( d: D, _: Token ) -> Result<Amount, <D as Deserializer<'d>>::Error>
where D: Deserializer<'d>,

§

impl SerdeAmountForOpt for Amount

§

fn type_prefix(_: Token) -> &'static str

§

fn ser_sat_opt<S>( self, s: S, _: Token ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>
where S: Serializer,

§

fn ser_btc_opt<S>( self, s: S, _: Token ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>
where S: Serializer,

§

impl Serialize for Amount

§

fn serialize<__S>( &self, __serializer: __S ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>
where __S: Serializer,

Serialize this value into the given Serde serializer. Read more
§

impl Sub for Amount

§

type Output = Amount

The resulting type after applying the - operator.
§

fn sub(self, rhs: Amount) -> <Amount as Sub>::Output

Performs the - operation. Read more
§

impl SubAssign for Amount

§

fn sub_assign(&mut self, other: Amount)

Performs the -= operation. Read more
§

impl Sum for Amount

§

fn sum<I>(iter: I) -> Amount
where I: Iterator<Item = Amount>,

Method which takes an iterator and generates Self from the elements by “summing up” the items.
§

impl TryFrom<Amount> for SignedAmount

§

type Error = OutOfRangeError

The type returned in the event of a conversion error.
§

fn try_from( value: Amount ) -> Result<SignedAmount, <SignedAmount as TryFrom<Amount>>::Error>

Performs the conversion.
§

impl TryFrom<SignedAmount> for Amount

§

type Error = OutOfRangeError

The type returned in the event of a conversion error.
§

fn try_from( value: SignedAmount ) -> Result<Amount, <Amount as TryFrom<SignedAmount>>::Error>

Performs the conversion.
§

impl Copy for Amount

§

impl Eq for Amount

§

impl StructuralPartialEq for Amount

Auto Trait Implementations§

§

impl Freeze for Amount

§

impl RefUnwindSafe for Amount

§

impl Send for Amount

§

impl Sync for Amount

§

impl Unpin for Amount

§

impl UnwindSafe for Amount

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> CheckedSum<Amount> for T
where T: Iterator<Item = Amount>,

§

fn checked_sum(self) -> Option<Amount>

Calculate the sum over the iterator using checked arithmetic. If an over or underflow would happen it returns None.
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for T
where T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,