lucre 0.6.0

#![doc = include_str!("../README.md")]

use std::{cmp::Ordering, fmt::Display, num::NonZeroU32};

pub use rust_decimal::Decimal;
use thiserror::Error;
pub use vec1::{Vec1, vec1};

mod format;
mod parse;

pub use format::Format;
pub use parse::{ParseMoneyError, Parser};

/// An amount of a currency.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct Money {
    amount: Decimal,
    currency: Currency,
}

impl Money {
    /// Create a Money object with an amount of a currency's major (non-fractional) units.
    pub fn from_major(major: i64, currency: &Currency) -> Self {
        let amount = Decimal::new(major, 0);
        Self {
            currency: *currency,
            amount,
        }
    }

    /// Create a Money object with an amount of a currency's minor (fractional) units.
    pub fn from_minor(minor: i64, currency: &Currency) -> Self {
        let amount = Decimal::new(minor, currency.minor_digits);
        Self {
            currency: *currency,
            amount,
        }
    }

    /// Create a Money object directly from a decimal amount.
    ///
    /// ## Example
    ///
    /// ```
    /// use lucre::{Currency, Money};
    ///
    /// // The amount is used verbatim — nothing is rounded or scaled to the
    /// // currency's minor digits.
    /// let money = Money::from_decimal("1.005".parse().unwrap(), &Currency::USD);
    ///
    /// assert_eq!(money.amount().to_string(), "1.005");
    /// ```
    pub fn from_decimal(amount: Decimal, currency: &Currency) -> Self {
        Self {
            currency: *currency,
            amount,
        }
    }

    /// The monetary value, in major units.
    pub fn amount(&self) -> Decimal {
        self.amount
    }

    /// The ISO currency this value is denominated in.
    pub fn currency(&self) -> Currency {
        self.currency
    }

    /// Whether the amount is exactly zero.
    pub fn is_amount_zero(&self) -> bool {
        self.amount.is_zero()
    }

    /// Whether the amount is strictly greater than zero.
    pub fn is_amount_positive(&self) -> bool {
        self.amount > Decimal::ZERO
    }

    /// Whether the amount is strictly less than zero.
    pub fn is_amount_negative(&self) -> bool {
        self.amount < Decimal::ZERO
    }

    /// The sum of two amounts denominated in the same currency — the fallible
    /// counterpart of `+`.
    ///
    /// ## Errors
    ///
    /// Returns `MoneyError::CurrencyMismatch` if the Money values have different currencies.
    /// Returns `MoneyError::Overflow` if the result falls outside the range a `Decimal` can hold.
    pub fn checked_add(&self, other: &Money) -> Result<Self, MoneyError> {
        Self::check_currency_match(self, other)?;

        Ok(Self {
            amount: self
                .amount
                .checked_add(other.amount)
                .ok_or(MoneyError::Overflow)?,
            currency: self.currency,
        })
    }

    /// The difference between two amounts denominated in the same currency —
    /// the fallible counterpart of `-`.
    ///
    /// ## Errors
    ///
    /// Returns `MoneyError::CurrencyMismatch` if the Money values have different currencies.
    /// Returns `MoneyError::Overflow` if the result falls outside the range a `Decimal` can hold.
    pub fn checked_sub(&self, other: &Money) -> Result<Self, MoneyError> {
        Self::check_currency_match(self, other)?;

        Ok(Self {
            amount: self
                .amount
                .checked_sub(other.amount)
                .ok_or(MoneyError::Overflow)?,
            currency: self.currency,
        })
    }

    /// The amount scaled by an arbitrary factor — the fallible counterpart
    /// of `*`.
    ///
    /// ## Errors
    ///
    /// Returns `MoneyError::Overflow` if the result falls outside the range a `Decimal` can hold.
    pub fn checked_mul<N: Into<Decimal>>(&self, other: N) -> Result<Self, MoneyError> {
        Ok(Self {
            amount: self
                .amount
                .checked_mul(other.into())
                .ok_or(MoneyError::Overflow)?,
            currency: self.currency,
        })
    }

