lucre 0.11.0

//! A table of rates, one per currency pair, and the ways in and out of it.

use std::{
    collections::{BTreeMap, btree_map},
    iter::FusedIterator,
};

use miette::Diagnostic;
use thiserror::Error;

use super::{ConvertError, ExchangeRate, Pair};
use crate::{Currency, Decimal, Money};

/// A set of exchange rates to look up by currency pair.
///
/// A table starts empty and fills with the rates it is given. Each pair holds
/// one rate at a time, and a new rate displaces the old one. The two
/// directions of a pair are separate entries, priced separately. Rates leave
/// one pair at a time with [`remove_rate`](Exchange::remove_rate), or all at
/// once with [`clear`](Exchange::clear).
///
/// [`convert`](Exchange::convert) prices an amount without the caller ever
/// handling a rate. [`rate`](Exchange::rate) hands one over for the work the
/// table does not do itself, such as crossing a pair it does not quote.
///
/// Whatever reads a table whole — [`iter`](Exchange::iter), [`IntoIterator`],
/// serialization — reads it in *pair order*: by the currency being priced,
/// then by the currency it is priced in.
///
/// ## Example
///
/// ```
/// # use std::error::Error;
/// #
/// # fn main() -> Result<(), Box<dyn Error>> {
/// use lucre::{Currency, Exchange, ExchangeRate, Money};
/// use rust_decimal::dec;
///
/// let mut desk = Exchange::new();
/// desk.set_rate(ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.9))?);
///
/// assert_eq!(
///     desk.convert(Money::from_major(100, Currency::USD), Currency::EUR)?,
///     Money::from_major(90, Currency::EUR)
/// );
/// assert!(desk.rate((Currency::EUR, Currency::USD)).is_none());
///
/// // A whole feed goes in the same way, one rate at a time.
/// let board: Exchange = [
///     ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.92))?,
///     ExchangeRate::new((Currency::EUR, Currency::JPY), dec!(160))?,
/// ]
/// .into_iter()
/// .collect();
///
/// assert_eq!(board.len(), 2);
/// #
/// #     Ok(())
/// # }
/// ```
#[derive(Clone, Debug, Default, Eq, Hash, PartialEq)]
pub struct Exchange {
    rates: BTreeMap<Pair, Decimal>,
}

impl Exchange {
    /// Create an empty table.
    ///
    /// ## Example
    ///
    /// ```
    /// use lucre::{Currency, Exchange};
    ///
    /// assert!(
    ///     Exchange::new()
    ///         .rate((Currency::USD, Currency::EUR))
    ///         .is_none()
    /// );
    /// ```
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Add a rate to the table, handing back the one it displaces.
    ///
    /// A pair quoted for the first time displaces nothing, so nothing comes
    /// back.
    ///
    /// ## Example
    ///
    /// ```
    /// # use std::error::Error;
    /// #
    /// # fn main() -> Result<(), Box<dyn Error>> {
    /// use lucre::{Currency, Exchange, ExchangeRate};
    /// use rust_decimal::dec;
    ///
    /// let opening = ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.9))?;
    /// let revised = ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.92))?;
    /// let mut desk = Exchange::new();
    ///
    /// assert_eq!(desk.set_rate(opening), None);
    /// assert_eq!(desk.set_rate(revised), Some(opening));
    /// assert_eq!(desk.rate((Currency::USD, Currency::EUR)), Some(revised));
    /// #
    /// #     Ok(())
    /// # }
    /// ```
    pub fn set_rate(&mut self, rate: ExchangeRate) -> Option<ExchangeRate> {
        self.rates
            .insert(rate.pair(), rate.rate())
            .map(|displaced| ExchangeRate::new_unchecked(rate.pair(), displaced))
    }

