Struct bitcoin::util::amount::Amount

pub struct Amount(_);

Amount

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

Warning!

This type implements several arithmetic operations from [std::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 [std::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.

Methods

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 fn from_sat(satoshi: u64) -> Amount

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

pub fn as_sat(self) -> u64

Get the number of satoshis in this [Amount].

pub fn max_value() -> Amount

The maximum value of an [Amount].

pub fn min_value() -> Amount

The minimum value of an [Amount].

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

Convert from a value expressing bitcoins to an [Amount].

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, ParseAmountError>

Parses amounts with denomination suffix like they are produced with [to_string_with_denomination] or with [fmt::Display]. If you want to parse only the amount without the denomination, use [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 as_btc(self) -> f64

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

Equivalent to to_float_in(Denomination::Bitcoin).

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

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 fmt_value_in(self, f: &mut dyn Write, denom: Denomination) -> Result

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 to_signed(self) -> Result<SignedAmount, ParseAmountError>

Convert to a signed amount.

Trait Implementations

impl Ord for Amount

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

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl PartialOrd<Amount> for Amount

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

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl Default for Amount

fn default() -> Self

Returns the "default value" for a type.

impl Clone for Amount

fn clone(&self) -> Amount

Returns a copy of the value.

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

Performs copy-assignment from source.

impl PartialEq<Amount> for Amount

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

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

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

This method tests for !=.

impl Eq for Amount

impl Copy for Amount

impl Display for Amount

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Debug for Amount

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Rem<u64> for Amount

type Output = Amount

The resulting type after applying the % operator.

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

Performs the % operation.

impl Sub<Amount> for Amount

type Output = Amount

The resulting type after applying the - operator.

fn sub(self, rhs: Amount) -> Self::Output

Performs the - operation.

impl Add<Amount> for Amount

type Output = Amount

The resulting type after applying the + operator.

fn add(self, rhs: Amount) -> Self::Output

Performs the + operation.

impl Mul<u64> for Amount

type Output = Amount

The resulting type after applying the * operator.

fn mul(self, rhs: u64) -> Self::Output

Performs the * operation.

impl Div<u64> for Amount

type Output = Amount

The resulting type after applying the / operator.

fn div(self, rhs: u64) -> Self::Output

Performs the / operation.

impl AddAssign<Amount> for Amount

fn add_assign(&mut self, other: Amount)

Performs the += operation.

impl SubAssign<Amount> for Amount

fn sub_assign(&mut self, other: Amount)

Performs the -= operation.

impl MulAssign<u64> for Amount

fn mul_assign(&mut self, rhs: u64)

Performs the *= operation.

impl DivAssign<u64> for Amount

fn div_assign(&mut self, rhs: u64)

Performs the /= operation.

impl RemAssign<u64> for Amount

fn rem_assign(&mut self, modulus: u64)

Performs the %= operation.

impl Hash for Amount

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

Feeds this value into the given [Hasher].

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

Feeds a slice of this type into the given [Hasher].

impl FromStr for Amount

type Err = ParseAmountError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.