    /// The amount split evenly across a divisor — the fallible counterpart
    /// of `/`.
    ///
    /// ## Example
    ///
    /// ```
    /// use lucre::{Currency, Money, RoundingMode};
    ///
    /// let bill = Money::from_major(10, &Currency::USD);
    ///
    /// // The quotient keeps `Decimal`'s full precision, so it may carry
    /// // more fractional digits than the currency has; apply `Money::round`
    /// // when a spendable amount is needed.
    /// let third = bill.checked_div(3).unwrap();
    ///
    /// assert_eq!(third.round(2, RoundingMode::HalfUp).to_string(), "3.33 USD");
    /// ```
    ///
    /// ## Errors
    ///
    /// Returns `MoneyError::DivisionByZero` if the `other` is zero.
    /// Returns `MoneyError::Overflow` if the result falls outside the range a `Decimal` can hold.
    pub fn checked_div<N: Into<Decimal>>(&self, other: N) -> Result<Self, MoneyError> {
        let other_dec: Decimal = other.into();

        if other_dec.is_zero() {
            return Err(MoneyError::DivisionByZero);
        }

        Ok(Self {
            amount: self
                .amount
                .checked_div(other_dec)
                .ok_or(MoneyError::Overflow)?,
            currency: self.currency,
        })
    }

    /// Returns a new `Money` rounded to the specified number of digits in the fractional portion,
    /// using the given strategy.
    pub fn round(&self, digits: u32, strategy: RoundingMode) -> Self {
        let dec_strategy = match strategy {
            RoundingMode::HalfUp => rust_decimal::RoundingStrategy::MidpointAwayFromZero,
            RoundingMode::HalfDown => rust_decimal::RoundingStrategy::MidpointTowardZero,
            RoundingMode::HalfEven => rust_decimal::RoundingStrategy::MidpointNearestEven,
        };

        let amount = self.amount.round_dp_with_strategy(digits, dec_strategy);

        Self {
            amount,
            currency: self.currency,
        }
    }

    /// Divide the amount into `n` parts that sum back to exactly `self`.
    ///
    /// Parts differ by at most one smallest unit — the finer of the amount's
    /// scale and the currency's minor digits. Negative amounts divide
    /// symmetrically.
    ///
    /// ## Example
    ///
    /// ```
    /// use std::num::NonZeroU32;
    /// use lucre::{Currency, Money};
    ///
    /// let three = NonZeroU32::new(3).unwrap();
    /// let parts = Money::from_major(10, &Currency::USD).split(three);
    ///
    /// // Earlier parts take the extra units.
    /// assert_eq!(
    ///     *parts,
    ///     [
    ///         Money::from_minor(334, &Currency::USD),
    ///         Money::from_minor(333, &Currency::USD),
    ///         Money::from_minor(333, &Currency::USD),
    ///     ]
    /// );
    /// ```
    pub fn split(&self, n: NonZeroU32) -> Vec1<Money> {
        let count = n.get() as usize;
        self.distribute(u128::from(n.get()), std::iter::repeat_n(1, count))
    }

    /// Divide the amount proportionally to `weights`, producing parts that
    /// sum back to exactly `self`, one per weight.
    ///
    /// Whatever cannot be divided proportionally at the smallest unit — the
    /// finer of the amount's scale and the currency's minor digits — goes one
    /// unit apiece to the earliest parts. Negative amounts divide
    /// symmetrically.
    ///
    /// ## Example
    ///
    /// ```
    /// use std::num::NonZeroU32;
    /// use lucre::{Currency, Money, vec1};
    ///
    /// let three = NonZeroU32::new(3).unwrap();
    /// let seven = NonZeroU32::new(7).unwrap();
    ///
    /// let parts = Money::from_minor(5, &Currency::USD).allocate(&vec1![three, seven]);
    ///
    /// assert_eq!(
    ///     *parts,
    ///     [
    ///         Money::from_minor(2, &Currency::USD),
    ///         Money::from_minor(3, &Currency::USD),
    ///     ]
    /// );
    /// ```
    pub fn allocate(&self, weights: &Vec1<NonZeroU32>) -> Vec1<Money> {
        let sum = weights.iter().map(|w| u128::from(w.get())).sum();
        self.distribute(sum, weights.iter().map(|w| u128::from(w.get())))
    }

