Struct steel_cent::SmallMoney

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

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

The range of supported values is small enough to be inappropriate for some practical applications. See max and min below.

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 SmallMoney is 64 bits in size.

assert_eq!(8, std::mem::size_of::<SmallMoney>());

Examples

let price = SmallMoney::of_major_minor(USD, 19, 95);
let shipping_and_handling = SmallMoney::of_major(USD, 10);
let convenience_charge = SmallMoney::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!(SmallMoney::of_minor(USD, 1596), discounted_price);
assert_eq!(SmallMoney::of_minor(USD, 3196), total);
assert_eq!((price * discount) + shipping_and_handling + convenience_charge, total);

Fields

currency: Currency

Methods

impl SmallMoney

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

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

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

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

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

pub fn zero(currency: Currency) -> Self

pub fn min(currency: Currency) -> Self

assert_eq!(SmallMoney::of_major_minor(USD, -21_474_836, -48), SmallMoney::min(USD));

pub fn max(currency: Currency) -> Self

assert_eq!(SmallMoney::of_major_minor(USD, 21_474_836, 47), SmallMoney::max(USD));

pub fn major_part(&self) -> i32

Returns the major unit part of the amount.

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

pub fn minor_part(&self) -> i32

Returns the minor unit part of the amount.

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

pub fn minor_amount(&self) -> i32

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

let two_dollars = SmallMoney::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 = SmallMoney::of_major(USD, 5);
let three_pound_seventy_five = SmallMoney::of_major_minor(GBP, 3, 75);
let gbp_per_usd = 0.75;
let five_eleven_yen = SmallMoney::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 = SmallMoney::of_major(USD, 100);
assert_eq!(Some(c), c.checked_abs());
assert_eq!(Some(c), (-c).checked_abs());
assert_eq!(None, SmallMoney::min(USD).checked_abs());

pub fn abs(&self) -> Self

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

let c = SmallMoney::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(SmallMoney::of_minor(USD, 4_01)),
           SmallMoney::of_major(USD, 4).checked_add(SmallMoney::of_minor(USD, 1)));
assert_eq!(None, SmallMoney::max(USD).checked_add(SmallMoney::of_minor(USD, 1)));

Panics

Panics when currencies differ.

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

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

Panics

Panics when currencies differ.

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

assert_eq!(Some(SmallMoney::of_major(USD, 8)), SmallMoney::of_major(USD, 4).checked_mul(2));
assert_eq!(None, SmallMoney::max(USD).checked_mul(2));
assert_eq!(None, SmallMoney::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(SmallMoney::of_minor(USD, 8_40)), SmallMoney::of_major(USD, 4).checked_mul_f(2.1));
assert_eq!(None, SmallMoney::max(USD).checked_mul_f(1.01));
assert_eq!(None, SmallMoney::min(USD).checked_mul_f(-1.0));

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

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

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

assert_eq!(Some(SmallMoney::of_minor(USD, 1)), SmallMoney::of_minor(USD, 4_01).checked_rem(2));
assert_eq!(None, SmallMoney::of_major(USD, 1).checked_rem(0));
assert_eq!(None, SmallMoney::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(SmallMoney::of_major(USD, -1)), SmallMoney::of_major(USD, 1).checked_neg());
assert_eq!(None, SmallMoney::min(USD).checked_neg());

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

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

Panics

Panics when currencies differ.

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

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

Panics

Panics when currencies differ.

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

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

Trait Implementations

impl FormattableMoney for SmallMoney

fn unformatted_minor_amount(&self) -> String

fn currency(&self) -> Currency

impl ParseableMoney for SmallMoney

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

impl PartialOrd<SmallMoney> for SmallMoney

Compares to SmallMoney 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: &SmallMoney) -> 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<SmallMoney> for SmallMoney

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

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

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

This method tests for !=.

impl Copy for SmallMoney

impl Eq for SmallMoney

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 Clone for SmallMoney

fn clone(&self) -> SmallMoney

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Add<SmallMoney> for SmallMoney

type Output = SmallMoney

The resulting type after applying the + operator.

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

Adds two SmallMoneys.

Examples

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

Panics

Panics when currencies differ.

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

Panics when addition of minor amounts would overflow.

SmallMoney::of_minor(USD, std::i32::MAX) + SmallMoney::of_minor(USD, 1); // panics!

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

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

The resulting type after applying the + operator.

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

Performs the + operation.

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

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

The resulting type after applying the + operator.

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

Performs the + operation.

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

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

The resulting type after applying the + operator.

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

Performs the + operation.

impl Sub<SmallMoney> for SmallMoney

type Output = SmallMoney

The resulting type after applying the - operator.

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

Subtracts one SmallMoney from another.

Examples

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

Panics

Panics when currencies differ.

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

Panics when subtraction of minor amounts would overflow.

SmallMoney::of_minor(USD, std::i32::MIN) - SmallMoney::of_minor(USD, 1); // panics!

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

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

