GncRational Class Reference

Rational number class using GncInt128 for the numerator and denominator. More...

#include <gnc-rational.hpp>

Public Member Functions
	GncRational ()
	Default constructor provides the zero value.
	GncRational (GncInt128 num, GncInt128 den) noexcept
	GncInt128 constructor. More...
	GncRational (gnc_numeric n) noexcept
	Convenience constructor from the C API's gnc_numeric. More...
	GncRational (GncNumeric n) noexcept
	GncNumeric constructor. More...
	GncRational (const GncRational &rhs)=default
	GncRational (GncRational &&rhs)=default
GncRational &	operator= (const GncRational &rhs)=default
GncRational &	operator= (GncRational &&rhs)=default
bool	valid () const noexcept
	Report if both members are valid numbers. More...
bool	is_big () const noexcept
	Report if either numerator or denominator are too big to fit in an int64_t. More...
	operator gnc_numeric () const noexcept
	Conversion operator; use static_cast<gnc_numeric>(foo). More...
GncRational	operator- () const noexcept
	Make a new GncRational with the opposite sign. More...
GncRational	reduce () const
	Return an equivalent fraction with all common factors between the numerator and the denominator removed. More...
GncRational	round_to_numeric () const
	Round to fit an int64_t, finding the closest possible approximation. More...
template<RoundType RT>
GncRational	convert (GncInt128 new_denom) const
	Convert a GncRational to use a new denominator. More...
template<RoundType RT>
GncRational	convert_sigfigs (unsigned int figs) const
	Convert with the specified sigfigs. More...
GncInt128	num () const noexcept
	Numerator accessor.
GncInt128	denom () const noexcept
	Denominator accessor.
void	operator+= (GncRational b)
void	operator-= (GncRational b)
void	operator*= (GncRational b)
void	operator/= (GncRational b)
GncRational	inv () const noexcept
	Inverts the number, equivalent of /= {1, 1}.
GncRational	abs () const noexcept
	Absolute value; return value is always >= 0 and of same magnitude. More...
int	cmp (GncRational b)
	Compare function. More...
int	cmp (GncInt128 b)

Detailed Description

Rational number class using GncInt128 for the numerator and denominator.

This class provides far greater overflow protection compared to GncNumeric at the expense of doubling the size, so GncNumeric is preferred for storage into objects. Furthermore the backends are not able to store GncRational numbers; storage in SQL would require using BLOBs which would preclude calculations in queries. GncRational exists primarily as a more overflow-resistant calculation facility for GncNumeric. It's available for cases where one needs an error instead of an automatically rounded value for a calculation that produces a result that won't fit into an int64 without rounding.

Errors: Errors are signalled by exceptions as follows:

• A zero denominator will raise a std::invalid_argument.
• Division by zero will raise a std::underflow_error.
• Overflowing 128 bits will raise a std::overflow_error.
• Failure to convert a number as specified by the arguments to convert() will raise a std::domain_error.

Definition at line 57 of file gnc-rational.hpp.

Constructor & Destructor Documentation

GncRational() [1/3]

GncRational::GncRational ( GncInt128  num, GncInt128  den  )

inlinenoexcept

GncInt128 constructor.

This will take any flavor of built-in integer thanks to implicit construction of the GncInt128s.

Definition at line 68 of file gnc-rational.hpp.

        : m_num(num), m_den(den) {}

GncRational() [2/3]

GncRational::GncRational ( gnc_numeric  n )

noexcept

Convenience constructor from the C API's gnc_numeric.

Definition at line 39 of file gnc-rational.cpp.

                                                :
    m_num (n.num), m_den (n.denom)
{
    if (m_den.isNeg())
    {
          m_num *= -m_den;
          m_den = 1;
    }
}

GncRational() [3/3]

GncRational::GncRational ( GncNumeric  n )

noexcept

GncNumeric constructor.

Definition at line 29 of file gnc-rational.cpp.

                                              :
    m_num(n.num()), m_den(n.denom())
{
    if (m_den.isNeg())
    {
        m_num *= -m_den;
        m_den = 1;
    }
}

Member Function Documentation

abs()

GncRational GncRational::abs ( ) const

noexcept

Absolute value; return value is always >= 0 and of same magnitude.

Definition at line 96 of file gnc-rational.cpp.

{
    if (m_num < 0)
        return -*this;
    return *this;
}

cmp()

int GncRational::cmp

(

GncRational

b

)

Compare function.

Parameters

b	GncNumeric or integer value to compare to.

Returns

-1 if < b, 0 if equal, 1 if > b.

Definition at line 132 of file gnc-rational.cpp.

{
    if (m_den == b.denom())
    {
        auto b_num = b.num();
        return m_num < b_num ? -1 : b_num < m_num ? 1 : 0;
    }
    auto gcd = m_den.gcd(b.denom());
    GncInt128 a_num(m_num * b.denom() / gcd), b_num(b.num() * m_den / gcd);
    return a_num < b_num ? -1 : b_num < a_num ? 1 : 0;
}

convert()

template<RoundType RT>

GncRational GncRational::convert ( GncInt128  new_denom ) const

inline

Convert a GncRational to use a new denominator.

If rounding is necessary use the indicated template specification. For example, to use half-up rounding you'd call bar = foo.convert<RoundType::half_up>(1000). If you specify RoundType::never this will throw std::domain_error if rounding is required.

Parameters

new_denom