    /// Remove a pair's rate, handing back what the table held.
    ///
    /// The pair may be given as a [`Pair`] or as the two currencies alone,
    /// base first. The other direction of the pair stays where it is.
    ///
    /// ## Example
    ///
    /// ```
    /// # use std::error::Error;
    /// #
    /// # fn main() -> Result<(), Box<dyn Error>> {
    /// use lucre::{Currency, Exchange, ExchangeRate};
    /// use rust_decimal::dec;
    ///
    /// let usd_eur = ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.9))?;
    /// let mut desk = Exchange::new();
    /// desk.set_rate(usd_eur);
    ///
    /// assert_eq!(desk.remove_rate((Currency::USD, Currency::EUR)), Some(usd_eur));
    /// assert_eq!(desk.remove_rate((Currency::USD, Currency::EUR)), None);
    /// #
    /// #     Ok(())
    /// # }
    /// ```
    pub fn remove_rate<P: Into<Pair>>(&mut self, pair: P) -> Option<ExchangeRate> {
        let pair = pair.into();

        self.rates
            .remove(&pair)
            .map(|rate| ExchangeRate::new_unchecked(pair, rate))
    }

    /// Remove every rate, leaving the table empty.
    ///
    /// ## Example
    ///
    /// ```
    /// # use std::error::Error;
    /// #
    /// # fn main() -> Result<(), Box<dyn Error>> {
    /// use lucre::{Currency, Exchange, ExchangeRate};
    /// use rust_decimal::dec;
    ///
    /// let mut desk = Exchange::new();
    /// desk.set_rate(ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.9))?);
    /// desk.clear();
    ///
    /// assert!(desk.is_empty());
    /// #
    /// #     Ok(())
    /// # }
    /// ```
    pub fn clear(&mut self) {
        self.rates.clear();
    }

    /// The rate the table quotes over a pair.
    ///
    /// The pair may be given as a [`Pair`] or as the two currencies alone,
    /// base first.
    ///
    /// ## Example
    ///
    /// ```
    /// # use std::error::Error;
    /// #
    /// # fn main() -> Result<(), Box<dyn Error>> {
    /// use lucre::{Currency, Exchange, ExchangeRate, Pair};
    /// use rust_decimal::dec;
    ///
    /// let usd_eur = ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.9))?;
    /// let mut desk = Exchange::new();
    /// desk.set_rate(usd_eur);
    ///
    /// assert_eq!(desk.rate((Currency::USD, Currency::EUR)), Some(usd_eur));
    /// assert_eq!(desk.rate("USD/EUR".parse::<Pair>()?), Some(usd_eur));
    /// assert_eq!(desk.rate((Currency::EUR, Currency::USD)), None);
    /// #
    /// #     Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn rate<P: Into<Pair>>(&self, pair: P) -> Option<ExchangeRate> {
        let pair = pair.into();