    /// Apportion the amount's smallest units across `weights`, giving each
    /// part its proportional floor and handing the leftover units one apiece
    /// to the earliest parts.
    ///
    /// Computing each floor as `whole * w + partial * w / weight_sum` (rather
    /// than `magnitude * w / weight_sum`) keeps every intermediate value no
    /// larger than the original mantissa, so no input can overflow.
    fn distribute(&self, weight_sum: u128, weights: impl Iterator<Item = u128>) -> Vec1<Money> {
        let mut scale = self.amount.scale();
        let mut magnitude = self.amount.mantissa().unsigned_abs();
        let sign = if self.amount.mantissa() < 0 {
            -1i128
        } else {
            1
        };

        // Refine coarse amounts to minor units, stopping short if the
        // mantissa would overflow (only possible within 10^4 of Decimal::MAX).
        let max_magnitude = Decimal::MAX.mantissa().unsigned_abs();
        while scale < self.currency.minor_digits && magnitude <= max_magnitude / 10 {
            magnitude *= 10;
            scale += 1;
        }

        let whole = magnitude / weight_sum;
        let partial = magnitude % weight_sum;

        let mut units: Vec<u128> = weights
            .map(|weight| whole * weight + partial * weight / weight_sum)
            .collect();

        let mut leftover = magnitude - units.iter().sum::<u128>();
        for unit in units.iter_mut() {
            if leftover == 0 {
                break;
            }
            *unit += 1;
            leftover -= 1;
        }

        let parts = units
            .into_iter()
            .map(|unit| Self {
                amount: Decimal::from_i128_with_scale(sign * unit as i128, scale),
                currency: self.currency,
            })
            .collect();

        Vec1::try_from_vec(parts).expect("one part per weight, and weights cannot be empty")
    }

    fn check_currency_match(a: &Money, b: &Money) -> Result<(), MoneyError> {
        if a.currency == b.currency {
            Ok(())
        } else {
            Err(MoneyError::CurrencyMismatch)
        }
    }
}

impl std::ops::Add for Money {
    type Output = Money;

    /// # Panics
    ///
    /// Panics on mismatched currencies or on overflow. Use
    /// [`Money::checked_add`] to handle both conditions as errors.
    fn add(self, rhs: Self) -> Self::Output {
        self.checked_add(&rhs)
            .unwrap_or_else(|e| panic!("addition error: {e}"))
    }
}

impl std::ops::Sub for Money {
    type Output = Money;

    /// # Panics
    ///
    /// Panics on mismatched currencies or on overflow. Use
    /// [`Money::checked_sub`] to handle both conditions as errors.
    fn sub(self, rhs: Self) -> Self::Output {
        self.checked_sub(&rhs)
            .unwrap_or_else(|e| panic!("subtraction error: {e}"))
    }
}

impl<N> std::ops::Mul<N> for Money
where
    N: Into<Decimal>,
{
    type Output = Money;

    /// # Panics
    ///
    /// Panics on overflow. Use [`Money::checked_mul`] to handle it as an
    /// error.
    fn mul(self, rhs: N) -> Self::Output {
        self.checked_mul(rhs)
            .unwrap_or_else(|e| panic!("multiplication error: {e}"))
    }
}

impl<N> std::ops::Div<N> for Money
where
    N: Into<Decimal>,
{
    type Output = Money;

    /// # Panics
    ///
    /// Panics on a zero divisor or on overflow. Use [`Money::checked_div`] to
    /// handle both conditions as errors.
    fn div(self, rhs: N) -> Self::Output {
        self.checked_div(rhs)
            .unwrap_or_else(|e| panic!("division error: {e}"))
    }
}

impl std::cmp::PartialOrd for Money {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        if self.currency != other.currency {
            return None;
        }

        Some(self.amount.cmp(&other.amount))
    }
}

/// The ISO 4217 numeric code for a currency.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
pub struct IsoNumericCode(u32);

impl IsoNumericCode {
    /// The code as its underlying integer.
    pub fn value(&self) -> u32 {
        self.0
    }
}

/// The ISO 4217 alphabetic code for a currency.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
pub struct IsoAlphabeticCode([u8; 3]);

impl IsoAlphabeticCode {
    /// The code as a string slice.
    ///
    /// ## Example
    ///
    /// ```
    /// use lucre::Currency;
    ///
    /// assert_eq!(Currency::USD.alphabetic_code().as_str(), "USD");
    /// ```
    pub fn as_str(&self) -> &str {
        std::str::from_utf8(&self.0).expect("alphabetic codes are ASCII")
    }
}

impl Display for IsoAlphabeticCode {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.as_str())
    }
}

/// An ISO 4217 currency.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
pub struct Currency {
    alphabetic_code: IsoAlphabeticCode,
    numeric_code: IsoNumericCode,
    minor_digits: u32,
    symbol: &'static str,
}

