Struct Amount

Source

pub struct Amount<U = ()> { /* private fields */ }

Expand description

Amount can be any unit

Note: PartialOrd is implemented manually for Amount<CurrencyUnit> to return None when comparing amounts with different units. Ord is only implemented for Amount<()>.

Implementations§

Source §

impl Amount

Source

pub const ZERO: Amount

Amount zero

Source

pub const ONE: Amount

Amount one

Source

pub fn with_unit(self, unit: CurrencyUnit) -> Amount<CurrencyUnit>

Convert an untyped amount to a typed one by adding a unit

This is used at the boundary between protocol and application layers. Protocol types use Amount<()> (no unit), while application types use Amount<CurrencyUnit> (with unit from keyset).

§Example

let untyped = Amount::from(100);
let typed = untyped.with_unit(CurrencyUnit::Sat);
assert_eq!(typed.value(), 100);
assert_eq!(typed.unit(), &CurrencyUnit::Sat);

Source

pub fn split( &self, fee_and_amounts: &FeeAndAmounts, ) -> Result<Vec<Amount>, Error>

Split into parts that are powers of two

Returns an error if the amount cannot be fully represented with the available denominations.

Source

pub fn split_targeted( &self, target: &SplitTarget, fee_and_amounts: &FeeAndAmounts, ) -> Result<Vec<Amount>, Error>

Split into parts that are powers of two by target

Source

pub fn split_with_fee( &self, fee_and_amounts: &FeeAndAmounts, ) -> Result<Vec<Amount>, Error>

Splits amount into powers of two while accounting for the swap fee

Source

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

Checked addition for Amount. Returns None if overflow occurs.

Source

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

Checked subtraction for Amount. Returns None if overflow occurs.

Source

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

Checked multiplication for Amount. Returns None if overflow occurs.

Source

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

Checked division for Amount. Returns None if overflow occurs.

Source

pub fn saturating_sub(self, other: Amount) -> Amount

Subtracts other from self, returning zero if the result would be negative.

Source

pub fn try_sum(iter: I) -> Result<Amount, Error>
where I: IntoIterator<Item = Amount>,

Try sum to check for overflow

Source

pub fn convert_unit( &self, current_unit: &CurrencyUnit, target_unit: &CurrencyUnit, ) -> Result<Amount, Error>

Convert unit

Source

pub fn to_u64(self) -> u64

Convert to u64

Source

pub fn to_i64(self) -> Option<i64>

Convert to i64

Source

pub fn from_i64(value: i64) -> Option<Amount>

Create from i64, returning None if negative

Source §

impl Amount<CurrencyUnit>

Source

pub fn new(value: u64, unit: CurrencyUnit) -> Amount<CurrencyUnit>

Create a new Amount with an explicit unit

This is the primary constructor for typed amounts. It works with all CurrencyUnit variants including Custom.

§Example

let sat_amount = Amount::new(1000, CurrencyUnit::Sat);
let custom = Amount::new(50, CurrencyUnit::Custom("BTC".into()));

Source

pub fn value(&self) -> u64

Get the numeric value

§Example

let amount = Amount::new(1000, CurrencyUnit::Sat);
assert_eq!(amount.value(), 1000);

Source

pub fn to_u64(self) -> u64

Convert to u64

Source

pub fn to_i64(self) -> Option<i64>

Convert to i64

Source

pub fn unit(&self) -> &CurrencyUnit

Get a reference to the unit

§Example

let amount = Amount::new(1000, CurrencyUnit::Sat);
assert_eq!(amount.unit(), &CurrencyUnit::Sat);

Source

pub fn into_parts(self) -> (u64, CurrencyUnit)

Consume self and return both value and unit

§Example

let amount = Amount::new(1000, CurrencyUnit::Sat);
let (value, unit) = amount.into_parts();
assert_eq!(value, 1000);
assert_eq!(unit, CurrencyUnit::Sat);

Source

pub fn checked_add( &self, other: &Amount<CurrencyUnit>, ) -> Result<Amount<CurrencyUnit>, Error>

Checked addition with unit verification

Returns an error if units don’t match or if overflow occurs.

§Example

let a = Amount::new(100, CurrencyUnit::Sat);
let b = Amount::new(50, CurrencyUnit::Sat);
let sum = a.checked_add(&b).unwrap();
assert_eq!(sum.value(), 150);

// Different units cause an error
let c = Amount::new(100, CurrencyUnit::Msat);
assert!(a.checked_add(&c).is_err());

Source

pub fn checked_sub( &self, other: &Amount<CurrencyUnit>, ) -> Result<Amount<CurrencyUnit>, Error>

Checked subtraction with unit verification

Returns an error if units don’t match or if underflow occurs.

§Example

let a = Amount::new(100, CurrencyUnit::Sat);
let b = Amount::new(30, CurrencyUnit::Sat);
let diff = a.checked_sub(&b).unwrap();
assert_eq!(diff.value(), 70);

Source

pub fn convert_to( &self, target_unit: &CurrencyUnit, ) -> Result<Amount<CurrencyUnit>, Error>

Convert to a different unit

§Example

let sat = Amount::new(1000, CurrencyUnit::Sat);
let msat = sat.convert_to(&CurrencyUnit::Msat).unwrap();
assert_eq!(msat.value(), 1_000_000);
assert_eq!(msat.unit(), &CurrencyUnit::Msat);

Source