        self.rates
            .get(&pair)
            .map(|&rate| ExchangeRate::new_unchecked(pair, rate))
    }

    /// Restate an amount in another currency, at the rate the table quotes.
    ///
    /// The result keeps the full precision [`ExchangeRate::convert`] gives it.
    ///
    /// ## Example
    ///
    /// ```
    /// # use std::error::Error;
    /// #
    /// # fn main() -> Result<(), Box<dyn Error>> {
    /// use lucre::{Currency, Exchange, ExchangeError, ExchangeRate, Money};
    /// use rust_decimal::dec;
    ///
    /// let mut desk = Exchange::new();
    /// desk.set_rate(ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.9))?);
    ///
    /// let fare = Money::from_major(100, Currency::USD);
    ///
    /// assert_eq!(desk.convert(fare, Currency::EUR)?, Money::from_major(90, Currency::EUR));
    /// assert!(matches!(
    ///     desk.convert(fare, Currency::JPY),
    ///     Err(ExchangeError::Unquoted { base: Currency::USD, quote: Currency::JPY, .. })
    /// ));
    ///
    /// desk.set_rate(ExchangeRate::identity(Currency::USD));
    ///
    /// assert_eq!(desk.convert(fare, Currency::USD)?, fare);
    /// #
    /// #     Ok(())
    /// # }
    /// ```
    ///
    /// ## Errors
    ///
    /// Returns [`ExchangeError::Unquoted`] if the table quotes no rate from
    /// the amount's currency to the one asked for. This includes a currency
    /// against itself; add [`ExchangeRate::identity`] to quote that pair.
    /// Returns [`ExchangeError::Convert`] if the rate the table quotes could
    /// not convert the amount.
    pub fn convert(&self, money: Money, into: Currency) -> Result<Money, ExchangeError> {
        Ok(self
            .rate((money.currency(), into))
            .ok_or(ExchangeError::Unquoted {
                base: money.currency(),
                quote: into,
            })?
            .convert(money)?)
    }

    /// Whether the table holds no rates.
    ///
    /// ## Example
    ///
    /// ```
    /// # use std::error::Error;
    /// #
    /// # fn main() -> Result<(), Box<dyn Error>> {
    /// use lucre::{Currency, Exchange, ExchangeRate};
    /// use rust_decimal::dec;
    ///
    /// let mut desk = Exchange::new();
    /// assert!(desk.is_empty());
    ///
    /// desk.set_rate(ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.9))?);
    /// assert!(!desk.is_empty());
    /// #
    /// #     Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.rates.is_empty()
    }

    /// How many pairs the table quotes.
    ///
    /// Each direction of a pair counts separately. A pair quoted again still
    /// counts once, since the new rate displaced the old one.
    ///
    /// ## Example
    ///
    /// ```
    /// # use std::error::Error;
    /// #
    /// # fn main() -> Result<(), Box<dyn Error>> {
    /// use lucre::{Currency, Exchange, ExchangeRate};
    /// use rust_decimal::dec;
    ///
    /// let mut desk = Exchange::new();
    /// desk.set_rate(ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.9))?);
    /// desk.set_rate(ExchangeRate::new((Currency::EUR, Currency::USD), dec!(1.1))?);
    /// assert_eq!(desk.len(), 2);
    ///
    /// desk.set_rate(ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.92))?);
    /// assert_eq!(desk.len(), 2);
    /// #
    /// #     Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn len(&self) -> usize {
        self.rates.len()
    }

    /// Every rate the table holds, in pair order.
    ///
    /// ## Example
    ///
    /// ```
    /// # use std::error::Error;
    /// #
    /// # fn main() -> Result<(), Box<dyn Error>> {
    /// use lucre::{Currency, Exchange, ExchangeRate};
    /// use rust_decimal::dec;
    ///
    /// let usd_eur = ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.9))?;
    /// let mut desk = Exchange::new();
    /// desk.set_rate(usd_eur);
    ///
    /// assert_eq!(desk.iter().collect::<Vec<_>>(), vec![usd_eur]);
    /// #
    /// #     Ok(())
    /// # }
    /// ```
    pub fn iter(&self) -> Rates<'_> {
        Rates(self.rates.iter())
    }

    /// Which pairs the table quotes, in [pair order](Exchange).
    ///
    /// A pair is quoted in one direction only, so a pair listed here does not
    /// put its reverse in the table.
    ///
    /// ## Example
    ///
    /// ```
    /// # use std::error::Error;
    /// #
    /// # fn main() -> Result<(), Box<dyn Error>> {
    /// use lucre::{Currency, Exchange, ExchangeRate, Pair};
    /// use rust_decimal::dec;
    ///
    /// let mut desk = Exchange::new();
    /// desk.set_rate(ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.9))?);
    ///
    /// assert_eq!(
    ///     desk.pairs().collect::<Vec<_>>(),
    ///     [Pair::new(Currency::USD, Currency::EUR)]
    /// );
    /// #
    /// #     Ok(())
    /// # }
    /// ```
    pub fn pairs(&self) -> Pairs<'_> {
        Pairs(self.rates.keys())
    }
}

/// One [`Pair`] per rate a borrowed table quotes, in [pair order](Exchange).
///
/// ## Example
///
/// ```
/// # use std::error::Error;
/// #
/// # fn main() -> Result<(), Box<dyn Error>> {
/// use lucre::{Currency, Exchange, ExchangeRate, Pairs};
/// use rust_decimal::dec;
///
/// let desk: Exchange = [ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.9))?]
///     .into_iter()
///     .collect();
/// let pairs: Pairs<'_> = desk.pairs();
///
/// assert_eq!(pairs.count(), 1);
/// #
/// #     Ok(())
/// # }
/// ```
#[derive(Debug, Clone)]
#[must_use = "iterators are lazy and do nothing unless consumed"]
pub struct Pairs<'a>(btree_map::Keys<'a, Pair, Decimal>);

