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 using the available denominations

Uses a greedy algorithm starting from the largest denomination, taking as many of each denomination as possible before moving to the next smaller one.

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