Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

Numeric: Rational Number Handling w/ Rounding Error Control
[Query Object Framework]


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.

Please refer to the GnuCash texinfo documentation for details on the numeric functions. (The texinfo will someday be brought inline, here, into this file).


Files

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


Data Structures

struct  _gnc_numeric

Constructors

gnc_numeric gnc_numeric_create (gint64 num, gint64 denom)
gnc_numeric gnc_numeric_zero (void)
gnc_numeric double_to_gnc_numeric (double in, gint64 denom, gint how)
const gchar * string_to_gnc_numeric (const gchar *str, gnc_numeric *n)
gnc_numeric gnc_numeric_error (int error_code)

Value accessors

gint64 gnc_numeric_num (gnc_numeric a)
gint64 gnc_numeric_denom (gnc_numeric a)
double gnc_numeric_to_double (gnc_numeric in)
gchar * gnc_numeric_to_string (gnc_numeric n)

Tests

int gnc_numeric_check (gnc_numeric a)
int gnc_numeric_zero_p (gnc_numeric a)
int gnc_numeric_compare (gnc_numeric a, gnc_numeric b)
int gnc_numeric_negative_p (gnc_numeric a)
int gnc_numeric_positive_p (gnc_numeric a)
int gnc_numeric_eq (gnc_numeric a, gnc_numeric b)
int gnc_numeric_equal (gnc_numeric a, gnc_numeric b)
int gnc_numeric_same (gnc_numeric a, gnc_numeric b, gint64 denom, gint how)

Arithmetic operations