impl Currency {
    /// The three-letter code identifying this currency.
    pub fn alphabetic_code(&self) -> IsoAlphabeticCode {
        self.alphabetic_code
    }

    /// The numeric code identifying this currency.
    pub fn numeric_code(&self) -> IsoNumericCode {
        self.numeric_code
    }

    /// How many fractional digits one whole unit divides into.
    pub fn minor_digits(&self) -> u32 {
        self.minor_digits
    }

    /// The customary sign written next to amounts.
    ///
    /// ## Example
    ///
    /// ```
    /// use lucre::Currency;
    ///
    /// assert_eq!(Currency::USD.symbol(), "$");
    /// assert_eq!(Currency::GBP.symbol(), "£");
    /// ```
    pub fn symbol(&self) -> &'static str {
        self.symbol
    }
}

// The ISO 4217 catalog, generated by build.rs from isodata.tsv.
include!(concat!(env!("OUT_DIR"), "/iso_currencies.rs"));

impl Display for Currency {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.alphabetic_code)
    }
}

/// Strategy for resolving a midpoint value when reducing precision.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum RoundingMode {
    HalfUp,
    HalfDown,
    HalfEven,
}

/// An error that can occur while working with `Money`.
#[derive(Error, Debug)]
pub enum MoneyError {
    #[error("mismatched currencies")]
    CurrencyMismatch,

    #[error("overflow")]
    Overflow,

    #[error("division by zero")]
    DivisionByZero,
}

#[cfg(test)]
mod tests {
    use super::*;
    use rust_decimal::prelude::*;

    #[test]
    fn from_major_minor_decimal_are_equal_test() {
        let from_minor = Money::from_minor(100, &Currency::USD);
        let from_major = Money::from_major(1, &Currency::USD);
        let from_decimal = Money::from_decimal(dec!(1.00), &Currency::USD);

        assert_eq!(from_minor, from_major);
        assert_eq!(from_major, from_decimal);
        assert_eq!(from_minor, from_decimal);
    }

    #[test]
    fn eq_with_different_currencies_are_not_equal() {
        let a = Money::from_major(100, &Currency::USD);
        let b = Money::from_major(100, &Currency::EUR);

        assert_ne!(a, b);
    }

    #[test]
    fn not_equal_with_different_amounts_test() {
        let a = Money::from_major(100, &Currency::USD);
        let b = Money::from_major(200, &Currency::USD);

        assert_ne!(a, b);
    }

    #[test]
    fn add_test() {
        let a = Money::from_minor(100, &Currency::USD);
        let b = Money::from_minor(200, &Currency::USD);

        let expected = Money::from_minor(300, &Currency::USD);

        assert_eq!(a + b, expected);
    }

    #[test]
    fn add_overflow_test() {
        let a = Money::from_decimal(Decimal::MAX, &Currency::USD);
        let b = Money::from_major(1, &Currency::USD);

        assert!(a.checked_add(&b).is_err());
    }

    #[test]
    #[should_panic]
    fn add_operator_overflow_panics_test() {
        let a = Money::from_decimal(Decimal::MAX, &Currency::USD);
        let b = Money::from_major(1, &Currency::USD);

        let _ = a + b;
    }

    #[test]
    fn add_mismatched_currencies_test() {
        let a = Money::from_minor(100, &Currency::USD);
        let b = Money::from_minor(100, &Currency::EUR);

        assert!(a.checked_add(&b).is_err());
    }

    #[test]
    #[should_panic]
    fn add_operator_mismatched_currencies_panics_test() {
        let _ = Money::from_minor(100, &Currency::USD) + Money::from_minor(100, &Currency::EUR);
    }

    #[test]
    fn sub_test() {
        let a = Money::from_minor(200, &Currency::USD);
        let b = Money::from_minor(100, &Currency::USD);

        assert_eq!(a - b, Money::from_minor(100, &Currency::USD));
    }

    #[test]
    fn sub_overflow_test() {
        let a = Money::from_decimal(Decimal::MIN, &Currency::USD);
        let b = Money::from_major(1, &Currency::USD);

        assert!(a.checked_sub(&b).is_err());
    }

    #[test]
    fn sub_mismatched_currencies_test() {
        let a = Money::from_minor(100, &Currency::USD);
        let b = Money::from_minor(100, &Currency::EUR);

        assert!(a.checked_sub(&b).is_err());
    }

