Struct SignedAmount 

pub struct SignedAmount(/* private fields */);

A signed amount.

The SignedAmount type can be used to express Bitcoin amounts that support arithmetic and 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 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 SignedAmount implements will panic when an overflow occurs.

Examples

use serde::{Serialize, Deserialize};
use bitcoin_units::SignedAmount;

#[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: SignedAmount,
}

Implementations

impl SignedAmount

pub const MAX: Self

The maximum value of an amount.

pub const MIN: Self

The minimum value of an amount.

pub const fn to_sat(self) -> i64

Gets the number of satoshis in this SignedAmount.

Examples

assert_eq!(SignedAmount::ONE_BTC.to_sat(), 100_000_000);

pub const fn from_sat(satoshi: i64) -> Result<Self, OutOfRangeError>

Constructs a new SignedAmount from the given number of satoshis.

Errors

If satoshi is outside of valid range (see Self::MAX_MONEY).

Examples

let amount = SignedAmount::from_sat(sat)?;
assert_eq!(amount.to_sat(), sat);

impl SignedAmount

pub const ZERO: Self

The zero amount.

pub const ONE_SAT: Self

Exactly one satoshi.

pub const ONE_BTC: Self

Exactly one bitcoin.

pub const FIFTY_BTC: Self

Exactly fifty bitcoin.

pub const MAX_MONEY: Self = Self::MAX

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

pub const fn from_sat_i32(satoshi: i32) -> Self

Constructs a new SignedAmount with satoshi precision and the given number of satoshis.

Accepts an i32 which is guaranteed to be in range for the type, but which can only represent roughly -21.47 to 21.47 BTC.

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

Converts from a value expressing a decimal number of bitcoin to a SignedAmount.

Errors

If the amount is too big (positive or negative) or too precise.

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

Examples

let amount = SignedAmount::from_btc(-0.01)?;
assert_eq!(amount.to_sat(), -1_000_000);

pub fn from_int_btc<T: Into<i16>>(whole_bitcoin: T) -> Self

Converts from a value expressing a whole number of bitcoin to a SignedAmount.

pub const fn from_btc_i16(whole_bitcoin: i16) -> Self

Converts from a value expressing a whole number of bitcoin to a SignedAmount in const context.

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 big (positive or negative) or too precise.

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 (positive or negative) or too precise.

Examples

let amount = SignedAmount::from_str_with_denomination("0.1 BTC")?;
assert_eq!(amount, SignedAmount::from_sat(10_000_000)?);

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

Expresses this SignedAmount as a floating-point value in the given Denomination.

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

Examples

let amount = SignedAmount::from_sat(100_000)?;
assert_eq!(amount.to_float_in(Denomination::Bitcoin), 0.001);

pub fn to_btc(self) -> f64

Expresses this SignedAmount as a floating-point value in Bitcoin.

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

Examples

let amount = SignedAmount::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<Self, ParseAmountError>

Converts this SignedAmount in floating-point notation in the given Denomination.

Errors

If the amount is too big (positive or negative) or too precise.

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

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 = SignedAmount::from_sat(10_000_000)?;
let mut output = String::new();
let _ = write!(&mut output, "{}", amount.display_in(Denomination::Bitcoin));
assert_eq!(output, "0.1");

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.

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

Returns a formatted string representing this SignedAmount in the given Denomination.

Returned string does not include the denomination.

Examples

let amount = SignedAmount::from_sat(10_000_000)?;
assert_eq!(amount.to_string_in(Denomination::Bitcoin), "0.1");

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

Returns a formatted string representing this SignedAmount in the given Denomination, suffixed with the abbreviation for the denomination.

Examples

let amount = SignedAmount::from_sat(10_000_000)?;
assert_eq!(amount.to_string_with_denomination(Denomination::Bitcoin), "0.1 BTC");

pub const fn abs(self) -> Self

Gets the absolute value of this SignedAmount.

