Numeric: Rational Number Handling w/ Rounding Error Control

The 'Numeric' functions provide a way of working with rational numbers while maintaining strict control over rounding errors when adding rationals with different denominators. More...

Files
file	gnc-numeric.h
	An exact-rational-number library for gnucash.

Data Structures
struct	gnc_numeric
	An rational-number type. More...

Variables
gint64	gnc_numeric::num
gint64	gnc_numeric::denom

Arguments Standard Arguments to most functions
Most of the gnc_numeric arithmetic functions take two arguments in addition to their numeric args: 'denom', which is the denominator to use in the output gnc_numeric object, and 'how'. which describes how the arithmetic result is to be converted to that denominator. This combination of output denominator and rounding policy allows the results of financial and other rational computations to be properly rounded to the appropriate units. Watch out: You must specify a rounding policy such as GNC_HOW_RND_NEVER, otherwise the fractional part of the input value might silently get discarded! Valid values for denom are: GNC_DENOM_AUTO – compute denominator exactly integer n – Force the denominator of the result to be this integer GNC_DENOM_RECIPROCAL – Use 1/n as the denominator (???huh???) Valid values for 'how' are bitwise combinations of zero or one "rounding instructions" with zero or one "denominator types". Valid rounding instructions are: GNC_HOW_RND_FLOOR GNC_HOW_RND_CEIL GNC_HOW_RND_TRUNC GNC_HOW_RND_PROMOTE GNC_HOW_RND_ROUND_HALF_DOWN GNC_HOW_RND_ROUND_HALF_UP GNC_HOW_RND_ROUND GNC_HOW_RND_NEVER The denominator type specifies how to compute a denominator if GNC_DENOM_AUTO is specified as the 'denom'. Valid denominator types are: GNC_HOW_DENOM_EXACT GNC_HOW_DENOM_REDUCE GNC_HOW_DENOM_LCD GNC_HOW_DENOM_FIXED GNC_HOW_DENOM_SIGFIGS(N) To use traditional rational-number operational semantics (all results are exact and are reduced to relatively-prime fractions) pass the argument GNC_DENOM_AUTO as 'denom' and GNC_HOW_DENOM_REDUCE| GNC_HOW_RND_NEVER as 'how'. To enforce strict financial semantics (such that all operands must have the same denominator as each other and as the result), use GNC_DENOM_AUTO as 'denom' and GNC_HOW_DENOM_FIXED | GNC_HOW_RND_NEVER as 'how'.
enum	{   GNC_HOW_RND_FLOOR = 0x01 , GNC_HOW_RND_CEIL = 0x02 , GNC_HOW_RND_TRUNC = 0x03 , GNC_HOW_RND_PROMOTE = 0x04 ,   GNC_HOW_RND_ROUND_HALF_DOWN = 0x05 , GNC_HOW_RND_ROUND_HALF_UP = 0x06 , GNC_HOW_RND_ROUND = 0x07 , GNC_HOW_RND_NEVER = 0x08 }
	Rounding/Truncation modes for operations. More...
enum	{   GNC_HOW_DENOM_EXACT = 0x10 , GNC_HOW_DENOM_REDUCE = 0x20 , GNC_HOW_DENOM_LCD = 0x30 , GNC_HOW_DENOM_FIXED = 0x40 ,   GNC_HOW_DENOM_SIGFIG = 0x50 }
	How to compute a denominator, or'ed into the "how" field. More...
enum	GNCNumericErrorCode {   GNC_ERROR_OK = 0 , GNC_ERROR_ARG = -1 , GNC_ERROR_OVERFLOW = -2 , GNC_ERROR_DENOM_DIFF = -3 ,   GNC_ERROR_REMAINDER = -4 }
	Error codes. More...
#define	GNC_NUMERIC_RND_MASK   0x0000000f
	bitmasks for HOW flags.
#define	GNC_NUMERIC_DENOM_MASK   0x000000f0
#define	GNC_NUMERIC_SIGFIGS_MASK   0x0000ff00
#define	GNC_HOW_DENOM_SIGFIGS(n)   ( ((( n ) & 0xff) << 8) | GNC_HOW_DENOM_SIGFIG)
	Build a 'how' value that will generate a denominator that will keep at least n significant figures in the result.