The resulting type after applying the - operator.

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

Performs the - operation.

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

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

The resulting type after applying the - operator.

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

Performs the - operation.

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

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

The resulting type after applying the - operator.

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

Performs the - operation.

impl Mul<i32> for SmallMoney

type Output = SmallMoney

The resulting type after applying the * operator.

fn mul(self, n: i32) -> SmallMoney

Multiplies money by an integer.

Examples

let two_usd = SmallMoney::of_major(USD, 2);
let four_usd = SmallMoney::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.

SmallMoney::of_minor(USD, std::i32::MAX) * 2; // panics!

impl<'a> Mul<i32> for &'a SmallMoney

type Output = <SmallMoney as Mul<i32>>::Output

The resulting type after applying the * operator.

fn mul(self, other: i32) -> <SmallMoney as Mul<i32>>::Output

Performs the * operation.

impl<'a> Mul<&'a i32> for SmallMoney

type Output = <SmallMoney as Mul<i32>>::Output

The resulting type after applying the * operator.

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

Performs the * operation.

impl<'a, 'b> Mul<&'a i32> for &'b SmallMoney

type Output = <SmallMoney as Mul<i32>>::Output

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<f64> for SmallMoney

type Output = SmallMoney

The resulting type after applying the * operator.

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

Multiplies money by a float, rounding if needed.

Examples

let one = SmallMoney::of_major(USD, 1);
let one01 = SmallMoney::of_minor(USD, 1_01);
assert_eq!(one01, one * 1.005001);
assert_eq!(SmallMoney::of_minor(USD, 1_005_00), SmallMoney::of_major(USD, 1_000) * 1.005001);
assert_eq!(SmallMoney::of_minor(USD, 10_050_01), SmallMoney::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.

SmallMoney::of_minor(USD, std::i32::MAX) * 1.01; // panics!

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

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

The resulting type after applying the * operator.

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

Performs the * operation.

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

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

The resulting type after applying the * operator.

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

Performs the * operation.

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

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

The resulting type after applying the * operator.

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

Performs the * operation.

impl Div<i32> for SmallMoney

type Output = SmallMoney

The resulting type after applying the / operator.

fn div(self, n: i32) -> SmallMoney

Divides money by an integer.

Examples

let two_usd = SmallMoney::of_major(USD, 2);
let four01 = SmallMoney::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.

SmallMoney::of_minor(USD, std::i32::MIN) / -1; // panics!

Panics when n is zero.

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

impl<'a> Div<i32> for &'a SmallMoney

type Output = <SmallMoney as Div<i32>>::Output

The resulting type after applying the / operator.

fn div(self, other: i32) -> <SmallMoney as Div<i32>>::Output

Performs the / operation.

impl<'a> Div<&'a i32> for SmallMoney

type Output = <SmallMoney as Div<i32>>::Output

The resulting type after applying the / operator.

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

Performs the / operation.

impl<'a, 'b> Div<&'a i32> for &'b SmallMoney

type Output = <SmallMoney as Div<i32>>::Output

The resulting type after applying the / operator.

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

Performs the / operation.

impl Rem<i32> for SmallMoney

type Output = SmallMoney

The resulting type after applying the % operator.

fn rem(self, n: i32) -> SmallMoney

Remainder of dividing money by an integer.

Examples

let one_cent = SmallMoney::of_minor(USD, 1);
let four01 = SmallMoney::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.

SmallMoney::of_minor(USD, std::i32::MIN) % -1; // panics!

Panics when n is zero.

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

impl<'a> Rem<i32> for &'a SmallMoney

type Output = <SmallMoney as Rem<i32>>::Output

The resulting type after applying the % operator.

fn rem(self, other: i32) -> <SmallMoney as Rem<i32>>::Output

Performs the % operation.

impl<'a> Rem<&'a i32> for SmallMoney

type Output = <SmallMoney as Rem<i32>>::Output

The resulting type after applying the % operator.

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

Performs the % operation.

impl<'a, 'b> Rem<&'a i32> for &'b SmallMoney

type Output = <SmallMoney as Rem<i32>>::Output

The resulting type after applying the % operator.

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

Performs the % operation.

impl Neg for SmallMoney

type Output = SmallMoney

The resulting type after applying the - operator.

fn neg(self) -> SmallMoney

Negation.

Examples

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

Panics

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

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

impl<'a> Neg for &'a SmallMoney

type Output = SmallMoney

The resulting type after applying the - operator.

fn neg(self) -> SmallMoney

Negation of ref.

Examples

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

Panics

Panics when negation would overflow.

-(&SmallMoney::of_minor(USD, std::i32::MIN)); // panics!

impl Debug for SmallMoney

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

Formats the value using the given formatter.

impl Display for SmallMoney

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!("{}", &SmallMoney::of_minor(GBP, 123456)));