This function never overflows or panics, unlike i64::abs().

pub fn unsigned_abs(self) -> Amount

Gets the absolute value of this SignedAmount returning Amount.

pub fn signum(self) -> i64

Returns a number representing sign of this SignedAmount.

• 0 if the amount is zero
• 1 if the amount is positive
• -1 if the amount is negative

pub fn is_positive(self) -> bool

Checks if this SignedAmount is positive.

Returns true if this SignedAmount is positive and false if this SignedAmount is zero or negative.

pub fn is_negative(self) -> bool

Checks if this SignedAmount is negative.

Returns true if this SignedAmount is negative and false if this SignedAmount is zero or positive.

pub const fn checked_abs(self) -> Option<Self>

👎Deprecated since 1.0.0-rc.0: Never returns none, use abs() instead

Returns the absolute value of this SignedAmount.

Consider using unsigned_abs which is often more practical.

Returns None if overflow occurred. (self == i64::MIN)

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

Checked addition.

Returns None if the sum is above SignedAmount::MAX or below SignedAmount::MIN.

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

Checked subtraction.

Returns None if the difference is above SignedAmount::MAX or below SignedAmount::MIN.

pub const fn checked_mul(self, rhs: i64) -> Option<Self>

Checked multiplication.

Returns None if the product is above SignedAmount::MAX or below SignedAmount::MIN.

pub const fn checked_div(self, rhs: i64) -> 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.

pub const fn checked_rem(self, rhs: i64) -> Option<Self>

Checked remainder.

Returns None if overflow occurred.

pub fn positive_sub(self, rhs: Self) -> Option<Self>

Subtraction that doesn’t allow negative SignedAmounts.

Returns None if either self, rhs or the result is strictly negative.

pub fn to_unsigned(self) -> Result<Amount, OutOfRangeError>

Converts to an unsigned amount.

Errors

If the amount is negative.

Trait Implementations

impl<'a> Add<&'a NumOpResult<SignedAmount>> for &SignedAmount

type Output = <SignedAmount as Add<NumOpResult<SignedAmount>>>::Output

The resulting type after applying the + operator.

fn add(self, rhs: &NumOpResult<SignedAmount>) -> Self::Output

Performs the + operation.

impl Add<&NumOpResult<SignedAmount>> for SignedAmount

type Output = <SignedAmount as Add<NumOpResult<SignedAmount>>>::Output

The resulting type after applying the + operator.

fn add(self, rhs: &NumOpResult<SignedAmount>) -> Self::Output

Performs the + operation.

impl<'a> Add<&'a SignedAmount> for &SignedAmount

type Output = <SignedAmount as Add>::Output

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<&SignedAmount> for SignedAmount

type Output = <SignedAmount as Add>::Output

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<NumOpResult<SignedAmount>> for &SignedAmount

type Output = <SignedAmount as Add<NumOpResult<SignedAmount>>>::Output

The resulting type after applying the + operator.

fn add(self, rhs: NumOpResult<SignedAmount>) -> Self::Output

Performs the + operation.

impl Add<NumOpResult<SignedAmount>> for SignedAmount

type Output = NumOpResult<SignedAmount>

The resulting type after applying the + operator.

fn add(self, rhs: NumOpResult<SignedAmount>) -> Self::Output

Performs the + operation.

impl Add<SignedAmount> for &SignedAmount

type Output = <SignedAmount as Add>::Output

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add for SignedAmount

type Output = NumOpResult<SignedAmount>

The resulting type after applying the + operator.

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

Performs the + operation.

impl AddAssign<SignedAmount> for NumOpResult<SignedAmount>

fn add_assign(&mut self, rhs: SignedAmount)

Performs the += operation.

impl<'a> Arbitrary<'a> for SignedAmount

Available on crate feature arbitrary only.

fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self>

Generate an arbitrary value of Self from the given unstructured data.