#define	GNC_HOW_GET_SIGFIGS(a)   ( (( a ) & 0xff00 ) >> 8)
#define	GNC_DENOM_AUTO   0
	Values that can be passed as the 'denom' argument.

Constructors
gnc_numeric	double_to_gnc_numeric (double n, gint64 denom, gint how)
	Convert a floating-point number to a gnc_numeric.
gnc_numeric	gnc_numeric_from_string (const gchar *str)
	Read a gnc_numeric from str, skipping any leading whitespace.
gnc_numeric	gnc_numeric_error (GNCNumericErrorCode error_code)
	Create a gnc_numeric object that signals the error condition noted by error_code, rather than a number.
const char *	gnc_numeric_errorCode_to_string (GNCNumericErrorCode error_code)
	Returns a string representation of the given GNCNumericErrorCode.

Value Accessors
gdouble	gnc_numeric_to_double (gnc_numeric n)
	Convert numeric to floating-point value.
gchar *	gnc_numeric_to_string (gnc_numeric n)
	Convert to string.
gchar *	gnc_num_dbg_to_string (gnc_numeric n)
	Convert to string.

Comparisons and Predicates
GNCNumericErrorCode	gnc_numeric_check (gnc_numeric a)
	Check for error signal in value.
gint	gnc_numeric_compare (gnc_numeric a, gnc_numeric b)
	Returns 1 if a>b, -1 if b>a, 0 if a == b
gboolean	gnc_numeric_zero_p (gnc_numeric a)
	Returns 1 if the given gnc_numeric is 0 (zero), else returns 0.
gboolean	gnc_numeric_negative_p (gnc_numeric a)
	Returns 1 if a < 0, otherwise returns 0.
gboolean	gnc_numeric_positive_p (gnc_numeric a)
	Returns 1 if a > 0, otherwise returns 0.
gboolean	gnc_numeric_eq (gnc_numeric a, gnc_numeric b)
	Equivalence predicate: Returns TRUE (1) if a and b are exactly the same (have the same numerator and denominator)
gboolean	gnc_numeric_equal (gnc_numeric a, gnc_numeric b)
	Equivalence predicate: Returns TRUE (1) if a and b represent the same number.
