GncNumeric Class Reference

The primary numeric class for representing amounts and values. More...

#include <gnc-numeric.hpp>

Public Member Functions
	GncNumeric ()
	Default constructor provides the zero value.
	GncNumeric (int64_t num, int64_t denom)
	Integer constructor. More...
	GncNumeric (GncRational rr)
	GncRational constructor. More...
	GncNumeric (gnc_numeric in)
	gnc_numeric constructor, used for interfacing old code. More...
	GncNumeric (double d)
	Double constructor. More...
	GncNumeric (const std::string &str, bool autoround=false)
	String constructor. More...
	GncNumeric (const GncNumeric &rhs)=default
	GncNumeric (GncNumeric &&rhs)=default
GncNumeric &	operator= (const GncNumeric &rhs)=default
GncNumeric &	operator= (GncNumeric &&rhs)=default
	operator gnc_numeric () const noexcept
	gnc_numeric conversion. More...
	operator double () const noexcept
	double conversion. More...
int64_t	num () const noexcept
	Accessor for numerator value.
int64_t	denom () const noexcept
	Accessor for denominator value.
GncNumeric	operator- () const noexcept
GncNumeric	inv () const noexcept
GncNumeric	abs () const noexcept
GncNumeric	reduce () const noexcept
	Return an equivalent fraction with all common factors between the numerator and the denominator removed. More...
template<RoundType RT>
GncNumeric	convert (int64_t new_denom) const
	Convert a GncNumeric to use a new denominator. More...
template<RoundType RT>
GncNumeric	convert_sigfigs (unsigned int figs) const
	Convert with the specified sigfigs. More...
std::string	to_string () const noexcept
	Return a string representation of the GncNumeric. More...
bool	is_decimal () const noexcept
GncNumeric	to_decimal (unsigned int max_places=17) const
	Convert the numeric to have a power-of-10 denominator if possible without rounding. More...
void	operator+= (GncNumeric b)
void	operator-= (GncNumeric b)
void	operator*= (GncNumeric b)
void	operator/= (GncNumeric b)
int	cmp (GncNumeric b)
int	cmp (int64_t b)

Detailed Description

The primary numeric class for representing amounts and values.

Calculations are generally performed in 128-bit (by converting to GncRational) and reducing the result. If the result would overflow a 64-bit representation then the GncNumeric(GncRational&) constructor will call GncRational::round_to_numeric() to get the value to fit. It will not raise an exception, so in the unlikely event that you need an error instead of rounding, use GncRational directly.

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.

Rounding Policy: GncNumeric provides a convert() member function that object amount and value setters (and only those functions!) should call to set a number which is represented in the commodity's SCU. Since SCUs are seldom 18 digits the convert may result in rounding, which will be performed in the method specified by the arguments passed to convert(). Overflows may result in internal rounding as described earlier.

Definition at line 59 of file gnc-numeric.hpp.

Constructor & Destructor Documentation

GncNumeric() [1/5]

GncNumeric::GncNumeric ( int64_t  num, int64_t  denom  )

inline

Integer constructor.

Unfortunately specifying a default for denom causes ambiguity errors with the other single-argument constructors on older versions of gcc, so one must always specify both arguments.

Parameters

num	The Numerator
denom	The Denominator

Definition at line 76 of file gnc-numeric.hpp.

                                           :
        m_num(num), m_den(denom) {
        if (denom == 0)
            throw std::invalid_argument("Attempt to construct a GncNumeric with a 0 denominator.");
    }

GncNumeric() [2/5]

GncNumeric::GncNumeric

(

GncRational

rr

)

GncRational constructor.

This constructor will round rr's GncInt128s to fit into the int64_t members using RoundType::half-down.

Parameters

rr	A GncRational.

Definition at line 70 of file gnc-numeric.cpp.

{
    /* Can't use isValid here because we want to throw different exceptions. */
    if (rr.num().isNan() || rr.denom().isNan())
        throw std::underflow_error("Operation resulted in NaN.");
    if (rr.num().isOverflow() || rr.denom().isOverflow())
        throw std::overflow_error("Operation overflowed a 128-bit int.");
    if (rr.num().isBig() || rr.denom().isBig())
    {
        GncRational reduced(rr.reduce());
        rr = reduced.round_to_numeric(); // A no-op if it's already small.
    }
    m_num = static_cast<int64_t>(rr.num());
    m_den = static_cast<int64_t>(rr.denom());
}

