Struct steel_cent::Money

pub struct Money {
    pub currency: Currency,
    // some fields omitted
}

A signed amount of money in a certain currency, with the currency's standard number of decimal places.

Note that the arithmetic ops implementations all delegate to the checked_ methods, panicking on None, even in a release build. (This is in contrast to primitive ops, which will overflow in a release build.)

A Money is 128 bits in size.

assert_eq!(16, std::mem::size_of::<Money>());

Examples

let price = Money::of_major_minor(USD, 19, 95);
let shipping_and_handling = Money::of_major(USD, 10);
let convenience_charge = Money::of_major(USD, 6);
let discount: f64 = 1.0 - 0.2; // 20% off
let discounted_price = price * discount;
let fees = shipping_and_handling + convenience_charge;
let total = discounted_price + fees;
println!("price: {:?}, discounted_price: {:?}", price, discounted_price);
assert_eq!(Money::of_minor(USD, 1596), discounted_price);
assert_eq!(Money::of_minor(USD, 3196), total);
assert_eq!((price * discount) + shipping_and_handling + convenience_charge, total);

Fields

currency: Currency

Methods

impl Money

pub fn of_minor(currency: Currency, amount_minor: i64) -> Self

Creates a Money from its "minor" unit (e.g. US cents to USD).

pub fn of_major(currency: Currency, amount_major: i64) -> Self

Creates a Money from its "major" unit (e.g. US dollars to USD).

pub fn of_major_minor(
    currency: Currency,
    amount_major: i64,
    amount_minor: i64
) -> Self

pub fn zero(currency: Currency) -> Self

pub fn min(currency: Currency) -> Self

assert_eq!(Money::of_major_minor(USD, -92_233_720_368_547_758, -08), Money::min(USD));

pub fn max(currency: Currency) -> Self

assert_eq!(Money::of_major_minor(USD, 92_233_720_368_547_758, 07), Money::max(USD));

pub fn major_part(&self) -> i64

Returns the major unit part of the amount.

assert_eq!(2, Money::of_minor(USD, 2_99).major_part());

pub fn minor_part(&self) -> i64

Returns the minor unit part of the amount.

assert_eq!(99, Money::of_minor(USD, 2_99).minor_part());

pub fn minor_amount(&self) -> i64

Returns the total amount in the currency's minor unit.

let two_dollars = Money::of_major(USD, 2);
assert_eq!(200, two_dollars.minor_amount());

pub fn convert_to(&self, currency: Currency, conversion_multiplier: f64) -> Self

let five_usd = Money::of_major(USD, 5);
let three_pound_seventy_five = Money::of_major_minor(GBP, 3, 75);
let gbp_per_usd = 0.75;
let five_eleven_yen = Money::of_major(JPY, 511);
let jpy_per_usd = 102.15;
assert_eq!(three_pound_seventy_five, five_usd.convert_to(GBP, gbp_per_usd));
assert_eq!(five_usd, three_pound_seventy_five.convert_to(USD, gbp_per_usd.recip()));
assert_eq!(510.75, 5.0 * jpy_per_usd); // but JPY has zero decimal places.
assert_eq!(five_eleven_yen, five_usd.convert_to(JPY, jpy_per_usd)); // rounded.
assert_eq!(five_usd, five_eleven_yen.convert_to(USD, jpy_per_usd.recip())); // rounded.

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

Returns absolute value, except for the minimum value, which cannot be negated.

let c = Money::of_major(USD, 100);
assert_eq!(Some(c), c.checked_abs());
assert_eq!(Some(c), (-c).checked_abs());
assert_eq!(None, Money::min(USD).checked_abs());

pub fn abs(&self) -> Self

Returns absolute value, except for the minimum value, which cannot be negated.

let c = Money::of_major(USD, 100);
assert_eq!(c, c.abs());
assert_eq!(c, (-c).abs());

Panics

Panics for the minimum value.

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

assert_eq!(Some(Money::of_minor(USD, 4_01)),
           Money::of_major(USD, 4).checked_add(Money::of_minor(USD, 1)));
assert_eq!(None, Money::max(USD).checked_add(Money::of_minor(USD, 1)));

Panics

Panics when currencies differ.

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

assert_eq!(Some(Money::of_minor(USD, 3_99)),
           Money::of_major(USD, 4).checked_sub(Money::of_minor(USD, 1)));