    #[test]
    #[should_panic]
    fn sub_operator_mismatched_currencies_panics_test() {
        let _ = Money::from_minor(100, &Currency::USD) - Money::from_minor(100, &Currency::EUR);
    }

    #[test]
    fn mul_test() {
        let a = Money::from_major(100, &Currency::USD);

        assert_eq!(a * 5, Money::from_major(500, &Currency::USD));
    }

    #[test]
    fn mul_overflow_test() {
        let a = Money::from_decimal(Decimal::MAX, &Currency::USD);

        assert!(a.checked_mul(2).is_err());
    }

    #[test]
    fn div_test() {
        let a = Money::from_major(100, &Currency::USD);

        assert_eq!(a / 5, Money::from_major(20, &Currency::USD));
    }

    #[test]
    fn div_overflow_test() {
        let a = Money::from_decimal(Decimal::MAX, &Currency::USD);

        assert!(a.checked_div(dec!(0.5)).is_err());
    }

    #[test]
    fn div_by_zero_test() {
        let a = Money::from_major(100, &Currency::USD);

        assert!(a.checked_div(0).is_err());
    }

    #[test]
    #[should_panic]
    fn div_operator_by_zero_panics_test() {
        let _ = Money::from_major(100, &Currency::USD) / 0;
    }

    #[test]
    fn partial_cmp_test() {
        let one = Money::from_major(1, &Currency::USD);
        let two = Money::from_major(2, &Currency::USD);

        assert_eq!(one.partial_cmp(&two), Some(Ordering::Less));
        assert_eq!(one.partial_cmp(&one), Some(Ordering::Equal));
        assert_eq!(two.partial_cmp(&one), Some(Ordering::Greater));
    }

    #[test]
    fn partial_cmp_mismatched_currencies_test() {
        let a = Money::from_major(1, &Currency::USD);
        let b = Money::from_major(1, &Currency::EUR);

        assert_eq!(a.partial_cmp(&b), None);
    }

    #[test]
    #[allow(clippy::neg_cmp_op_on_partial_ord)]
    fn ordering_operators_test() {
        let one = Money::from_major(1, &Currency::USD);
        let two = Money::from_major(2, &Currency::USD);

        assert!(one < two);
        assert!(one <= two);
        assert!(one <= one);
        assert!(two > one);
        assert!(two >= one);
        assert!(two >= two);
        assert!(!(two < one));
        assert!(!(one > two));
    }

    #[test]
    #[allow(clippy::neg_cmp_op_on_partial_ord)]
    fn ordering_operators_mismatched_currencies_test() {
        let a = Money::from_major(1, &Currency::USD);
        let b = Money::from_major(2, &Currency::EUR);

        assert!(!(a < b));
        assert!(!(a > b));
        assert!(!(a <= b));
        assert!(!(a >= b));
    }

    #[test]
    fn round_half_up_test() {
        let a = Money::from_decimal(dec!(0.125), &Currency::USD);

        assert_eq!(
            a.round(2, RoundingMode::HalfUp),
            Money::from_decimal(dec!(0.13), &Currency::USD)
        );
    }

    #[test]
    fn round_half_down_test() {
        let a = Money::from_decimal(dec!(0.125), &Currency::USD);

        assert_eq!(
            a.round(2, RoundingMode::HalfDown),
            Money::from_decimal(dec!(0.12), &Currency::USD)
        );
    }

    #[test]
    fn round_half_even_test() {
        assert_eq!(
            Money::from_decimal(dec!(0.125), &Currency::USD).round(2, RoundingMode::HalfEven),
            Money::from_decimal(dec!(0.12), &Currency::USD)
        );
        assert_eq!(
            Money::from_decimal(dec!(0.135), &Currency::USD).round(2, RoundingMode::HalfEven),
            Money::from_decimal(dec!(0.14), &Currency::USD)
        );
    }

    #[test]
    #[should_panic]
    fn sub_operator_overflow_panics_test() {
        let a = Money::from_decimal(Decimal::MIN, &Currency::USD);
        let b = Money::from_major(1, &Currency::USD);

        let _ = a - b;
    }

    #[test]
    #[should_panic]
    fn mul_operator_overflow_panics_test() {
        let _ = Money::from_decimal(Decimal::MAX, &Currency::USD) * 2;
    }

    #[test]
    #[should_panic]
    fn div_operator_overflow_panics_test() {
        let _ = Money::from_decimal(Decimal::MAX, &Currency::USD) / dec!(0.5);
    }