impl Iterator for Pairs<'_> {
    type Item = Pair;

    fn next(&mut self) -> Option<Self::Item> {
        self.0.next().copied()
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        self.0.size_hint()
    }
}

impl DoubleEndedIterator for Pairs<'_> {
    fn next_back(&mut self) -> Option<Self::Item> {
        self.0.next_back().copied()
    }
}

impl ExactSizeIterator for Pairs<'_> {
    fn len(&self) -> usize {
        self.0.len()
    }
}

impl FusedIterator for Pairs<'_> {}

/// What a borrowed table yields: one [`ExchangeRate`] per pair quoted, in
/// [pair order](Exchange).
///
/// ## Example
///
/// ```
/// # use std::error::Error;
/// #
/// # fn main() -> Result<(), Box<dyn Error>> {
/// use lucre::{Currency, Exchange, ExchangeRate, Rates};
/// use rust_decimal::dec;
///
/// let desk: Exchange = [ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.9))?]
///     .into_iter()
///     .collect();
/// let rates: Rates<'_> = desk.iter();
///
/// assert_eq!(rates.count(), 1);
/// #
/// #     Ok(())
/// # }
/// ```
#[derive(Debug, Clone)]
#[must_use = "iterators are lazy and do nothing unless consumed"]
pub struct Rates<'a>(btree_map::Iter<'a, Pair, Decimal>);

impl Iterator for Rates<'_> {
    type Item = ExchangeRate;

    fn next(&mut self) -> Option<Self::Item> {
        self.0.next().map(borrowed_entry_to_rate)
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        self.0.size_hint()
    }
}

impl DoubleEndedIterator for Rates<'_> {
    fn next_back(&mut self) -> Option<Self::Item> {
        self.0.next_back().map(borrowed_entry_to_rate)
    }
}

impl ExactSizeIterator for Rates<'_> {
    fn len(&self) -> usize {
        self.0.len()
    }
}

impl FusedIterator for Rates<'_> {}

/// The same rates, out of a table consumed whole.
///
/// ## Example
///
/// ```
/// # use std::error::Error;
/// #
/// # fn main() -> Result<(), Box<dyn Error>> {
/// use lucre::{Currency, Exchange, ExchangeRate, IntoRates};
/// use rust_decimal::dec;
///
/// let desk: Exchange = [ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.9))?]
///     .into_iter()
///     .collect();
/// let rates: IntoRates = desk.into_iter();
///
/// assert_eq!(rates.count(), 1);
/// #
/// #     Ok(())
/// # }
/// ```
#[derive(Debug)]
#[must_use = "iterators are lazy and do nothing unless consumed"]
pub struct IntoRates(btree_map::IntoIter<Pair, Decimal>);

impl Iterator for IntoRates {
    type Item = ExchangeRate;

    fn next(&mut self) -> Option<Self::Item> {
        self.0.next().map(entry_to_rate)
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        self.0.size_hint()
    }
}

impl DoubleEndedIterator for IntoRates {
    fn next_back(&mut self) -> Option<Self::Item> {
        self.0.next_back().map(entry_to_rate)
    }
}

impl ExactSizeIterator for IntoRates {
    fn len(&self) -> usize {
        self.0.len()
    }
}

impl FusedIterator for IntoRates {}

fn entry_to_rate((pair, rate): (Pair, Decimal)) -> ExchangeRate {
    ExchangeRate::new_unchecked(pair, rate)
}

fn borrowed_entry_to_rate((pair, rate): (&Pair, &Decimal)) -> ExchangeRate {
    entry_to_rate((*pair, *rate))
}

impl IntoIterator for Exchange {
    type Item = ExchangeRate;
    type IntoIter = IntoRates;