assert_eq!(None, Money::min(USD).checked_sub(Money::of_minor(USD, 1)));

Panics

Panics when currencies differ.

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

assert_eq!(Some(Money::of_major(USD, 8)), Money::of_major(USD, 4).checked_mul(2));
assert_eq!(None, Money::max(USD).checked_mul(2));
assert_eq!(None, Money::min(USD).checked_mul(-1));

pub fn checked_mul_f(self, n: f64) -> Option<Self>

Checked multiplication by a float with rounding. Note that a float has less-than-integer precision for very large and very small amounts of money, which can result in surprising rounding errors.

assert_eq!(Some(Money::of_minor(USD, 8_40)), Money::of_major(USD, 4).checked_mul_f(2.1));
assert_eq!(None, Money::max(USD).checked_mul_f(1.01));
assert_eq!(None, Money::min(USD).checked_mul_f(-1.0));

pub fn checked_div(self, n: i64) -> Option<Self>

assert_eq!(Some(Money::of_major(USD, 2)), Money::of_minor(USD, 4_01).checked_div(2));
assert_eq!(None, Money::of_major(USD, 1).checked_div(0));
assert_eq!(None, Money::min(USD).checked_div(-1));

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

assert_eq!(Some(Money::of_minor(USD, 1)), Money::of_minor(USD, 4_01).checked_rem(2));
assert_eq!(None, Money::of_major(USD, 1).checked_rem(0));
assert_eq!(None, Money::min(USD).checked_rem(-1));

pub fn checked_neg(self) -> Option<Self>

Negates the value, except for the minimum value, which cannot be negated.

assert_eq!(Some(Money::of_major(USD, -1)), Money::of_major(USD, 1).checked_neg());
assert_eq!(None, Money::min(USD).checked_neg());

pub fn saturating_add(self, other: Self) -> Self

assert_eq!(Money::of_minor(USD, 4_01),
           Money::of_major(USD, 4).saturating_add(Money::of_minor(USD, 1)));
assert_eq!(Money::max(USD),
           Money::max(USD).saturating_add(Money::of_minor(USD, 1)));

Panics

Panics when currencies differ.

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

assert_eq!(Money::of_minor(USD, 3_99),
           Money::of_major(USD, 4).saturating_sub(Money::of_minor(USD, 1)));
assert_eq!(Money::min(USD),
           Money::min(USD).saturating_sub(Money::of_minor(USD, 1)));

Panics

Panics when currencies differ.

pub fn saturating_mul(self, n: i64) -> Self

assert_eq!(Money::of_major(USD, 8), Money::of_major(USD, 4).saturating_mul(2));
assert_eq!(Money::max(USD), Money::max(USD).saturating_mul(2));
assert_eq!(Money::max(USD), Money::min(USD).saturating_mul(-1));

Trait Implementations

impl FormattableMoney for Money

fn unformatted_minor_amount(&self) -> String

fn currency(&self) -> Currency

impl ParseableMoney for Money

fn from_unformatted_minor_amount(
    currency: Currency,
    unformatted_minor_amount: &str
) -> Result<Self, ParseIntError>

impl Clone for Money

fn clone(&self) -> Money

Returns a copy of the value.

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

Performs copy-assignment from source.

impl From<SmallMoney> for Money

Converts a SmallMoney to a Money.

assert_eq!(Money::of_major(USD, 2),
           Money::from(SmallMoney::of_major(USD, 2)));

fn from(small: SmallMoney) -> Self

Performs the conversion.

impl Copy for Money

impl Eq for Money

impl PartialOrd<Money> for Money

Compares to Money of the same currency only.

Returns None when currencies differ, causing all comparison operators to return false when currencies differ.

fn partial_cmp(&self, other: &Money) -> 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 PartialEq<Money> for Money

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl Debug for Money

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

Formats the value using the given formatter.

impl Display for Money

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

Displays the value with formatting::STYLE_GENERIC. See the formatting module for other pre-defined and custom styles.

assert_eq!("1,234.56\u{a0}GBP", format!("{}", &Money::of_minor(GBP, 123456)));

impl Add<Money> for Money

type Output = Money

The resulting type after applying the + operator.

fn add(self, other: Money) -> Money

Adds two Moneys.