gint	gnc_numeric_same (gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
	Equivalence predicate: Convert both a and b to denom using the specified DENOM and method HOW, and compare numerators the results using gnc_numeric_equal.

Arithmetic Operations
gnc_numeric	gnc_numeric_add (gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
	Return a+b.
gnc_numeric	gnc_numeric_sub (gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
	Return a-b.
gnc_numeric	gnc_numeric_mul (gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
	Multiply a times b, returning the product.
gnc_numeric	gnc_numeric_div (gnc_numeric x, gnc_numeric y, gint64 denom, gint how)
	Division.
gnc_numeric	gnc_numeric_neg (gnc_numeric a)
	Returns a newly created gnc_numeric that is the negative of the given gnc_numeric value.
gnc_numeric	gnc_numeric_abs (gnc_numeric a)
	Returns a newly created gnc_numeric that is the absolute value of the given gnc_numeric value.

Change Denominator
gnc_numeric	gnc_numeric_convert (gnc_numeric n, gint64 denom, gint how)
	Change the denominator of a gnc_numeric value to the specified denominator under standard arguments 'denom' and 'how'.
gnc_numeric	gnc_numeric_reduce (gnc_numeric n)
	Return input after reducing it by Greater Common Factor (GCF) elimination.
gboolean	gnc_numeric_to_decimal (gnc_numeric *a, guint8 *max_decimal_places)
	Attempt to convert the denominator to an exact power of ten without rounding.
gnc_numeric	gnc_numeric_invert (gnc_numeric num)
	Invert a gnc_numeric.

GValue
GType	gnc_numeric_get_type (void)
#define	GNC_TYPE_NUMERIC   (gnc_numeric_get_type ())

Detailed Description

The 'Numeric' functions provide a way of working with rational numbers while maintaining strict control over rounding errors when adding rationals with different denominators.

The Numeric class is primarily used for working with monetary amounts, where the denominator typically represents the smallest fraction of the currency (e.g. pennies, centimes). The numeric class can handle any fraction (e.g. twelfth's) and is not limited to fractions that are powers of ten.

A 'Numeric' value represents a number in rational form, with a 64-bit integer as numerator and denominator. Rationals are ideal for many uses, such as performing exact, roundoff-error-free addition and multiplication, but 64-bit rationals do not have the dynamic range of floating point numbers.

Macro Definition Documentation

GNC_DENOM_AUTO

#define GNC_DENOM_AUTO   0

Values that can be passed as the 'denom' argument.

The include a positive number n to be used as the denominator of the output value. Other possibilities include the list below: Compute an appropriate denominator automatically. Flags in the 'how' argument will specify how to compute the denominator.

Definition at line 245 of file gnc-numeric.h.

GNC_HOW_DENOM_SIGFIGS

#define GNC_HOW_DENOM_SIGFIGS

(

n

)

( ((( n ) & 0xff) << 8) | GNC_HOW_DENOM_SIGFIG)

Build a 'how' value that will generate a denominator that will keep at least n significant figures in the result.

Definition at line 217 of file gnc-numeric.h.

GNC_HOW_GET_SIGFIGS

#define GNC_HOW_GET_SIGFIGS

(

a

)

( (( a ) & 0xff00 ) >> 8)

Definition at line 218 of file gnc-numeric.h.

GNC_NUMERIC_DENOM_MASK

#define GNC_NUMERIC_DENOM_MASK   0x000000f0

Definition at line 127 of file gnc-numeric.h.

GNC_NUMERIC_RND_MASK

#define GNC_NUMERIC_RND_MASK   0x0000000f

bitmasks for HOW flags.

bits 8-15 of 'how' are reserved for the number of significant digits to use in the output with GNC_HOW_DENOM_SIGFIG

Definition at line 126 of file gnc-numeric.h.

GNC_NUMERIC_SIGFIGS_MASK

#define GNC_NUMERIC_SIGFIGS_MASK   0x0000ff00

Definition at line 128 of file gnc-numeric.h.

GNC_TYPE_NUMERIC

#define GNC_TYPE_NUMERIC   (gnc_numeric_get_type ())

Definition at line 489 of file gnc-numeric.h.

Enumeration Type Documentation

anonymous enum

anonymous enum

Rounding/Truncation modes for operations.

Rounding instructions control how fractional parts in the specified denominator affect the result. For example, if a computed result is "3/4" but the specified denominator for the return value is 2, should the return value be "1/2" or "2/2"?

Watch out: You must specify a rounding policy such as GNC_HOW_RND_NEVER, otherwise the fractional part of the input value might silently get discarded!

Possible rounding instructions are:

Enumerator
GNC_HOW_RND_FLOOR	Round toward -infinity.
GNC_HOW_RND_CEIL	Round toward +infinity.
GNC_HOW_RND_TRUNC	Truncate fractions (round toward zero)
GNC_HOW_RND_PROMOTE	Promote fractions (round away from zero)
GNC_HOW_RND_ROUND_HALF_DOWN	Round to the nearest integer, rounding toward zero when there are two equidistant nearest integers.
GNC_HOW_RND_ROUND_HALF_UP	Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers.
GNC_HOW_RND_ROUND	Use unbiased ("banker's") rounding. This rounds to the nearest integer, and to the nearest even integer when there are two equidistant nearest integers. This is generally the one you should use for financial quantities.
GNC_HOW_RND_NEVER	Never round at all, and signal an error if there is a fractional result in a computation.

Definition at line 143 of file gnc-numeric.h.

{
    GNC_HOW_RND_FLOOR            = 0x01,
 
    GNC_HOW_RND_CEIL             = 0x02,
 
    GNC_HOW_RND_TRUNC            = 0x03,
 
    GNC_HOW_RND_PROMOTE          = 0x04,
 
    GNC_HOW_RND_ROUND_HALF_DOWN  = 0x05,
 
    GNC_HOW_RND_ROUND_HALF_UP    = 0x06,
 
    GNC_HOW_RND_ROUND            = 0x07,
 
    GNC_HOW_RND_NEVER            = 0x08
};

anonymous enum

anonymous enum

How to compute a denominator, or'ed into the "how" field.

Enumerator
GNC_HOW_DENOM_EXACT	Use any denominator which gives an exactly correct ratio of numerator to denominator. Use EXACT when you do not wish to lose any information in the result but also do not want to spend any time finding the "best" denominator.
GNC_HOW_DENOM_REDUCE	Reduce the result value by common factor elimination, using the smallest possible value for the denominator that keeps the correct ratio. The numerator and denominator of the result are relatively prime.
GNC_HOW_DENOM_LCD	Find the least common multiple of the arguments' denominators and use that as the denominator of the result.
GNC_HOW_DENOM_FIXED	All arguments are required to have the same denominator, that denominator is to be used in the output, and an error is to be signaled if any argument has a different denominator.
GNC_HOW_DENOM_SIGFIG	Round to the number of significant figures given in the rounding instructions by the GNC_HOW_DENOM_SIGFIGS () macro.

Definition at line 181 of file gnc-numeric.h.

{
    GNC_HOW_DENOM_EXACT  = 0x10,
 
    GNC_HOW_DENOM_REDUCE = 0x20,
 
    GNC_HOW_DENOM_LCD    = 0x30,
 
    GNC_HOW_DENOM_FIXED  = 0x40,
 
    GNC_HOW_DENOM_SIGFIG = 0x50
};

GNCNumericErrorCode

enum GNCNumericErrorCode

Error codes.

Enumerator
GNC_ERROR_OK	No error.
GNC_ERROR_ARG	Argument is not a valid number.
GNC_ERROR_OVERFLOW	Intermediate result overflow.
GNC_ERROR_DENOM_DIFF	GNC_HOW_DENOM_FIXED was specified, but argument denominators differed.
GNC_ERROR_REMAINDER	GNC_HOW_RND_NEVER was specified, but the result could not be converted to the desired denominator without a remainder.

Definition at line 221 of file gnc-numeric.h.

{
    GNC_ERROR_OK         =  0,   
    GNC_ERROR_ARG        = -1,   
    GNC_ERROR_OVERFLOW   = -2,   
    GNC_ERROR_DENOM_DIFF = -3,
 
    GNC_ERROR_REMAINDER  = -4
} GNCNumericErrorCode;

Function Documentation

double_to_gnc_numeric()

gnc_numeric double_to_gnc_numeric	(	double	n,
		gint64	denom,
		gint	how
	)

Convert a floating-point number to a gnc_numeric.

Both 'denom' and 'how' are used as in arithmetic.

See also

Arguments

Parameters

n	The double value that is converted into a gnc_numeric
denom	The denominator of the gnc_numeric return value. If the 'how' argument contains the GNC_HOW_DENOM_SIGFIG flag, this value will be ignored. If GNC_DENOM_AUTO is given an appropriate power of ten will be used for the denominator (it may be reduced by rounding if appropriate).
how	Describes the rounding policy and output denominator. Watch out: You must specify a rounding policy such as GNC_HOW_RND_NEVER, otherwise the fractional part of the input value is silently discarded! Common values for 'how' are (GNC_HOW_DENOM_REDUCE|GNC_HOW_RND_NEVER) or (GNC_HOW_DENOM_FIXED|GNC_HOW_RND_NEVER).

Returns

The newly created gnc_numeric rational value.

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

{
    try
    {
        GncNumeric an(in);
        return convert(an, denom, how);
    }
    catch (const std::overflow_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_OVERFLOW);
    }
    catch (const std::invalid_argument& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_ARG);
    }
    catch (const std::underflow_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_ARG);
    }
    catch (const std::domain_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_REMAINDER);
    }
}

gnc_num_dbg_to_string()

gchar * gnc_num_dbg_to_string

(

gnc_numeric

n

)

Convert to string.

Uses a static, non-thread-safe buffer. For internal use only.

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

{
    static char buff[1000];
    static char *p = buff;
    static const size_t size = 50;
    int64_t tmpnum = n.num;
    int64_t tmpdenom = n.denom;
 
    p += size;
    if ((size_t)(p - buff) > (sizeof(buff) - size))
        p = buff;
 
    snprintf(p, size, "%" PRId64 "/%" PRId64, tmpnum, tmpdenom);
 
    return p;
}

gnc_numeric_abs()

gnc_numeric gnc_numeric_abs

(

gnc_numeric

a

)

Returns a newly created gnc_numeric that is the absolute value of the given gnc_numeric value.

For a given gnc_numeric "a/b" the returned value is "|a/b|".

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

{
    if (gnc_numeric_check(a))
    {
        return gnc_numeric_error(GNC_ERROR_ARG);
    }
    return gnc_numeric_create(ABS(a.num), a.denom);
}

gnc_numeric_add()

gnc_numeric gnc_numeric_add	(	gnc_numeric	a,
		gnc_numeric	b,
		gint64	denom,
		gint	how
	)

Return a+b.

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

{
    if (gnc_numeric_check(a) || gnc_numeric_check(b))
    {
        return gnc_numeric_error(GNC_ERROR_ARG);
    }
    try
    {
        denom = denom_lcd(a, b, denom, how);
        if ((how & GNC_NUMERIC_DENOM_MASK) != GNC_HOW_DENOM_EXACT)
        {
            GncNumeric an (a), bn (b);
            GncNumeric sum = an + bn;
            return static_cast<gnc_numeric>(convert(sum, denom, how));
        }
        GncRational ar(a), br(b);
        auto sum = ar + br;
        if (denom == GNC_DENOM_AUTO &&
            (how & GNC_NUMERIC_RND_MASK) != GNC_HOW_RND_NEVER)
            return static_cast<gnc_numeric>(sum.round_to_numeric());
        sum = convert(sum, denom, how);
        if (sum.is_big() || !sum.valid())
            return gnc_numeric_error(GNC_ERROR_OVERFLOW);
        return static_cast<gnc_numeric>(sum);
    }
    catch (const std::overflow_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_OVERFLOW);
    }
    catch (const std::invalid_argument& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_ARG);
    }
    catch (const std::underflow_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_OVERFLOW);
    }
    catch (const std::domain_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_REMAINDER);
    }
}