GncNumeric() [3/5]

GncNumeric::GncNumeric ( gnc_numeric  in )

inline

gnc_numeric constructor, used for interfacing old code.

This function should not be used outside of gnc-numeric.cpp.

Parameters

in	A gnc_numeric.

Definition at line 96 of file gnc-numeric.hpp.

                               : m_num(in.num), m_den(in.denom)
    {
        if (in.denom == 0)
            throw std::invalid_argument("Attempt to construct a GncNumeric with a 0 denominator.");
        /* gnc_numeric has a dumb convention that a negative denominator means
         * to multiply the numerator by the denominator instead of dividing.
         */
        if (in.denom < 0)
        {
            m_num *= -in.denom;
            m_den = 1;
        }
    }

GncNumeric() [4/5]

GncNumeric::GncNumeric

(

double

d

)

Double constructor.

Parameters

d	The double to be converted. In order to fit in an int64_t, its absolute value must be < 1e18; if its absolute value is < 1e-18 it will be represented as 0, though for practical purposes nearly all commodities will round to zero at 1e-9 or larger.

Definition at line 86 of file gnc-numeric.cpp.

                               : m_num(0), m_den(1)
{
    static uint64_t max_leg_value{INT64_C(1000000000000000000)};
    if (std::isnan(d) || fabs(d) > max_leg_value)
    {
        std::ostringstream msg;
        msg << "Unable to construct a GncNumeric from " << d << ".\n";
        throw std::invalid_argument(msg.str());
    }
    constexpr auto max_num = static_cast<double>(INT64_MAX);
    auto logval = log10(fabs(d));
    int64_t den;
    uint8_t den_digits;
    if (logval > 0.0)
        den_digits = (max_leg_digits + 1) - static_cast<int>(floor(logval));
    else
        den_digits = max_leg_digits;
    den = powten(den_digits);
    auto num_d = static_cast<double>(den) * d;
    while (fabs(num_d) > max_num && den_digits > 1)
    {
        den = powten(--den_digits);
        num_d = static_cast<double>(den) * d;
    }
    auto num = static_cast<int64_t>(floor(num_d));

    if (num == 0)
        return;
    GncNumeric q(num, den);
    auto r = q.reduce();
    m_num = r.num();
    m_den = r.denom();
}

GncNumeric() [5/5]

GncNumeric::GncNumeric	(	const std::string &	str,
		bool	autoround = false
	)

String constructor.

Accepts integer values in decimal and hexadecimal. Does not accept thousands separators. If the string contains a '/' it is taken to separate the numerator and denominator; if it contains either a '.' or a ',' it is taken as a decimal point and the integers on either side will be combined and a denominator will be the appropriate power of 10. If neither is present the number will be treated as an integer and m_den will be set to 1.

Whitespace around a '/' is ignored. A correctly-formatted number will be extracted from a larger string.

Numbers that cannot be represented with int64_ts will throw std::out_of_range unless a decimal point is found (see above). A 0 denominator will cause the constructor to throw std::underflow_error. An empty string or one which contains no recognizable number will result in std::invalid_argument.