Examples

let one = Money::of_major(USD, 1);
assert_eq!(Money::of_major(USD, 2), one + one);
// Likewise for refs:
let one = Money::of_major(USD, 1);
assert_eq!(Money::of_major(USD, 2), one + &one);
assert_eq!(Money::of_major(USD, 2), &one + one);
assert_eq!(Money::of_major(USD, 2), &one + &one);

Panics

Panics when currencies differ.

Money::of_major(USD, 1) + Money::of_major(JPY, 1); // panics!

Panics when addition of minor amounts would overflow.

Money::of_minor(USD, std::i64::MAX) + Money::of_minor(USD, 1); // panics!

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

type Output = <Money as Add<Money>>::Output

The resulting type after applying the + operator.

fn add(self, other: Money) -> <Money as Add<Money>>::Output

Performs the + operation.

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

type Output = <Money as Add<Money>>::Output

The resulting type after applying the + operator.

fn add(self, other: &'a Money) -> <Money as Add<Money>>::Output

Performs the + operation.

impl<'a, 'b> Add<&'a Money> for &'b Money

type Output = <Money as Add<Money>>::Output

The resulting type after applying the + operator.

fn add(self, other: &'a Money) -> <Money as Add<Money>>::Output

Performs the + operation.

impl Sub<Money> for Money

type Output = Money

The resulting type after applying the - operator.

fn sub(self, other: Money) -> Money

Subtracts one Money from another.

Examples

let one = Money::of_major(USD, 1);
assert_eq!(Money::of_major(USD, 0), one - one);
// Likewise for refs:
assert_eq!(Money::of_major(USD, 0), one - &one);
assert_eq!(Money::of_major(USD, 0), &one - one);
assert_eq!(Money::of_major(USD, 0), &one - &one);

Panics

Panics when currencies differ.

Money::of_major(USD, 1) - Money::of_major(JPY, 1); // panics!

Panics when subtraction of minor amounts would overflow.

Money::of_minor(USD, std::i64::MIN) - Money::of_minor(USD, 1); // panics!

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

type Output = <Money as Sub<Money>>::Output

The resulting type after applying the - operator.

fn sub(self, other: Money) -> <Money as Sub<Money>>::Output

Performs the - operation.

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

type Output = <Money as Sub<Money>>::Output

The resulting type after applying the - operator.

fn sub(self, other: &'a Money) -> <Money as Sub<Money>>::Output

Performs the - operation.

impl<'a, 'b> Sub<&'a Money> for &'b Money

type Output = <Money as Sub<Money>>::Output

The resulting type after applying the - operator.

fn sub(self, other: &'a Money) -> <Money as Sub<Money>>::Output

Performs the - operation.

impl Mul<i64> for Money

type Output = Money

The resulting type after applying the * operator.

fn mul(self, n: i64) -> Money

Multiplies money by an integer.

Examples

let two_usd = Money::of_major(USD, 2);
let four_usd = Money::of_major(USD, 4);
assert_eq!(four_usd, two_usd * 2);
// Likewise for refs:
assert_eq!(four_usd, two_usd * &2);
assert_eq!(four_usd, &two_usd * 2);
assert_eq!(four_usd, &two_usd * &2);

Panics

Panics when multiplication of minor amount would overflow.

Money::of_minor(USD, std::i64::MAX) * 2; // panics!

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

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

The resulting type after applying the * operator.

fn mul(self, other: i64) -> <Money as Mul<i64>>::Output

Performs the * operation.

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

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

The resulting type after applying the * operator.

fn mul(self, other: &'a i64) -> <Money as Mul<i64>>::Output

Performs the * operation.

impl<'a, 'b> Mul<&'a i64> for &'b Money

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

The resulting type after applying the * operator.

fn mul(self, other: &'a i64) -> <Money as Mul<i64>>::Output

Performs the * operation.

impl Mul<f64> for Money

type Output = Money

The resulting type after applying the * operator.

fn mul(self, n: f64) -> Money

Multiplies money by a float, rounding if needed.

Examples

let one = Money::of_major(USD, 1);
let one01 = Money::of_minor(USD, 1_01);
assert_eq!(one01, one * 1.005001);
assert_eq!(Money::of_minor(USD, 1_005_00), Money::of_major(USD, 1_000) * 1.005001);
assert_eq!(Money::of_minor(USD, 10_050_01), Money::of_major(USD, 10_000) * 1.005001);
// Likewise for refs:
assert_eq!(one01, one * &1.005001);
assert_eq!(one01, &one * 1.005001);
assert_eq!(one01, &one * &1.005001);

Panics

Panics when multiplication of minor amount would overflow.

Money::of_minor(USD, std::i64::MAX) * 1.01; // panics!

impl<'a> Mul<f64> for &'a Money

type Output = <Money as Mul<f64>>::Output

The resulting type after applying the * operator.

fn mul(self, other: f64) -> <Money as Mul<f64>>::Output

Performs the * operation.

impl<'a> Mul<&'a f64> for Money

type Output = <Money as Mul<f64>>::Output

The resulting type after applying the * operator.

fn mul(self, other: &'a f64) -> <Money as Mul<f64>>::Output

Performs the * operation.

impl<'a, 'b> Mul<&'a f64> for &'b Money

type Output = <Money as Mul<f64>>::Output

The resulting type after applying the * operator.

fn mul(self, other: &'a f64) -> <Money as Mul<f64>>::Output

Performs the * operation.

impl Div<i64> for Money

type Output = Money

The resulting type after applying the / operator.

fn div(self, n: i64) -> Money

Divides money by an integer.

Examples

let two_usd = Money::of_major(USD, 2);
let four01 = Money::of_minor(USD, 4_01);
assert_eq!(two_usd, four01 / 2);
// Likewise for refs:
assert_eq!(two_usd, &four01 / 2);
assert_eq!(two_usd, four01 / &2);
assert_eq!(two_usd, &four01 / &2);

Panics

Panics when division of minor amount would overflow.

Money::of_minor(USD, std::i64::MIN) / -1; // panics!

Panics when n is zero.

Money::of_minor(USD, 1) / 0; // panics!

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

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

The resulting type after applying the / operator.

fn div(self, other: i64) -> <Money as Div<i64>>::Output

Performs the / operation.

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

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

The resulting type after applying the / operator.

fn div(self, other: &'a i64) -> <Money as Div<i64>>::Output

Performs the / operation.

impl<'a, 'b> Div<&'a i64> for &'b Money

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

The resulting type after applying the / operator.

fn div(self, other: &'a i64) -> <Money as Div<i64>>::Output

Performs the / operation.

impl Rem<i64> for Money

type Output = Money

The resulting type after applying the % operator.

fn rem(self, n: i64) -> Money

Remainder of dividing money by an integer.

Examples

let one_cent = Money::of_minor(USD, 1);
let four01 = Money::of_minor(USD, 4_01);
assert_eq!(one_cent, four01 % 2);
// Likewise for refs:
assert_eq!(one_cent, &four01 % 2);
assert_eq!(one_cent, four01 % &2);
assert_eq!(one_cent, &four01 % &2);

Panics

Panics when division of minor amount would overflow.

Money::of_minor(USD, std::i64::MIN) % -1; // panics!

Panics when n is zero.

Money::of_minor(USD, 1) % 0; // panics!

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

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

The resulting type after applying the % operator.

fn rem(self, other: i64) -> <Money as Rem<i64>>::Output

Performs the % operation.

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

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

The resulting type after applying the % operator.

fn rem(self, other: &'a i64) -> <Money as Rem<i64>>::Output

Performs the % operation.

impl<'a, 'b> Rem<&'a i64> for &'b Money

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

The resulting type after applying the % operator.

fn rem(self, other: &'a i64) -> <Money as Rem<i64>>::Output

Performs the % operation.

impl Neg for Money

type Output = Money

The resulting type after applying the - operator.

fn neg(self) -> Money

Negation.

Examples

assert_eq!(Money::of_minor(USD, -1), -Money::of_minor(USD, 1));

Panics

Panics when negation would overflow, which is only the case for the minimum value.

-Money::min(USD); // panics!

impl<'a> Neg for &'a Money

type Output = Money

The resulting type after applying the - operator.

fn neg(self) -> Money

Negation of ref.

Examples

assert_eq!(Money::of_minor(USD, -1), -(&Money::of_minor(USD, 1)));

Panics

Panics when negation would overflow.

-(&Money::of_minor(USD, std::i64::MIN)); // panics!