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.

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.

Implementations

impl SignedAmount

pub const ZERO: SignedAmount = _

The zero amount.

pub const ONE_SAT: SignedAmount = _

Exactly one satoshi.

pub const ONE_BTC: SignedAmount = _

Exactly one bitcoin.

pub const MAX_MONEY: SignedAmount = _

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

pub const MIN: SignedAmount = _

The minimum value of an amount.

pub const MAX: SignedAmount = _

The maximum value of an amount.

pub const fn from_sat(satoshi: i64) -> SignedAmount

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

pub fn to_sat(self) -> i64

Gets the number of satoshis in this SignedAmount.

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

Available on crate feature alloc only.

Convert from a value expressing bitcoins to an SignedAmount.

pub fn from_str_in( s: &str, denom: Denomination, ) -> Result<SignedAmount, 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<SignedAmount, 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

Available on crate feature alloc only.

Express this SignedAmount 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

Available on crate feature alloc only.

Express this SignedAmount 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<SignedAmount, ParseAmountError>

Available on crate feature alloc only.

Convert this SignedAmount in floating-point notation with a given denomination.

Errors

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

👎Deprecating in a future version: Use display_in() instead

Format the value of this SignedAmount in the given denomination.

Does not include the denomination.

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

Available on crate feature alloc only.

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

Does not include the denomination.

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

Available on crate feature alloc only.

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

pub fn abs(self) -> SignedAmount

Get the absolute value of this SignedAmount.

pub fn unsigned_abs(self) -> Amount

Get 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 fn checked_abs(self) -> Option<SignedAmount>

Returns the absolute value of this SignedAmount.

Consider using unsigned_abs which is often more practical.

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

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

Checked addition.

Returns None if overflow occurred.

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

Checked subtraction.

Returns None if overflow occurred.

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

Checked multiplication.

Returns None if overflow occurred.

pub fn checked_div(self, rhs: i64) -> Option<SignedAmount>

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: i64) -> Option<SignedAmount>

Checked remainder.

Returns None if overflow occurred.

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

Unchecked addition.

Computes self + rhs.

Panics

On overflow, panics in debug mode, wraps in release mode.

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

Unchecked subtraction.

Computes self - rhs.

Panics

On overflow, panics in debug mode, wraps in release mode.

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

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.

Trait Implementations

impl Add for SignedAmount

type Output = SignedAmount

The resulting type after applying the + operator.

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

Performs the + operation.

impl AddAssign for SignedAmount

fn add_assign(&mut self, other: 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.

impl<T> CheckedSum<SignedAmount> for T

where T: Iterator<Item = SignedAmount>,

fn checked_sum(self) -> Option<SignedAmount>

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

impl Clone for SignedAmount

fn clone(&self) -> SignedAmount

Returns a copy 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 Div<i64> for SignedAmount

type Output = SignedAmount

The resulting type after applying the / operator.

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

Performs the / operation.

impl DivAssign<i64> for SignedAmount

fn div_assign(&mut self, rhs: i64)

Performs the /= operation.

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 string slice is zero or negative zero, then no denomination is required.

Returns

Ok(Amount) if the string amount and denomination parse successfully, otherwise, return Err(ParseError).

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 Mul<i64> for SignedAmount

type Output = SignedAmount

The resulting type after applying the * operator.

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

Performs the * operation.

impl MulAssign<i64> for SignedAmount

fn mul_assign(&mut self, rhs: i64)

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 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 Rem<i64> for SignedAmount

type Output = SignedAmount

The resulting type after applying the % operator.

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

Performs the % operation.

impl RemAssign<i64> for SignedAmount

fn rem_assign(&mut self, modulus: i64)

Performs the %= operation.

impl SerdeAmount for SignedAmount

Available on crate feature serde only.

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

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

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

Available on crate feature alloc only.

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

Available on crate feature alloc only.

impl SerdeAmountForOpt for SignedAmount

Available on crate feature serde only.

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

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

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

Available on crate feature alloc only.

impl Sub for SignedAmount

type Output = SignedAmount

The resulting type after applying the - operator.

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

Performs the - operation.

impl SubAssign for SignedAmount

fn sub_assign(&mut self, other: SignedAmount)

Performs the -= operation.

impl Sum for SignedAmount

fn sum<I: Iterator<Item = Self>>(iter: I) -> Self

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

Performs the conversion.

impl Copy for SignedAmount

impl Eq for SignedAmount

impl StructuralPartialEq for SignedAmount