    #[test]
    fn arithmetic_with_negative_amounts_test() {
        let credit = Money::from_major(5, &Currency::USD);
        let debit = Money::from_major(-2, &Currency::USD);

        assert_eq!(credit + debit, Money::from_major(3, &Currency::USD));
        assert_eq!(debit - credit, Money::from_major(-7, &Currency::USD));
        assert!(debit < credit);
    }

    #[test]
    fn mul_by_decimal_scalar_test() {
        let a = Money::from_major(5, &Currency::USD);

        assert_eq!(
            a * dec!(0.5),
            Money::from_decimal(dec!(2.5), &Currency::USD)
        );
    }

    #[test]
    fn div_keeps_fractional_result_test() {
        let a = Money::from_major(10, &Currency::USD);

        assert_eq!(a / 4, Money::from_decimal(dec!(2.5), &Currency::USD));
    }

    #[test]
    fn round_negative_midpoint_goes_away_from_zero_test() {
        let a = Money::from_decimal(dec!(-0.125), &Currency::USD);

        assert_eq!(
            a.round(2, RoundingMode::HalfUp),
            Money::from_decimal(dec!(-0.13), &Currency::USD)
        );
    }

    #[test]
    fn round_beyond_scale_is_identity_test() {
        let a = Money::from_decimal(dec!(1.5), &Currency::USD);

        assert_eq!(a.round(2, RoundingMode::HalfUp), a);
    }

    #[test]
    fn money_accessors_test() {
        let a = Money::from_minor(150, &Currency::USD);

        assert_eq!(a.amount(), dec!(1.50));
        assert_eq!(a.currency(), Currency::USD);
    }

    #[test]
    fn currency_accessors_test() {
        let currency = Currency::USD;

        assert_eq!(currency.alphabetic_code().as_str(), "USD");
        assert_eq!(currency.numeric_code().value(), 840);
        assert_eq!(currency.minor_digits(), 2);
        assert_eq!(currency.symbol(), "$");
    }

    #[test]
    fn display_test() {
        assert_eq!(
            Money::from_minor(150, &Currency::USD).to_string(),
            "1.50 USD"
        );
        assert_eq!(
            Money::from_major(-3, &Currency::USD).to_string(),
            "-3.00 USD"
        );
    }

    #[test]
    fn currency_lookup_test() {
        assert_eq!(Currency::from_alphabetic_code("USD"), Some(Currency::USD));
        assert_eq!(Currency::from_alphabetic_code("ZZZ"), None);
        assert_eq!(Currency::from_numeric_code(978), Some(Currency::EUR));
        assert_eq!(Currency::from_numeric_code(1), None);
    }

    #[test]
    fn currency_catalog_test() {
        assert!(Currency::all().contains(&Currency::USD));
        assert!(Currency::all().contains(&Currency::XAU));
        assert_eq!(Currency::BHD.minor_digits(), 3);
        assert_eq!(Currency::XAU.minor_digits(), 0);
    }

    #[test]
    fn is_amount_zero_test() {
        assert!(Money::from_major(0, &Currency::USD).is_amount_zero());
        assert!(!Money::from_major(1, &Currency::USD).is_amount_zero());
        assert!(!Money::from_major(-1, &Currency::USD).is_amount_zero());
    }

    #[test]
    fn is_amount_positive_test() {
        assert!(Money::from_major(1, &Currency::USD).is_amount_positive());
        assert!(!Money::from_major(-1, &Currency::USD).is_amount_positive());
        assert!(!Money::from_major(0, &Currency::USD).is_amount_positive());
    }

    #[test]
    fn is_amount_negative_test() {
        assert!(Money::from_major(-1, &Currency::USD).is_amount_negative());
        assert!(!Money::from_major(1, &Currency::USD).is_amount_negative());
        assert!(!Money::from_major(0, &Currency::USD).is_amount_negative());
    }

    #[test]
    fn negative_zero_is_zero_not_negative_test() {
        let a = Money::from_decimal(dec!(-0.00), &Currency::USD);

        assert!(a.is_amount_zero());
        assert!(!a.is_amount_negative());
        assert!(!a.is_amount_positive());
    }

    #[test]
    fn from_minor_with_three_minor_digits_test() {
        let a = Money::from_minor(1500, &Currency::BHD);

        assert_eq!(a.amount(), dec!(1.500));
    }