    fn into_iter(self) -> Self::IntoIter {
        IntoRates(self.rates.into_iter())
    }
}

/// Borrowing a table still yields owned [`ExchangeRate`]s, which are [`Copy`].
impl<'a> IntoIterator for &'a Exchange {
    type Item = ExchangeRate;
    type IntoIter = Rates<'a>;

    fn into_iter(self) -> Self::IntoIter {
        self.iter()
    }
}

/// Adds each rate as [`set_rate`](Exchange::set_rate) does, so a pair quoted
/// more than once keeps the rate given last. This holds whether the rate it
/// displaces came from the same batch or was already in the table.
///
/// ## Example
///
/// ```
/// # use std::error::Error;
/// #
/// # fn main() -> Result<(), Box<dyn Error>> {
/// use lucre::{Currency, Exchange, ExchangeRate};
/// use rust_decimal::dec;
///
/// let mut desk = Exchange::new();
/// desk.set_rate(ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.9))?);
/// desk.extend([
///     ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.92))?,
///     ExchangeRate::new((Currency::EUR, Currency::JPY), dec!(160))?,
/// ]);
///
/// assert_eq!(
///     desk.rate((Currency::USD, Currency::EUR)).map(|rate| rate.rate()),
///     Some(dec!(0.92))
/// );
/// assert_eq!(desk.iter().len(), 2);
/// #
/// #     Ok(())
/// # }
/// ```
impl Extend<ExchangeRate> for Exchange {
    fn extend<I: IntoIterator<Item = ExchangeRate>>(&mut self, iter: I) {
        for rate in iter {
            self.set_rate(rate);
        }
    }
}

impl<'a> Extend<&'a ExchangeRate> for Exchange {
    fn extend<I: IntoIterator<Item = &'a ExchangeRate>>(&mut self, iter: I) {
        self.extend(iter.into_iter().copied());
    }
}

/// Collects rates into a table, adding each one as [`Extend`] does.
///
/// ## Example
///
/// ```
/// # use std::error::Error;
/// #
/// # fn main() -> Result<(), Box<dyn Error>> {
/// use lucre::{Currency, Exchange, ExchangeRate, Money};
/// use rust_decimal::dec;
///
/// let feed = [
///     ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.9))?,
///     ExchangeRate::new((Currency::EUR, Currency::JPY), dec!(160))?,
/// ];
///
/// let desk: Exchange = feed.into_iter().collect();
///
/// assert_eq!(
///     desk.convert(Money::from_major(100, Currency::USD), Currency::EUR)?,
///     Money::from_major(90, Currency::EUR)
/// );
/// #
/// #     Ok(())
/// # }
/// ```
impl FromIterator<ExchangeRate> for Exchange {
    fn from_iter<I: IntoIterator<Item = ExchangeRate>>(iter: I) -> Self {
        let mut desk = Self::new();
        desk.extend(iter);

        desk
    }
}

impl<'a> FromIterator<&'a ExchangeRate> for Exchange {
    fn from_iter<I: IntoIterator<Item = &'a ExchangeRate>>(iter: I) -> Self {
        iter.into_iter().copied().collect()
    }
}

/// An error from converting an amount against an [`Exchange`].
#[derive(Clone, Debug, Diagnostic, Error, Eq, PartialEq)]
#[diagnostic(url(docsrs))]
#[non_exhaustive]
pub enum ExchangeError {
    /// The table holds no rate for the pair.
    #[error("the table quotes no rate from {base} to {quote}")]
    #[diagnostic(
        code(lucre::exchange::unquoted),
        help("set a rate for the pair, or cross two rates that meet at a shared currency")
    )]
    #[non_exhaustive]
    Unquoted {
        /// The currency the amount was in.
        base: Currency,

        /// The currency asked for.
        quote: Currency,
    },

    /// The table quotes the pair, but converting at that rate failed. The
    /// source error says why, and names the pair.
    #[error("the rate the table quotes could not convert the amount")]
    #[diagnostic(code(lucre::exchange::convert), forward(source))]
    #[non_exhaustive]
    Convert {
        /// The error [`ExchangeRate::convert`] gave.
        #[from]
        source: ConvertError,
    },
}

