Quality.h

#pragma once
 
#include <xrpl/beast/utility/Zero.h>
#include <xrpl/beast/utility/instrumentation.h>
#include <xrpl/protocol/AmountConversions.h>
#include <xrpl/protocol/STAmount.h>
 
#include <algorithm>
#include <cmath>
#include <concepts>
#include <cstdint>
#include <ostream>
#include <utility>
 
namespace xrpl {

template <class In, class Out>
struct TAmounts
{
    TAmounts() = default;
 
    TAmounts(beast::Zero, beast::Zero) : in(beast::kZero), out(beast::kZero)
    {
    }
 
    TAmounts(In in, Out out) : in(std::move(in)), out(std::move(out))
    {
    }

    [[nodiscard]] bool
    empty() const noexcept
    {
        return in <= beast::kZero || out <= beast::kZero;
    }
 
    TAmounts&
    operator+=(TAmounts const& rhs)
    {
        in += rhs.in;
        out += rhs.out;
        return *this;
    }
 
    TAmounts&
    operator-=(TAmounts const& rhs)
    {
        in -= rhs.in;
        out -= rhs.out;
        return *this;
    }
 
    In in{};
    Out out{};
};
 
using Amounts = TAmounts<STAmount, STAmount>;
 
template <class In, class Out>
bool
operator==(TAmounts<In, Out> const& lhs, TAmounts<In, Out> const& rhs) noexcept
{
    return lhs.in == rhs.in && lhs.out == rhs.out;
}
 
//------------------------------------------------------------------------------
 
// XRPL specific constant used for parsing qualities and other things
#define QUALITY_ONE 1'000'000'000

class Quality
{
public:
    // Type of the internal representation. Higher qualities
    // have lower unsigned integer representations.
    using value_type = std::uint64_t;
 
    static int const kMinTickSize = 3;
    static int const kMaxTickSize = 16;
 
private:
    // This has the same representation as STAmount, see the comment on the
    // STAmount. However, this class does not always use the canonical
    // representation. In particular, the increment and decrement operators may
    // cause a non-canonical representation.
    value_type value_;
 
public:
    Quality() = default;

    explicit Quality(std::uint64_t value);

    explicit Quality(Amounts const& amount);

    template <class In, class Out>
    explicit Quality(TAmounts<In, Out> const& amount)
        : Quality(Amounts(toSTAmount(amount.in), toSTAmount(amount.out)))
    {
    }

    template <class In, class Out>
    Quality(Out const& out, In const& in) : Quality(Amounts(toSTAmount(in), toSTAmount(out)))
    {
    }

    Quality&
    operator++();
 
    Quality
    operator++(int);

    Quality&
    operator--();
 
    Quality
    operator--(int);

    [[nodiscard]] STAmount
    rate() const
    {
        return amountFromQuality(value_);
    }

    [[nodiscard]] Quality
    round(int tickSize) const;

    [[nodiscard]] Amounts
    ceilIn(Amounts const& amount, STAmount const& limit) const;
 
    template <class In, class Out>
    [[nodiscard]] TAmounts<In, Out>
    ceilIn(TAmounts<In, Out> const& amount, In const& limit) const;
 
    // Some of the underlying rounding functions called by ceil_in() ignored
    // low order bits that could influence rounding decisions.  This "strict"
    // method uses underlying functions that pay attention to all the bits.
    [[nodiscard]] Amounts
    ceilInStrict(Amounts const& amount, STAmount const& limit, bool roundUp) const;
 
    template <class In, class Out>
    [[nodiscard]] TAmounts<In, Out>
    ceilInStrict(TAmounts<In, Out> const& amount, In const& limit, bool roundUp) const;

    [[nodiscard]] Amounts
    ceilOut(Amounts const& amount, STAmount const& limit) const;
 
    template <class In, class Out>
    [[nodiscard]] TAmounts<In, Out>
    ceilOut(TAmounts<In, Out> const& amount, Out const& limit) const;
 
    // Some of the underlying rounding functions called by ceil_out() ignored
    // low order bits that could influence rounding decisions.  This "strict"
    // method uses underlying functions that pay attention to all the bits.
    [[nodiscard]] Amounts
    ceilOutStrict(Amounts const& amount, STAmount const& limit, bool roundUp) const;
 
    template <class In, class Out>
    [[nodiscard]] TAmounts<In, Out>
    ceilOutStrict(TAmounts<In, Out> const& amount, Out const& limit, bool roundUp) const;
 
private:
    // The ceil_in and ceil_out methods that deal in TAmount all convert
    // their arguments to STAmount and convert the result back to TAmount.
    // This helper function takes care of all the conversion operations.
    template <class In, class Out, class Lim, typename FnPtr, std::same_as<bool>... Round>
    [[nodiscard]] TAmounts<In, Out>
    ceilTAmountsHelper(
        TAmounts<In, Out> const& amount,
        Lim const& limit,
        Lim const& limitCmp,
        FnPtr ceilFunction,
        Round... round) const;
 
public:
    friend bool
    operator<(Quality const& lhs, Quality const& rhs) noexcept
    {
        return lhs.value_ > rhs.value_;
    }
 