Definition at line 244 of file gnc-numeric.cpp.

                                                           {
    static const std::string maybe_sign ("(-?)");
    static const std::string opt_signed_int("(-?[0-9]*)");
    static const std::string unsigned_int("([0-9]+)");
    static const std::string hex_frag("(0[xX][A-Fa-f0-9]+)");
    static const std::string slash("[ \\t]*/[ \\t]*");
    static const std::string whitespace("[ \\t]+");
    /* The llvm standard C++ library refused to recognize the - in the
     * opt_signed_int pattern with the default ECMAScript syntax so we use the
     * awk syntax.
     */
    static const regex numeral(opt_signed_int);
    static const regex hex(hex_frag);
    static const regex numeral_rational(opt_signed_int + slash + unsigned_int);
    static const regex integer_and_fraction(maybe_sign + unsigned_int + whitespace + unsigned_int + slash + unsigned_int);
    static const regex hex_rational(hex_frag + slash + hex_frag);
    static const regex hex_over_num(hex_frag + slash + unsigned_int);
    static const regex num_over_hex(opt_signed_int + slash + hex_frag);
    static const regex decimal(opt_signed_int + "[.,]" + unsigned_int);
    static const regex scientific("(?:(-?[0-9]+[.,]?)|(-?[0-9]*)[.,]([0-9]+))[Ee](-?[0-9]+)");
    static const regex has_hex_prefix(".*0[xX]$");
    smatch m, x;
    /* The order of testing the regexes is from the more restrictve to the less
     * restrictive, as less-restrictive ones will match  patterns that would also
     * match the more-restrictive and so invoke the wrong construction.
     */
    if (str.empty())
        throw std::invalid_argument(
            "Can't construct a GncNumeric from an empty string.");
    if (auto res = fast_numeral_rational (str.c_str()))
    {
        m_num = res->num;
        m_den = res->denom;
        return;
    }
    if (regex_search(str, m, hex_rational))
    {
        GncNumeric n(stoll(m[1].str(), nullptr, 16),
                     stoll(m[2].str(), nullptr, 16));

        m_num = n.num();
        m_den = n.denom();
        return;
    }
    if (regex_search(str, m, hex_over_num))
    {
        GncNumeric n(stoll(m[1].str(), nullptr, 16), stoll(m[2].str()));
        m_num = n.num();
        m_den = n.denom();
        return;
    }
    if (regex_search(str, m, num_over_hex))
    {
        GncNumeric n(stoll(m[1].str()), stoll(m[2].str(), nullptr, 16));
        m_num = n.num();
        m_den = n.denom();
        return;
    }
    if (regex_search(str, m, integer_and_fraction))
    {
        GncNumeric n(stoll(m[3].str()), stoll(m[4].str()));
        n += stoll(m[2].str());
        m_num = m[1].str().empty() ? n.num() : -n.num();
        m_den = n.denom();
        return;
    }
    if (regex_search(str, m, numeral_rational))
    {
        GncNumeric n(stoll(m[1].str()), stoll(m[2].str()));
        m_num = n.num();
        m_den = n.denom();
        return;
    }
    if (regex_search(str, m, scientific) && ! regex_match(m.prefix().str(), x,  has_hex_prefix))
    {
        auto [num, denom] =
            reduce_number_pair(numeric_from_scientific_match(m),
                                   str, autoround);
        m_num = num;
        m_den = denom;
        return;
    }
    if (regex_search(str, m, decimal))
    {
        std::string integer{m[1].matched ? m[1].str() : ""};
        std::string decimal{m[2].matched ? m[2].str() : ""};
        auto [num, denom] =
            reduce_number_pair(numeric_from_decimal_match(integer, decimal),
                               str, autoround);
        m_num = num;
        m_den = denom;
        return;
    }
    if (regex_search(str, m, hex))
    {
        GncNumeric n(stoll(m[1].str(), nullptr, 16), INT64_C(1));
        m_num = n.num();
        m_den = n.denom();
        return;
    }
    if (regex_search(str, m, numeral))
    {
        GncNumeric n(stoll(m[1].str()), INT64_C(1));
        m_num = n.num();
        m_den = n.denom();
        return;
    }
    std::ostringstream errmsg;
    errmsg << "String " << str << " contains no recognizable numeric value.";
    throw std::invalid_argument(errmsg.str());
}

Member Function Documentation

abs()

GncNumeric GncNumeric::abs ( ) const

noexcept

Returns

-this if this < 0 else this.

Definition at line 385 of file gnc-numeric.cpp.

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

convert()

template<RoundType RT>

GncNumeric GncNumeric::convert ( int64_t  new_denom ) const

inline

Convert a GncNumeric 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 GncNumeric having the requested denominator.

Definition at line 192 of file gnc-numeric.hpp.

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

convert_sigfigs()

template<RoundType RT>

GncNumeric GncNumeric::convert_sigfigs ( unsigned int  figs ) const

inline

Convert with the specified sigfigs.

The resulting denominator depends on the value of the GncNumeric, 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 GncNumeric with the specified number of digits in the numerator and the appropriate power-of-ten denominator.

Definition at line 215 of file gnc-numeric.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 GncNumeric(params.num, new_denom);
        return GncNumeric(round(params.num, params.den,
                                params.rem, RT2T<RT>()), new_denom);
    }

inv()

GncNumeric GncNumeric::inv ( ) const

noexcept

Returns

0 if this == 0 else 1/this.

Definition at line 375 of file gnc-numeric.cpp.

{
    if (m_num == 0)
        return *this;
    if (m_num < 0)
        return GncNumeric(-m_den, -m_num);
    return GncNumeric(m_den, m_num);
}

is_decimal()

bool GncNumeric::is_decimal ( ) const

noexcept

Returns

true if the denominator is a power of ten, false otherwise.