gnc_numeric_check()

GNCNumericErrorCode gnc_numeric_check

(

gnc_numeric

a

)

Check for error signal in value.

Returns GNC_ERROR_OK (==0) if the number appears to be valid, otherwise it returns the type of error. Error values always have a denominator of zero.

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

{
    if (G_LIKELY(in.denom != 0))
    {
        return GNC_ERROR_OK;
    }
    else if (in.num)
    {
        if ((0 < in.num) || (-4 > in.num))
        {
            in.num = (gint64) GNC_ERROR_OVERFLOW;
        }
        return (GNCNumericErrorCode) in.num;
    }
    else
    {
        return GNC_ERROR_ARG;
    }
}

gnc_numeric_compare()

gint gnc_numeric_compare	(	gnc_numeric	a,
		gnc_numeric	b
	)

Returns 1 if a>b, -1 if b>a, 0 if a == b

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

{
    if (gnc_numeric_check(a) || gnc_numeric_check(b))
    {
        return 0;
    }
 
    if (a.denom == b.denom)
    {
        if (a.num == b.num) return 0;
        if (a.num > b.num) return 1;
        return -1;
    }
 
    GncNumeric an (a), bn (b);
 
    return an.cmp(bn);
}

gnc_numeric_div()

gnc_numeric gnc_numeric_div	(	gnc_numeric	x,
		gnc_numeric	y,
		gint64	denom,
		gint	how
	)