    friend bool
    operator>(Quality const& lhs, Quality const& rhs) noexcept
    {
        return lhs.value_ < rhs.value_;
    }
 
    friend bool
    operator<=(Quality const& lhs, Quality const& rhs) noexcept
    {
        return !(lhs > rhs);
    }
 
    friend bool
    operator>=(Quality const& lhs, Quality const& rhs) noexcept
    {
        return !(lhs < rhs);
    }
 
    friend bool
    operator==(Quality const& lhs, Quality const& rhs) noexcept
    {
        return lhs.value_ == rhs.value_;
    }
 
    friend std::ostream&
    operator<<(std::ostream& os, Quality const& quality)
    {
        os << quality.value_;
        return os;
    }
 
    // return the relative distance (relative error) between two qualities. This
    // is used for testing only. relative distance is abs(a-b)/min(a,b)
    friend double
    relativeDistance(Quality const& q1, Quality const& q2)
    {
        XRPL_ASSERT(
            q1.value_ > 0 && q2.value_ > 0, "xrpl::Quality::relativeDistance : minimum inputs");
 
        if (q1.value_ == q2.value_)  // make expected common case fast
            return 0;
 
        auto const [minV, maxV] = std::minmax(q1.value_, q2.value_);
 
        auto mantissa = [](std::uint64_t rate) { return rate & ~(255ull << (64 - 8)); };
        auto exponent = [](std::uint64_t rate) { return static_cast<int>(rate >> (64 - 8)) - 100; };
 
        auto const minVMantissa = mantissa(minV);
        auto const maxVMantissa = mantissa(maxV);
        auto const expDiff = exponent(maxV) - exponent(minV);
 
        auto const minVD = static_cast<double>(minVMantissa);
        double const maxVD =
            (expDiff != 0) ? maxVMantissa * pow(10, expDiff) : static_cast<double>(maxVMantissa);
 
        // maxVD and minVD are scaled so they have the same exponents. Dividing
        // cancels out the exponents, so we only need to deal with the (scaled)
        // mantissas
        return (maxVD - minVD) / minVD;
    }
};
 
template <class In, class Out, class Lim, typename FnPtr, std::same_as<bool>... Round>
TAmounts<In, Out>
Quality::ceilTAmountsHelper(
    TAmounts<In, Out> const& amount,
    Lim const& limit,
    Lim const& limitCmp,
    FnPtr ceilFunction,
    Round... roundUp) const
{
    if (limitCmp <= limit)
        return amount;
 
    // Use the existing STAmount implementation for now, but consider
    // replacing with code specific to IOUAMount and XRPAmount
    Amounts const stAmt(toSTAmount(amount.in), toSTAmount(amount.out));
    STAmount const stLim(toSTAmount(limit));
    Amounts const stRes = ((*this).*ceilFunction)(stAmt, stLim, roundUp...);
    return TAmounts<In, Out>(toAmount<In>(stRes.in), toAmount<Out>(stRes.out));
}
 
template <class In, class Out>
TAmounts<In, Out>
Quality::ceilIn(TAmounts<In, Out> const& amount, In const& limit) const
{
    // Construct a function pointer to the function we want to call.
    static constexpr Amounts (Quality::*kCeilInFnPtr)(Amounts const&, STAmount const&) const =
        &Quality::ceilIn;
 
    return ceilTAmountsHelper(amount, limit, amount.in, kCeilInFnPtr);
}
 
template <class In, class Out>
TAmounts<In, Out>
Quality::ceilInStrict(TAmounts<In, Out> const& amount, In const& limit, bool roundUp) const
{
    // Construct a function pointer to the function we want to call.
    static constexpr Amounts (Quality::*kCeilInFnPtr)(Amounts const&, STAmount const&, bool) const =
        &Quality::ceilInStrict;
 
    return ceilTAmountsHelper(amount, limit, amount.in, kCeilInFnPtr, roundUp);
}
 
template <class In, class Out>
TAmounts<In, Out>
Quality::ceilOut(TAmounts<In, Out> const& amount, Out const& limit) const
{
    // Construct a function pointer to the function we want to call.
    static constexpr Amounts (Quality::*kCeilOutFnPtr)(Amounts const&, STAmount const&) const =
        &Quality::ceilOut;
 
    return ceil_TAmounts_helper(amount, limit, amount.out, kCeilOutFnPtr);
}
 
template <class In, class Out>
TAmounts<In, Out>
Quality::ceilOutStrict(TAmounts<In, Out> const& amount, Out const& limit, bool roundUp) const
{
    // Construct a function pointer to the function we want to call.
    static constexpr Amounts (Quality::*kCeilOutFnPtr)(Amounts const&, STAmount const&, bool)
        const = &Quality::ceilOutStrict;
 
    return ceilTAmountsHelper(amount, limit, amount.out, kCeilOutFnPtr, roundUp);
}

Quality
composedQuality(Quality const& lhs, Quality const& rhs);
 
}  // namespace xrpl