The new denominator to convert the fraction to.

Returns

A new GncRational having the requested denominator.

Definition at line 117 of file gnc-rational.hpp.

    {
        auto params = prepare_conversion(new_denom);
        if (new_denom == GNC_DENOM_AUTO)
            new_denom = m_den;
        if (params.rem == 0)
            return GncRational(params.num, new_denom);
        return GncRational(round(params.num, params.den,
                                 params.rem, RT2T<RT>()), new_denom);
    }

convert_sigfigs()

template<RoundType RT>

GncRational GncRational::convert_sigfigs ( unsigned int  figs ) const

inline

Convert with the specified sigfigs.

The resulting denominator depends on the value of the GncRational, such that the specified significant digits are retained in the numerator and the denominator is always a power of

1. This is of rather dubious benefit in an accounting program, but it's used in several places so it needs to be implemented.

Parameters

figs	The number of digits to use for the numerator.

Returns

A GncRational with the specified number of digits in the numerator and the appropriate power-of-ten denominator.

Definition at line 140 of file gnc-rational.hpp.

    {
        auto new_denom(sigfigs_denom(figs));
        auto params = prepare_conversion(new_denom);
        if (new_denom == 0) //It had better not, but just in case...
            new_denom = 1;
        if (params.rem == 0)
            return GncRational(params.num, new_denom);
        return GncRational(round(params.num, params.den,
                                params.rem, RT2T<RT>()), new_denom);
    }

is_big()

bool GncRational::is_big ( ) const

noexcept

Report if either numerator or denominator are too big to fit in an int64_t.

Returns

true if either is too big.

Definition at line 58 of file gnc-rational.cpp.

{
    if (m_num.isBig() || m_den.isBig())
        return true;
    return false;
}

operator gnc_numeric()

GncRational::operator gnc_numeric ( ) const

noexcept

Conversion operator; use static_cast<gnc_numeric>(foo).

Definition at line 65 of file gnc-rational.cpp.

{
    if (!valid())
        return gnc_numeric_error(GNC_ERROR_OVERFLOW);
    try
    {
        return {static_cast<int64_t>(m_num), static_cast<int64_t>(m_den)};
    }
    catch (std::overflow_error&)
    {
        return gnc_numeric_error (GNC_ERROR_OVERFLOW);
    }
}

operator-()

GncRational GncRational::operator- ( ) const

noexcept

Make a new GncRational with the opposite sign.

Definition at line 80 of file gnc-rational.cpp.

{
    return GncRational(-m_num, m_den);
}

reduce()

GncRational GncRational::reduce

(

)

const

Return an equivalent fraction with all common factors between the numerator and the denominator removed.

Returns

reduced GncRational

Definition at line 181 of file gnc-rational.cpp.

{
    auto gcd = m_den.gcd(m_num);
    if (gcd.isNan() || gcd.isOverflow())
        throw std::overflow_error("Reduce failed, calculation of gcd overflowed.");
    return GncRational(m_num / gcd, m_den / gcd);
}

round_to_numeric()

GncRational GncRational::round_to_numeric

(

)

const

Round to fit an int64_t, finding the closest possible approximation.

Throws std::overflow_error if m_den is 1 and m_num is big.

Returns

rounded GncRational

Definition at line 190 of file gnc-rational.cpp.

{
    unsigned int ll_bits = GncInt128::legbits;
    if (m_num.isZero())
        return GncRational(); //Default constructor makes 0/1
    if (!(m_num.isBig() || m_den.isBig()))
        return *this;
    if (m_num.abs() > m_den)
    {
        auto quot(m_num / m_den);
        if (quot.isBig())
        {
            std::ostringstream msg;
            msg << " Cannot be represented as a "
                << "GncNumeric. Its integer value is too large.\n";
            throw std::overflow_error(msg.str());
        }
        GncRational new_v;
        while (new_v.num().isZero())
        {
            try
            {
                new_v = convert<RoundType::half_down>(m_den / (m_num.abs() >> ll_bits));
                if (new_v.is_big())
                {
                    --ll_bits;
                    new_v = GncRational();
                }
            }
            catch(const std::overflow_error& err)
            {
                --ll_bits;
            }
        }
        return new_v;
    }
    auto quot(m_den / m_num);
    if (quot.isBig())
        return GncRational(); //Smaller than can be represented as a GncNumeric
    GncRational new_v;
    while (new_v.num().isZero())
    {
        auto divisor = m_den >> ll_bits;
        if (m_num.isBig())
        {
            GncInt128 oldnum(m_num), num, rem;
            oldnum.div(divisor, num, rem);
            auto den = m_den / divisor;
            num += rem * 2 >= den ? 1 : 0;
            if (num.isBig() || den.isBig())
            {
                --ll_bits;
                continue;
            }
            GncRational new_rational(num, den);
            return new_rational;
        }
        new_v = convert<RoundType::half_down>(m_den / divisor);
        if (new_v.is_big())
        {
            --ll_bits;
            new_v = GncRational();
        }
    }
    return new_v;
}

valid()

bool GncRational::valid ( ) const

noexcept

Report if both members are valid numbers.

Returns

true if neither numerator nor denominator are Nan or Overflowed.

Definition at line 50 of file gnc-rational.cpp.

{
    if (m_num.valid() && m_den.valid())
        return true;
    return false;
}

---

The documentation for this class was generated from the following files:

• gnc-rational.hpp
• gnc-rational.cpp