Division.

Note that division can overflow, in the following sense: if we write x=a/b and y=c/d then x/y = (a*d)/(b*c) If, after eliminating all common factors between the numerator (a*d) and the denominator (b*c), then if either the numerator and/or the denominator are still greater than 2^63, then the division has overflowed.

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

{
    if (gnc_numeric_check(a) || gnc_numeric_check(b))
    {
        return gnc_numeric_error(GNC_ERROR_ARG);
    }
    try
    {
        denom = denom_lcd(a, b, denom, how);
        if ((how & GNC_NUMERIC_DENOM_MASK) != GNC_HOW_DENOM_EXACT)
        {
            GncNumeric an (a), bn (b);
            auto quot = an / bn;
            return static_cast<gnc_numeric>(convert(quot, denom, how));
        }
        GncRational ar(a), br(b);
        auto quot = ar / br;
        if (denom == GNC_DENOM_AUTO &&
            (how & GNC_NUMERIC_RND_MASK) != GNC_HOW_RND_NEVER)
            return static_cast<gnc_numeric>(quot.round_to_numeric());
        quot =  static_cast<gnc_numeric>(convert(quot, denom, how));
        if (quot.is_big() || !quot.valid())
            return gnc_numeric_error(GNC_ERROR_OVERFLOW);
        return static_cast<gnc_numeric>(quot);
    }
    catch (const std::overflow_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_OVERFLOW);
    }
    catch (const std::invalid_argument& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_ARG);
    }
    catch (const std::underflow_error& err) //Divide by zero
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_OVERFLOW);
    }
    catch (const std::domain_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_REMAINDER);
    }
}

