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.

#[must_use] fn lt(&self, other: &Rhs) -> bool

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

#[must_use] fn le(&self, other: &Rhs) -> bool

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

#[must_use] fn gt(&self, other: &Rhs) -> bool

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

#[must_use] fn ge(&self, other: &Rhs) -> 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 ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Eq for Amount

impl Copy for Amount

impl Debug for Amount

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

Formats the value using the given formatter.

impl Display 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 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.

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