Definition at line 449 of file gnc-numeric.cpp.

{
    for (unsigned pwr = 0; pwr < max_leg_digits && m_den >= pten[pwr]; ++pwr)
    {
        if (m_den == pten[pwr])
            return true;
        if (m_den % pten[pwr])
            return false;
    }
    return false;
}

operator double()

GncNumeric::operator double ( ) const

noexcept

double conversion.

Use static_cast<double>(foo)

Definition at line 361 of file gnc-numeric.cpp.

{
    return static_cast<double>(m_num) / static_cast<double>(m_den);
}

operator gnc_numeric()

GncNumeric::operator gnc_numeric ( ) const

noexcept

gnc_numeric conversion.

Use static_cast<gnc_numeric>(foo)

Definition at line 356 of file gnc-numeric.cpp.

{
    return {m_num, m_den};
}

operator-()

GncNumeric GncNumeric::operator- ( ) const

noexcept

Returns

A GncNumeric with the opposite sign.

Definition at line 367 of file gnc-numeric.cpp.

{
    GncNumeric b(*this);
    b.m_num = - b.m_num;
    return b;
}

reduce()

GncNumeric GncNumeric::reduce ( ) const

noexcept

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

Returns

reduced GncNumeric

Definition at line 393 of file gnc-numeric.cpp.

{
    return static_cast<GncNumeric>(GncRational(*this).reduce());
}

to_decimal()

GncNumeric GncNumeric::to_decimal

(

unsigned int

max_places = 17

)

const

Convert the numeric to have a power-of-10 denominator if possible without rounding.

Throws a std::range_error on failure; the message will explain the details.

Parameters

max_places

exponent of the largest permissible denominator.

Returns

A GncNumeric value with the new denominator.

Definition at line 462 of file gnc-numeric.cpp.

{
    if (max_places > max_leg_digits)
        max_places = max_leg_digits;

    if (m_num == 0)
    return GncNumeric();

    if (is_decimal())
    {
        if (m_num == 0 || m_den < powten(max_places))
            return *this; // Nothing to do.
        /* See if we can reduce m_num to fit in max_places */
        auto excess = m_den / powten(max_places);
        if (m_num % excess)
        {
            std::ostringstream msg;
            msg << "GncNumeric " << *this
                << " could not be represented in " << max_places
                << " decimal places without rounding.\n";
            throw std::range_error(msg.str());
        }
        return GncNumeric(m_num / excess, powten(max_places));
    }
    GncRational rr(*this);
    rr = rr.convert<RoundType::never>(powten(max_places)); //May throw
    /* rr might have gotten reduced a bit too much; if so, put it back: */
    unsigned int pwr{1};
    for (; pwr <= max_places && !(rr.denom() % powten(pwr)); ++pwr);
    auto reduce_to = powten(pwr);
    GncInt128 rr_num(rr.num()), rr_den(rr.denom());
    if (rr_den % reduce_to)
    {
        auto factor(reduce_to / rr.denom());
        rr_num *= factor;
        rr_den *= factor;
    }
    while (!rr_num.isZero() && rr_num > 9 && rr_den > 9 && rr_num % 10 == 0)
    {
        rr_num /= 10;
        rr_den /= 10;
    }
    try
    {
        /* Construct from the parts to avoid the GncRational constructor's
         * automatic rounding.
         */
        return {static_cast<int64_t>(rr_num), static_cast<int64_t>(rr_den)};
    }
    catch (const std::invalid_argument& err)
    {
        std::ostringstream msg;
        msg << "GncNumeric " << *this
            << " could not be represented as a decimal without rounding.\n";
        throw std::range_error(msg.str());
    }
    catch (const std::overflow_error& err)
    {
        std::ostringstream msg;
        msg << "GncNumeric " << *this
            << " overflows when attempting to convert it to decimal.\n";
        throw std::range_error(msg.str());
    }
    catch (const std::underflow_error& err)
    {
        std::ostringstream msg;
        msg << "GncNumeric " << *this
            << " underflows when attempting to convert it to decimal.\n";
        throw std::range_error(msg.str());
    }
}

to_string()

std::string GncNumeric::to_string ( ) const

noexcept

Return a string representation of the GncNumeric.

See operator<< for details.

Definition at line 441 of file gnc-numeric.cpp.

{
    std::ostringstream out;
    out << *this;
    return out.str();
}

---

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

• gnc-numeric.hpp
• gnc-numeric.cpp