gnc_numeric_eq()

gboolean gnc_numeric_eq	(	gnc_numeric	a,
		gnc_numeric	b
	)

Equivalence predicate: Returns TRUE (1) if a and b are exactly the same (have the same numerator and denominator)

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

{
    return ((a.num == b.num) && (a.denom == b.denom));
}

gnc_numeric_equal()

gboolean gnc_numeric_equal	(	gnc_numeric	a,
		gnc_numeric	b
	)

Equivalence predicate: Returns TRUE (1) if a and b represent the same number.

That is, return TRUE if the ratios, when reduced by eliminating common factors, are identical.

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

{
    if (gnc_numeric_check(a))
    {
        /* a is not a valid number, check b */
        if (gnc_numeric_check(b))
            /* Both invalid, consider them equal */
            return TRUE;
        else
            /* a invalid, b valid */
            return FALSE;
    }
    if (gnc_numeric_check(b))
        /* a valid, b invalid */
        return FALSE;
 
    return gnc_numeric_compare (a, b) == 0;
}

gnc_numeric_error()

gnc_numeric gnc_numeric_error

(

GNCNumericErrorCode

error_code

)

Create a gnc_numeric object that signals the error condition noted by error_code, rather than a number.

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

{
    return gnc_numeric_create(error_code, 0LL);
}

gnc_numeric_errorCode_to_string()

const char * gnc_numeric_errorCode_to_string

(

GNCNumericErrorCode

error_code

)

Returns a string representation of the given GNCNumericErrorCode.

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

{
    switch (error_code)
    {
    case GNC_ERROR_OK:
        return "GNC_ERROR_OK";
    case GNC_ERROR_ARG:
        return "GNC_ERROR_ARG";
    case GNC_ERROR_OVERFLOW:
        return "GNC_ERROR_OVERFLOW";
    case GNC_ERROR_DENOM_DIFF:
        return "GNC_ERROR_DENOM_DIFF";
    case GNC_ERROR_REMAINDER:
        return "GNC_ERROR_REMAINDER";
    default:
        return "<unknown>";
    }
}

gnc_numeric_from_string()

gnc_numeric gnc_numeric_from_string

(

const gchar *

str

)

Read a gnc_numeric from str, skipping any leading whitespace.

Returns the resulting gnc_numeric. Return GNC_ERROR_ARG on error.

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

{
    if (!str)
        return gnc_numeric_error (GNC_ERROR_ARG);
 
    // the default gnc_numeric string format is "num/denom", whereby
    // the denom must be >= 1. this speedily parses it. this also
    // parses "num" as num/1.
    if (auto res = fast_numeral_rational (str))
        return *res;
 
    try
    {
        return GncNumeric (str);
    }
    catch (const std::exception& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error (GNC_ERROR_ARG);
    }
}

gnc_numeric_invert()

gnc_numeric gnc_numeric_invert

(

gnc_numeric

num

)

Invert a gnc_numeric.

Much faster than dividing 1 by it.

Parameters

num	The number to be inverted

Returns

a gnc_numeric that is the inverse of num

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

{
    if (num.num == 0)
        return gnc_numeric_zero();
    try
    {
        return static_cast<gnc_numeric>(GncNumeric(num).inv());
    }
    catch (const std::overflow_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_OVERFLOW);
    }
    catch (const std::invalid_argument& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_ARG);
    }
    catch (const std::underflow_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_ARG);
    }
    catch (const std::domain_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_REMAINDER);
    }
}

gnc_numeric_mul()