    fn n(value: u32) -> NonZeroU32 {
        NonZeroU32::new(value).unwrap()
    }

    fn usd(amount: Decimal) -> Money {
        Money::from_decimal(amount, &Currency::USD)
    }

    #[test]
    fn split_evenly_test() {
        let parts = usd(dec!(9.00)).split(n(3));

        assert_eq!(*parts, vec![usd(dec!(3.00)); 3]);
    }

    #[test]
    fn split_gives_extra_units_to_earlier_parts_test() {
        let parts = usd(dec!(10.00)).split(n(3));

        assert_eq!(
            *parts,
            vec![usd(dec!(3.34)), usd(dec!(3.33)), usd(dec!(3.33))]
        );
    }

    #[test]
    fn split_into_one_part_is_identity_test() {
        let a = usd(dec!(10.01));

        assert_eq!(*a.split(n(1)), vec![a]);
    }

    #[test]
    fn split_negative_is_symmetric_test() {
        let parts = usd(dec!(-10.01)).split(n(2));

        assert_eq!(*parts, vec![usd(dec!(-5.01)), usd(dec!(-5.00))]);
    }

    #[test]
    fn split_zero_amount_test() {
        let parts = usd(dec!(0.00)).split(n(3));

        assert_eq!(*parts, vec![usd(dec!(0.00)); 3]);
    }

    #[test]
    fn split_keeps_sub_minor_precision_test() {
        let parts = usd(dec!(10.005)).split(n(2));

        assert_eq!(*parts, vec![usd(dec!(5.003)), usd(dec!(5.002))]);
    }

    #[test]
    fn split_refines_coarse_amounts_to_minor_units_test() {
        let parts = Money::from_major(10, &Currency::USD).split(n(3));

        assert_eq!(
            *parts,
            vec![usd(dec!(3.34)), usd(dec!(3.33)), usd(dec!(3.33))]
        );
    }

    #[test]
    fn split_zero_minor_digit_currency_stays_whole_test() {
        let parts = Money::from_major(10, &Currency::XAU).split(n(3));

        assert_eq!(
            *parts,
            vec![
                Money::from_major(4, &Currency::XAU),
                Money::from_major(3, &Currency::XAU),
                Money::from_major(3, &Currency::XAU),
            ]
        );
    }

    #[test]
    fn split_near_decimal_max_conserves_the_total_test() {
        let a = Money::from_decimal(Decimal::MAX, &Currency::USD);

        let total = a
            .split(n(3))
            .into_iter()
            .reduce(|sum, part| sum + part)
            .unwrap();

        assert_eq!(total, a);
    }

    #[test]
    fn split_conserves_the_total_test() {
        let a = usd(dec!(100.03));

        let total = a
            .split(n(7))
            .into_iter()
            .reduce(|sum, part| sum + part)
            .unwrap();

        assert_eq!(total, a);
    }

    #[test]
    fn allocate_proportionally_test() {
        let parts = usd(dec!(10.00)).allocate(&vec1![n(7), n(3)]);

        assert_eq!(*parts, vec![usd(dec!(7.00)), usd(dec!(3.00))]);
    }

    #[test]
    fn allocate_gives_remainder_units_to_earlier_parts_test() {
        let parts = usd(dec!(0.05)).allocate(&vec1![n(3), n(7)]);

        assert_eq!(*parts, vec![usd(dec!(0.02)), usd(dec!(0.03))]);
    }

    #[test]
    fn allocate_single_weight_is_identity_test() {
        let a = usd(dec!(10.01));

        assert_eq!(*a.allocate(&vec1![n(42)]), vec![a]);
    }

    #[test]
    fn allocate_negative_is_symmetric_test() {
        let parts = usd(dec!(-0.05)).allocate(&vec1![n(3), n(7)]);

        assert_eq!(*parts, vec![usd(dec!(-0.02)), usd(dec!(-0.03))]);
    }

    #[test]
    fn allocate_conserves_the_total_test() {
        let a = usd(dec!(97.31));

        let total = a
            .allocate(&vec1![n(1), n(999), n(37), n(2)])
            .into_iter()
            .reduce(|sum, part| sum + part)
            .unwrap();

        assert_eq!(total, a);
    }

    #[test]
    fn allocate_with_equal_weights_matches_split_test() {
        let a = usd(dec!(10.00));

        assert_eq!(a.allocate(&vec1![n(5), n(5), n(5)]), a.split(n(3)));
    }
}