fn arbitrary_take_rest(u: Unstructured<'a>) -> Result<Self, Error>

Generate an arbitrary value of Self from the entirety of the given unstructured data.

fn size_hint(depth: usize) -> (usize, Option<usize>)

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

fn try_size_hint( depth: usize, ) -> Result<(usize, Option<usize>), MaxRecursionReached>

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

impl Binary for SignedAmount

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

Formats the value using the given formatter.

impl Clone for SignedAmount

fn clone(&self) -> SignedAmount

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SignedAmount

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

Formats the value using the given formatter.

impl Default for SignedAmount

fn default() -> Self

Returns the “default value” for a type.

impl Display for SignedAmount

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

Formats the value using the given formatter.

impl<'a> Div<&'a NonZero<i64>> for &SignedAmount

type Output = <SignedAmount as Div<NonZero<i64>>>::Output

The resulting type after applying the / operator.

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

Performs the / operation.

impl Div<&NonZero<i64>> for SignedAmount

type Output = <SignedAmount as Div<NonZero<i64>>>::Output

The resulting type after applying the / operator.

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

Performs the / operation.

impl<'a> Div<&'a SignedAmount> for &SignedAmount

type Output = <SignedAmount as Div>::Output

The resulting type after applying the / operator.

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

Performs the / operation.

impl Div<&SignedAmount> for SignedAmount

type Output = <SignedAmount as Div>::Output

The resulting type after applying the / operator.

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

Performs the / operation.

impl<'a> Div<&'a i64> for &SignedAmount

type Output = <SignedAmount as Div<i64>>::Output

The resulting type after applying the / operator.

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

Performs the / operation.

impl Div<&i64> for SignedAmount

type Output = <SignedAmount as Div<i64>>::Output

The resulting type after applying the / operator.

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

Performs the / operation.

impl Div<NonZero<i64>> for &SignedAmount

type Output = <SignedAmount as Div<NonZero<i64>>>::Output

The resulting type after applying the / operator.

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

Performs the / operation.

impl Div<NonZero<i64>> for SignedAmount

type Output = SignedAmount

The resulting type after applying the / operator.

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

Performs the / operation.

impl Div<SignedAmount> for &SignedAmount

type Output = <SignedAmount as Div>::Output

The resulting type after applying the / operator.

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

Performs the / operation.

impl Div<i64> for &SignedAmount

type Output = <SignedAmount as Div<i64>>::Output

The resulting type after applying the / operator.

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

Performs the / operation.

impl Div<i64> for SignedAmount

type Output = NumOpResult<SignedAmount>

The resulting type after applying the / operator.

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

Performs the / operation.

impl Div for SignedAmount

type Output = NumOpResult<i64>

The resulting type after applying the / operator.

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

Performs the / operation.

impl From<&SignedAmount> for NumOpResult<SignedAmount>

fn from(a: &SignedAmount) -> Self

Converts to this type from the input type.

impl From<Amount> for SignedAmount

fn from(value: Amount) -> Self

Converts to this type from the input type.

impl From<SignedAmount> for NumOpResult<SignedAmount>

fn from(a: SignedAmount) -> Self

Converts to this type from the input type.

impl FromStr for SignedAmount

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

Parses a string slice where the slice includes a denomination.

If the returned value would be zero or negative zero, then no denomination is required.

type Err = ParseError

The associated error which can be returned from parsing.

impl Hash for SignedAmount

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, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl LowerHex for SignedAmount

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

Formats the value using the given formatter.

impl<'a> Mul<&'a SignedAmount> for &i64

type Output = <i64 as Mul<SignedAmount>>::Output

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<&SignedAmount> for i64

type Output = <i64 as Mul<SignedAmount>>::Output

The resulting type after applying the * operator.

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

Performs the * operation.

impl<'a> Mul<&'a i64> for &SignedAmount

type Output = <SignedAmount as Mul<i64>>::Output

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<&i64> for SignedAmount

type Output = <SignedAmount as Mul<i64>>::Output

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<SignedAmount> for &i64

type Output = <i64 as Mul<SignedAmount>>::Output

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<SignedAmount> for i64

type Output = NumOpResult<SignedAmount>

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<i64> for &SignedAmount

type Output = <SignedAmount as Mul<i64>>::Output

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<i64> for SignedAmount

type Output = NumOpResult<SignedAmount>

The resulting type after applying the * operator.

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

Performs the * operation.

impl Neg for SignedAmount

type Output = SignedAmount

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl Octal for SignedAmount

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

Formats the value using the given formatter.

impl Ord for SignedAmount

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for SignedAmount

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl PartialOrd for SignedAmount

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl<'a> Rem<&'a i64> for &SignedAmount

type Output = <SignedAmount as Rem<i64>>::Output

The resulting type after applying the % operator.

fn rem(self, rhs: &i64) -> Self::Output

Performs the % operation.

impl Rem<&i64> for SignedAmount

type Output = <SignedAmount as Rem<i64>>::Output

The resulting type after applying the % operator.

fn rem(self, rhs: &i64) -> Self::Output

Performs the % operation.

impl Rem<i64> for &SignedAmount

type Output = <SignedAmount as Rem<i64>>::Output

The resulting type after applying the % operator.

fn rem(self, rhs: i64) -> Self::Output

Performs the % operation.

impl Rem<i64> for SignedAmount

type Output = NumOpResult<SignedAmount>

The resulting type after applying the % operator.

fn rem(self, modulus: i64) -> Self::Output

Performs the % operation.

impl<'a> Sub<&'a NumOpResult<SignedAmount>> for &SignedAmount

type Output = <SignedAmount as Sub<NumOpResult<SignedAmount>>>::Output

The resulting type after applying the - operator.

fn sub(self, rhs: &NumOpResult<SignedAmount>) -> Self::Output

Performs the - operation.

impl Sub<&NumOpResult<SignedAmount>> for SignedAmount

type Output = <SignedAmount as Sub<NumOpResult<SignedAmount>>>::Output

The resulting type after applying the - operator.

fn sub(self, rhs: &NumOpResult<SignedAmount>) -> Self::Output

Performs the - operation.

impl<'a> Sub<&'a SignedAmount> for &SignedAmount

type Output = <SignedAmount as Sub>::Output

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<&SignedAmount> for SignedAmount

type Output = <SignedAmount as Sub>::Output

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<NumOpResult<SignedAmount>> for &SignedAmount

type Output = <SignedAmount as Sub<NumOpResult<SignedAmount>>>::Output

The resulting type after applying the - operator.

fn sub(self, rhs: NumOpResult<SignedAmount>) -> Self::Output

Performs the - operation.

impl Sub<NumOpResult<SignedAmount>> for SignedAmount

type Output = NumOpResult<SignedAmount>

The resulting type after applying the - operator.

fn sub(self, rhs: NumOpResult<SignedAmount>) -> Self::Output

Performs the - operation.

impl Sub<SignedAmount> for &SignedAmount

type Output = <SignedAmount as Sub>::Output

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub for SignedAmount

type Output = NumOpResult<SignedAmount>

The resulting type after applying the - operator.

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

Performs the - operation.

impl SubAssign<SignedAmount> for NumOpResult<SignedAmount>

fn sub_assign(&mut self, rhs: SignedAmount)

Performs the -= operation.

impl TryFrom<SignedAmount> for Amount

type Error = OutOfRangeError

The type returned in the event of a conversion error.

fn try_from(value: SignedAmount) -> Result<Self, Self::Error>

Performs the conversion.

impl UpperHex for SignedAmount

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

Formats the value using the given formatter.

impl Copy for SignedAmount

impl Eq for SignedAmount

impl StructuralPartialEq for SignedAmount