gnc_numeric gnc_numeric_mul	(	gnc_numeric	a,
		gnc_numeric	b,
		gint64	denom,
		gint	how
	)

Multiply a times b, returning the product.

An overflow may occur if the result of the multiplication can't be represented as a ratio of 64-bit int's after removing common factors.

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

{
    if (gnc_numeric_check(a) || gnc_numeric_check(b))
    {
        return gnc_numeric_error(GNC_ERROR_ARG);
    }
 
    try
    {
        denom = denom_lcd(a, b, denom, how);
        if ((how & GNC_NUMERIC_DENOM_MASK) != GNC_HOW_DENOM_EXACT)
        {
            GncNumeric an (a), bn (b);
            auto prod = an * bn;
            return static_cast<gnc_numeric>(convert(prod, denom, how));
        }
        GncRational ar(a), br(b);
        auto prod = ar * br;
        if (denom == GNC_DENOM_AUTO &&
            (how & GNC_NUMERIC_RND_MASK) != GNC_HOW_RND_NEVER)
            return static_cast<gnc_numeric>(prod.round_to_numeric());
        prod = convert(prod, denom, how);
        if (prod.is_big() || !prod.valid())
            return gnc_numeric_error(GNC_ERROR_OVERFLOW);
        return static_cast<gnc_numeric>(prod);
     }
    catch (const std::overflow_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_OVERFLOW);
    }
    catch (const std::invalid_argument& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_ARG);
    }
    catch (const std::underflow_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_OVERFLOW);
    }
    catch (const std::domain_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_REMAINDER);
    }
}

gnc_numeric_neg()

gnc_numeric gnc_numeric_neg

(

gnc_numeric

a

)

Returns a newly created gnc_numeric that is the negative of the given gnc_numeric value.

For a given gnc_numeric "a/b" the returned value is "-a/b".

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

{
    if (gnc_numeric_check(a))
    {
        return gnc_numeric_error(GNC_ERROR_ARG);
    }
    return gnc_numeric_create(- a.num, a.denom);
}

gnc_numeric_negative_p()

gboolean gnc_numeric_negative_p

(

gnc_numeric

a

)

Returns 1 if a < 0, otherwise returns 0.

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

{
    if (gnc_numeric_check(a))
    {
        return 0;
    }
    else
    {
        if ((a.num < 0) && (a.denom != 0))
        {
            return 1;
        }
        else
        {
            return 0;
        }
    }
}

gnc_numeric_positive_p()

gboolean gnc_numeric_positive_p

(

gnc_numeric

a

)

Returns 1 if a > 0, otherwise returns 0.

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

{
    if (gnc_numeric_check(a))
    {
        return 0;
    }
    else
    {
        if ((a.num > 0) && (a.denom != 0))
        {
            return 1;
        }
        else
        {
            return 0;
        }
    }
}

gnc_numeric_reduce()

gnc_numeric gnc_numeric_reduce

(

gnc_numeric

n

)

Return input after reducing it by Greater Common Factor (GCF) elimination.

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

{
    if (gnc_numeric_check(in))
    {
        return gnc_numeric_error(GNC_ERROR_ARG);
    }
 
    if (in.denom < 0) /* Negative denoms multiply num, can't be reduced. */
        return in;
    try
    {
        GncNumeric an (in);
        return static_cast<gnc_numeric>(an.reduce());
    }
    catch (const std::overflow_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_OVERFLOW);
    }
    catch (const std::invalid_argument& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_ARG);
    }
    catch (const std::underflow_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_ARG);
    }
    catch (const std::domain_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_REMAINDER);
    }
}

gnc_numeric_same()

gint gnc_numeric_same	(	gnc_numeric	a,
		gnc_numeric	b,
		gint64	denom,
		gint	how
	)

Equivalence predicate: Convert both a and b to denom using the specified DENOM and method HOW, and compare numerators the results using gnc_numeric_equal.

For example, if a == 7/16 and b == 3/4, gnc_numeric_same(a, b, 2, GNC_HOW_RND_TRUNC) == 1 because both 7/16 and 3/4 round to 1/2 under truncation. However, gnc_numeric_same(a, b, 2, GNC_HOW_RND_ROUND) == 0 because 7/16 rounds to 1/2 under unbiased rounding but 3/4 rounds to 2/2.

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