gnc_numeric gnc_numeric_add (gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
gnc_numeric gnc_numeric_sub (gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
gnc_numeric gnc_numeric_mul (gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
gnc_numeric gnc_numeric_div (gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
gnc_numeric gnc_numeric_neg (gnc_numeric a)
gnc_numeric gnc_numeric_abs (gnc_numeric a)
gnc_numeric gnc_numeric_add_fixed (gnc_numeric a, gnc_numeric b)
gnc_numeric gnc_numeric_sub_fixed (gnc_numeric a, gnc_numeric b)

Arithmetic functions with exact error returns

gnc_numeric gnc_numeric_add_with_error (gnc_numeric a, gnc_numeric b, gint64 denom, gint how, gnc_numeric *error)
gnc_numeric gnc_numeric_sub_with_error (gnc_numeric a, gnc_numeric b, gint64 denom, gint how, gnc_numeric *error)
gnc_numeric gnc_numeric_mul_with_error (gnc_numeric a, gnc_numeric b, gint64 denom, gint how, gnc_numeric *error)
gnc_numeric gnc_numeric_div_with_error (gnc_numeric a, gnc_numeric b, gint64 denom, gint how, gnc_numeric *error)

Change denominator

gnc_numeric gnc_numeric_convert (gnc_numeric in, gint64 denom, gint how)
gnc_numeric gnc_numeric_convert_with_error (gnc_numeric in, gint64 denom, gint how, gnc_numeric *error)
gnc_numeric gnc_numeric_reduce (gnc_numeric in)

Defines

#define GNC_NUMERIC_RND_MASK   0x0000000f
#define GNC_NUMERIC_DENOM_MASK   0x000000f0
#define GNC_NUMERIC_SIGFIGS_MASK   0x0000ff00
#define GNC_DENOM_AUTO   0
#define GNC_DENOM_RECIPROCAL(a)   (- ( a ))
#define GNC_DENOM_SIGFIGS(a)   ( ((( a ) & 0xff) << 8) | GNC_DENOM_SIGFIG)
#define GNC_NUMERIC_GET_SIGFIGS(a)   ( (( a ) & 0xff00 ) >> 8)

Typedefs

typedef _gnc_numeric gnc_numeric
 An exact-number type.


Enumerations

enum  {
  GNC_RND_FLOOR = 0x01, GNC_RND_CEIL = 0x02, GNC_RND_TRUNC = 0x03, GNC_RND_PROMOTE = 0x04,
  GNC_RND_ROUND_HALF_DOWN = 0x05, GNC_RND_ROUND_HALF_UP = 0x06, GNC_RND_ROUND = 0x07, GNC_RND_NEVER = 0x08
}
enum  {
  GNC_DENOM_EXACT = 0x10, GNC_DENOM_REDUCE = 0x20, GNC_DENOM_LCD = 0x30, GNC_DENOM_FIXED = 0x40,
  GNC_DENOM_SIGFIG = 0x50
}
enum  {
  GNC_ERROR_OK = 0, GNC_ERROR_ARG = -1, GNC_ERROR_OVERFLOW = -2, GNC_ERROR_DENOM_DIFF = -3,
  GNC_ERROR_REMAINDER = -4
}


Define Documentation

#define GNC_NUMERIC_RND_MASK   0x0000000f
 

bitmasks for HOW flags


Typedef Documentation

typedef struct _gnc_numeric gnc_numeric
 

An exact-number type.

This is a rational number, defined by nominator and denominator.


Enumeration Type Documentation

anonymous enum
 

rounding/truncation modes for operations

anonymous enum
 

auto-denominator types

anonymous enum
 

errors


Function Documentation

gnc_numeric double_to_gnc_numeric double  in,
gint64  denom,
gint  how
 

convert from floating-point values

gnc_numeric gnc_numeric_abs gnc_numeric  a  ) 
 

Return the absolute value of the argument

gnc_numeric gnc_numeric_add_fixed gnc_numeric  a,
gnc_numeric  b
 

Shortcut for most common case: gnc_numeric_add(a, b, GNC_DENOM_AUTO, GNC_DENOM_FIXED | GNC_RND_NEVER);

int gnc_numeric_check gnc_numeric  a  ) 
 

Check for error signal in value. Returns GNC_ERROR_OK (==0) if there is no error, or any error code if there is one (e.g. GNC_ERROR_OVERFLOW)

int gnc_numeric_compare gnc_numeric  a,
gnc_numeric  b
 

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

gnc_numeric gnc_numeric_convert gnc_numeric  in,
gint64  denom,
gint  how
 

change the denominator of a gnc_numeric value

gnc_numeric gnc_numeric_convert_with_error gnc_numeric  in,
gint64  denom,
gint  how,
gnc_numeric error
 

change the denominator of a gnc_numeric value

gnc_numeric gnc_numeric_create gint64  num,
gint64  denom
 

make a gnc_numeric from numerator and denominator

gint64 gnc_numeric_denom gnc_numeric  a  ) 
 

Get parts

int gnc_numeric_eq gnc_numeric  a,
gnc_numeric  b
 

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

int gnc_numeric_equal gnc_numeric  a,
gnc_numeric  b
 

Equivalence predicate: Returns TRUE (1) if a and b represent exactly the same number (ratio of numerator to denominator is exactly equal)

gnc_numeric gnc_numeric_error int  error_code  ) 
 

make a special error-signalling gnc_numeric

gnc_numeric gnc_numeric_neg gnc_numeric  a  ) 
 

Negate the argument

gint64 gnc_numeric_num gnc_numeric  a  ) 
 

Get parts

gnc_numeric gnc_numeric_reduce gnc_numeric  in  ) 
 

reduce by GCF elimination

int gnc_numeric_same gnc_numeric  a,
gnc_numeric  b,
gint64  denom,
gint  how
 

Equivalence predicate: Returns TRUE (1) if after both are converted to DENOM using method HOW, a and b are gnc_numeric_equal().

gnc_numeric gnc_numeric_sub_fixed gnc_numeric  a,
gnc_numeric  b
 

Shortcut for most common case: gnc_numeric_sub(a, b, GNC_DENOM_AUTO, GNC_DENOM_FIXED | GNC_RND_NEVER);

double gnc_numeric_to_double gnc_numeric  in  ) 
 

Convert to floating-point values

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)

gnc_numeric gnc_numeric_zero void   ) 
 

create a zero-value gnc_numeric

int gnc_numeric_zero_p gnc_numeric  a  ) 
 

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

const gchar* string_to_gnc_numeric const gchar *  str,
gnc_numeric n
 

Read a gnc_numeric from str, skipping any leading whitespace, and returning a pointer to just past the last byte read. Return NULL on error.


Generated on Sun May 23 15:41:47 2004 for QOF by doxygen 1.3.6-20040222