#[cfg(test)]
mod tests {
    use super::*;
    use rust_decimal::prelude::*;
    use std::{
        collections::{HashSet, hash_map::DefaultHasher},
        hash::{Hash, Hasher},
    };

    fn usd_eur() -> ExchangeRate {
        ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.9)).unwrap()
    }

    #[test]
    fn exchange_answers_a_rate_it_was_given_test() {
        let mut desk = Exchange::new();
        desk.set_rate(usd_eur());

        assert_eq!(desk.rate((Currency::USD, Currency::EUR)), Some(usd_eur()));
    }

    #[test]
    fn exchange_answers_a_pair_named_in_advance_test() {
        let mut desk = Exchange::new();
        desk.set_rate(usd_eur());

        assert_eq!(
            desk.rate(Pair::new(Currency::USD, Currency::EUR)),
            Some(usd_eur())
        );
    }

    #[test]
    fn exchange_takes_a_pair_by_borrow_test() {
        let quoted = [Pair::new(Currency::USD, Currency::EUR)];
        let mut desk = Exchange::new();
        desk.set_rate(usd_eur());

        for pair in &quoted {
            assert_eq!(desk.rate(pair), Some(usd_eur()));
            assert_eq!(desk.remove_rate(pair), Some(usd_eur()));
        }
    }

    #[test]
    fn exchange_keeps_the_directions_of_a_pair_apart_test() {
        let mut desk = Exchange::new();
        desk.set_rate(usd_eur());

        assert_eq!(desk.rate((Currency::EUR, Currency::USD)), None);
    }

    #[test]
    fn exchange_displaces_an_earlier_rate_test() {
        let revised = ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.92)).unwrap();
        let mut desk = Exchange::new();
        desk.set_rate(usd_eur());
        desk.set_rate(revised);

        assert_eq!(desk.rate((Currency::USD, Currency::EUR)), Some(revised));
    }

    #[test]
    fn exchange_hands_back_the_rate_it_displaces_test() {
        let revised = ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.92)).unwrap();
        let mut desk = Exchange::new();

        assert_eq!(desk.set_rate(usd_eur()), None);
        assert_eq!(desk.set_rate(revised), Some(usd_eur()));
    }

    #[test]
    fn exchange_takes_par_in_as_it_takes_any_pair_test() {
        let par = ExchangeRate::identity(Currency::USD);
        let mut desk = Exchange::new();

        assert_eq!(desk.set_rate(par), None);
        assert_eq!(desk.set_rate(par), Some(par));
    }

    #[test]
    fn exchange_holds_nothing_to_begin_with_test() {
        assert_eq!(Exchange::new().rate((Currency::USD, Currency::EUR)), None);
        assert_eq!(Exchange::new().rate((Currency::USD, Currency::USD)), None);
    }

    #[test]
    fn exchange_converts_at_the_rate_it_quotes_test() {
        let desk = Exchange::from_iter([usd_eur()]);

        assert_eq!(
            desk.convert(Money::from_major(100, Currency::USD), Currency::EUR),
            Ok(Money::from_major(90, Currency::EUR))
        );
    }

    #[test]
    fn exchange_refuses_to_convert_across_an_unquoted_self_pair_test() {
        let fare = Money::from_minor(275, Currency::USD);

        assert_eq!(
            Exchange::new().convert(fare, Currency::USD),
            Err(ExchangeError::Unquoted {
                base: Currency::USD,
                quote: Currency::USD,
            })
        );
    }

    #[test]
    fn exchange_converts_at_a_quoted_self_pair_test() {
        let discounted = ExchangeRate::new((Currency::USD, Currency::USD), dec!(0.99)).unwrap();
        let desk = Exchange::from_iter([discounted]);

        assert_eq!(desk.rate((Currency::USD, Currency::USD)), Some(discounted));
        assert_eq!(
            desk.convert(Money::from_minor(275, Currency::USD), Currency::USD),
            Ok(Money::from_decimal(dec!(2.7225), Currency::USD))
        );
    }

    #[test]
    fn exchange_refuses_to_convert_across_an_unquoted_pair_test() {
        let desk = Exchange::from_iter([usd_eur()]);

        assert_eq!(
            desk.convert(Money::from_major(100, Currency::USD), Currency::JPY),
            Err(ExchangeError::Unquoted {
                base: Currency::USD,
                quote: Currency::JPY
            })
        );
    }

    #[test]
    fn refusal_names_the_pair_it_could_not_price_test() {
        let refused = ExchangeError::Unquoted {
            base: Currency::USD,
            quote: Currency::JPY,
        };

        assert!(refused.to_string().contains("USD"));
        assert!(refused.to_string().contains("JPY"));
    }

    #[test]
    fn exchange_reports_an_unrepresentable_conversion_test() {
        let steep = ExchangeRate::new((Currency::USD, Currency::EUR), Decimal::MAX).unwrap();
        let desk = Exchange::from_iter([steep]);
        let fortune = Money::from_decimal(Decimal::MAX, Currency::USD);

        let refused = desk.convert(fortune, Currency::EUR).unwrap_err();

        assert!(matches!(refused, ExchangeError::Convert { .. }));
        assert_eq!(
            std::error::Error::source(&refused)
                .map(ToString::to_string)
                .as_deref(),
            Some("converting at USD/EUR gives an amount too large for a decimal")
        );
    }

    #[test]
    fn exchange_is_empty_until_a_pair_is_quoted_test() {
        let mut desk = Exchange::new();

        assert!(desk.is_empty());

        desk.set_rate(usd_eur());

        assert!(!desk.is_empty());
    }

    #[test]
    fn exchange_counts_one_rate_per_pair_test() {
        let eur_usd = ExchangeRate::new((Currency::EUR, Currency::USD), dec!(1.1)).unwrap();
        let revised = ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.92)).unwrap();
        let mut desk = Exchange::new();

        assert_eq!(desk.len(), 0);

        desk.set_rate(usd_eur());
        desk.set_rate(eur_usd);
        desk.set_rate(revised);

        assert_eq!(desk.len(), 2);
    }

    #[test]
    fn exchange_hands_back_the_rate_it_withdraws_test() {
        let mut desk = Exchange::new();
        desk.set_rate(usd_eur());

        assert_eq!(
            desk.remove_rate((Currency::USD, Currency::EUR)),
            Some(usd_eur())
        );
        assert_eq!(desk.rate((Currency::USD, Currency::EUR)), None);
    }

    #[test]
    fn exchange_withdraws_a_pair_named_in_advance_test() {
        let mut desk = Exchange::new();
        desk.set_rate(usd_eur());

        assert_eq!(
            desk.remove_rate(Pair::new(Currency::USD, Currency::EUR)),
            Some(usd_eur())
        );
    }

    #[test]
    fn exchange_withdraws_one_direction_of_a_pair_test() {
        let eur_usd = ExchangeRate::new((Currency::EUR, Currency::USD), dec!(1.1)).unwrap();
        let mut desk = Exchange::from_iter([usd_eur(), eur_usd]);

        desk.remove_rate((Currency::USD, Currency::EUR));

        assert_eq!(desk.rate((Currency::EUR, Currency::USD)), Some(eur_usd));
    }

    #[test]
    fn exchange_withdraws_nothing_from_an_unquoted_pair_test() {
        let mut desk = Exchange::new();

        assert_eq!(desk.remove_rate((Currency::USD, Currency::EUR)), None);
    }

    #[test]
    fn exchange_clears_every_rate_test() {
        let eur_usd = ExchangeRate::new((Currency::EUR, Currency::USD), dec!(1.1)).unwrap();
        let mut desk = Exchange::from_iter([usd_eur(), eur_usd]);

        desk.clear();

        assert_eq!(desk, Exchange::new());
        assert_eq!(desk.rate((Currency::USD, Currency::EUR)), None);
    }

    #[test]
    fn exchange_iterates_in_pair_order_test() {
        let usd_jpy = ExchangeRate::new((Currency::USD, Currency::JPY), dec!(144)).unwrap();
        let eur_usd = ExchangeRate::new((Currency::EUR, Currency::USD), dec!(1.1)).unwrap();
        let mut desk = Exchange::new();
        desk.set_rate(usd_jpy);
        desk.set_rate(usd_eur());
        desk.set_rate(eur_usd);

        assert_eq!(
            desk.iter().collect::<Vec<_>>(),
            [eur_usd, usd_eur(), usd_jpy]
        );
    }

    #[test]
    fn exchange_collects_from_rates_test() {
        let eur_usd = ExchangeRate::new((Currency::EUR, Currency::USD), dec!(1.1)).unwrap();
        let rates = [usd_eur(), eur_usd];

        let owned: Exchange = rates.into_iter().collect();
        let borrowed: Exchange = rates.iter().collect();

        assert_eq!(owned.rate((Currency::USD, Currency::EUR)), Some(usd_eur()));
        assert_eq!(owned.rate((Currency::EUR, Currency::USD)), Some(eur_usd));
        assert_eq!(owned, borrowed);
    }

    #[test]
    fn exchange_collects_a_later_rate_over_an_earlier_one_test() {
        let revised = ExchangeRate::new((Currency::USD, Currency::EUR), dec!(0.92)).unwrap();

        let desk: Exchange = [usd_eur(), revised].into_iter().collect();

        assert_eq!(desk.rate((Currency::USD, Currency::EUR)), Some(revised));
    }

    #[test]
    fn exchange_extends_from_rates_test() {
        let eur_usd = ExchangeRate::new((Currency::EUR, Currency::USD), dec!(1.1)).unwrap();
        let usd_jpy = ExchangeRate::new((Currency::USD, Currency::JPY), dec!(144)).unwrap();
        let mut desk = Exchange::from_iter([usd_eur()]);
        desk.extend([eur_usd]);
        desk.extend([&usd_jpy]);

        assert_eq!(desk.rate((Currency::USD, Currency::EUR)), Some(usd_eur()));
        assert_eq!(desk.rate((Currency::EUR, Currency::USD)), Some(eur_usd));
        assert_eq!(desk.rate((Currency::USD, Currency::JPY)), Some(usd_jpy));
    }

    #[test]
    fn into_iterator_yields_rates_test() {
        let eur_usd = ExchangeRate::new((Currency::EUR, Currency::USD), dec!(1.1)).unwrap();
        let desk: Exchange = [usd_eur(), eur_usd].into_iter().collect();

        let borrowed: Vec<ExchangeRate> = (&desk).into_iter().collect();
        let owned: Vec<ExchangeRate> = desk.into_iter().collect();

        assert_eq!(owned, [eur_usd, usd_eur()]);
        assert_eq!(owned, borrowed);
    }

    #[test]
    fn rates_count_and_reverse_without_walking_forward_test() {
        let eur_usd = ExchangeRate::new((Currency::EUR, Currency::USD), dec!(1.1)).unwrap();
        let desk: Exchange = [usd_eur(), eur_usd].into_iter().collect();

        assert_eq!(desk.iter().len(), 2);
        assert_eq!(desk.iter().rev().collect::<Vec<_>>(), [usd_eur(), eur_usd]);
        assert_eq!(
            desk.into_iter().rev().collect::<Vec<_>>(),
            [usd_eur(), eur_usd]
        );
    }

    #[test]
    fn equal_tables_hash_alike_test() {
        let eur_usd = ExchangeRate::new((Currency::EUR, Currency::USD), dec!(1.1)).unwrap();
        let one = Exchange::from_iter([usd_eur(), eur_usd]);
        let other = Exchange::from_iter([eur_usd, usd_eur()]);

        let hash_of = |desk: &Exchange| {
            let mut hasher = DefaultHasher::new();
            desk.hash(&mut hasher);
            hasher.finish()
        };

        assert_eq!(one, other);
        assert_eq!(hash_of(&one), hash_of(&other));
        assert_eq!(HashSet::from([one, other]).len(), 1);
    }
}