{
    gnc_numeric aconv, bconv;
 
    aconv = gnc_numeric_convert(a, denom, how);
    bconv = gnc_numeric_convert(b, denom, how);
 
    return(gnc_numeric_equal(aconv, bconv));
}

gnc_numeric_sub()

gnc_numeric gnc_numeric_sub	(	gnc_numeric	a,
		gnc_numeric	b,
		gint64	denom,
		gint	how
	)

Return a-b.

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

{
    if (gnc_numeric_check(a) || gnc_numeric_check(b))
    {
        return gnc_numeric_error(GNC_ERROR_ARG);
    }
    try
    {
        denom = denom_lcd(a, b, denom, how);
        if ((how & GNC_NUMERIC_DENOM_MASK) != GNC_HOW_DENOM_EXACT)
        {
            GncNumeric an (a), bn (b);
            auto sum = an - bn;
            return static_cast<gnc_numeric>(convert(sum, denom, how));
        }
        GncRational ar(a), br(b);
        auto sum = ar - br;
        if (denom == GNC_DENOM_AUTO &&
            (how & GNC_NUMERIC_RND_MASK) != GNC_HOW_RND_NEVER)
            return static_cast<gnc_numeric>(sum.round_to_numeric());
        sum = convert(sum, denom, how);
        if (sum.is_big() || !sum.valid())
            return gnc_numeric_error(GNC_ERROR_OVERFLOW);
        return static_cast<gnc_numeric>(sum);
    }
    catch (const std::overflow_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_OVERFLOW);
    }
    catch (const std::invalid_argument& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_ARG);
    }
    catch (const std::underflow_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_OVERFLOW);
    }
    catch (const std::domain_error& err)
    {
        PWARN("%s", err.what());
        return gnc_numeric_error(GNC_ERROR_REMAINDER);
    }
}

gnc_numeric_to_decimal()

gboolean gnc_numeric_to_decimal	(	gnc_numeric *	a,
		guint8 *	max_decimal_places
	)

Attempt to convert the denominator to an exact power of ten without rounding.

Parameters

a	the ::gnc_numeric value to convert
max_decimal_places	the number of decimal places of the converted value. This parameter may be NULL.

Returns

TRUE if a has been converted or was already decimal. Otherwise, FALSE is returned and a and max_decimal_places remain unchanged.

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

{
    int max_places =  max_decimal_places == NULL ? max_leg_digits :
        *max_decimal_places;
    if (a->num == 0) return TRUE;
    try
    {
        GncNumeric an (*a);
        auto bn = an.to_decimal(max_places);
        *a = static_cast<gnc_numeric>(bn);
        return TRUE;
    }
    catch (const std::exception& err)
    {
        PINFO ("%s", err.what());
        return FALSE;
    }
}

gnc_numeric_to_double()

gdouble gnc_numeric_to_double

(

gnc_numeric

n

)

Convert numeric to floating-point value.

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

{
    if (in.denom > 0)
    {
        return (double)in.num / (double)in.denom;
    }
    else
    {
        return (double)(in.num * -in.denom);
    }
}

gnc_numeric_to_string()

gchar * gnc_numeric_to_string

(

gnc_numeric

n

)

Convert to string.

The returned buffer is to be g_free'd by the caller (it was allocated through g_strdup)

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

{
    char *result;
    int64_t tmpnum = n.num;
    int64_t tmpdenom = n.denom;
 
    result = g_strdup_printf("%" PRId64 "/%" PRId64, tmpnum, tmpdenom);
 
    return result;
}

gnc_numeric_zero_p()

gboolean gnc_numeric_zero_p

(

gnc_numeric

a

)

Returns 1 if the given gnc_numeric is 0 (zero), else returns 0.

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

{
    if (gnc_numeric_check(a))
    {
        return 0;
    }
    else
    {
        if ((a.num == 0) && (a.denom != 0))
        {
            return 1;
        }
        else
        {
            return 0;
        }
    }
}

Variable Documentation

denom

gint64 gnc_numeric::denom

Definition at line 61 of file gnc-numeric.h.

num

gint64 gnc_numeric::num

Definition at line 60 of file gnc-numeric.h.