QOF
0.8.7
|
Modules | |
Math128 | |
Files | |
file | qofnumeric.h |
An exact-rational-number library for QOF. | |
Data Structures | |
struct | _QofNumeric |
Typedefs | |
typedef struct _QofNumeric | QofNumeric |
A rational-number type. More... | |
Standard Arguments to most functions | |
Most of the QofNumeric arithmetic functions take two arguments in addition to their numeric args: 'denom', which is the denominator to use in the output QofNumeric 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. Valid values for denom are: QOF_DENOM_AUTO – compute denominator exactly integer n – Force the denominator of the result to be this integer QOF_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: QOF_HOW_RND_FLOOR QOF_HOW_RND_CEIL QOF_HOW_RND_TRUNC QOF_HOW_RND_PROMOTE QOF_HOW_RND_ROUND_HALF_DOWN QOF_HOW_RND_ROUND_HALF_UP QOF_HOW_RND_ROUND QOF_HOW_RND_NEVER The denominator type specifies how to compute a denominator if QOF_DENOM_AUTO is specified as the 'denom'. Valid denominator types are: QOF_HOW_DENOM_EXACT QOF_HOW_DENOM_REDUCE QOF_HOW_DENOM_LCD QOF_HOW_DENOM_FIXED QOF_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 QOF_DENOM_AUTO as 'denom' and QOF_HOW_DENOM_REDUCE| QOF_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 QOF_DENOM_AUTO as 'denom' and QOF_HOW_DENOM_FIXED | QOF_HOW_RND_NEVER as 'how'. | |
enum | { QOF_HOW_RND_FLOOR = 0x01, QOF_HOW_RND_CEIL = 0x02, QOF_HOW_RND_TRUNC = 0x03, QOF_HOW_RND_PROMOTE = 0x04, QOF_HOW_RND_ROUND_HALF_DOWN = 0x05, QOF_HOW_RND_ROUND_HALF_UP = 0x06, QOF_HOW_RND_ROUND = 0x07, QOF_HOW_RND_NEVER = 0x08 } |
Rounding/Truncation modes for operations. More... | |
enum | { QOF_HOW_DENOM_EXACT = 0x10, QOF_HOW_DENOM_REDUCE = 0x20, QOF_HOW_DENOM_LCD = 0x30, QOF_HOW_DENOM_FIXED = 0x40, QOF_HOW_DENOM_SIGFIG = 0x50 } |
enum | QofNumericErrorCode { QOF_ERROR_OK = 0, QOF_ERROR_ARG = -1, QOF_ERROR_OVERFLOW = -2, QOF_ERROR_DENOM_DIFF = -3, QOF_ERROR_REMAINDER = -4 } |
#define | QOF_NUMERIC_RND_MASK 0x0000000f |
bitmasks for HOW flags. More... | |
#define | QOF_NUMERIC_DENOM_MASK 0x000000f0 |
#define | QOF_NUMERIC_SIGFIGS_MASK 0x0000ff00 |
#define | QOF_HOW_DENOM_SIGFIGS(n) ( ((( n ) & 0xff) << 8) | QOF_HOW_DENOM_SIGFIG) |
#define | QOF_HOW_GET_SIGFIGS(a) ( (( a ) & 0xff00 ) >> 8) |
#define | QOF_DENOM_AUTO 0 |
#define | QOF_DENOM_RECIPROCAL(a) (- ( a )) |
Constructors | |
static QofNumeric | qof_numeric_create (gint64 num, gint64 denom) |
static QofNumeric | qof_numeric_zero (void) |
QofNumeric | qof_numeric_from_double (gdouble in, gint64 denom, gint how) |
gboolean | qof_numeric_from_string (const gchar *str, QofNumeric *n) |
QofNumeric | qof_numeric_error (QofNumericErrorCode error_code) |
Value Accessors | |
static gint64 | qof_numeric_num (QofNumeric a) |
static gint64 | qof_numeric_denom (QofNumeric a) |
gdouble | qof_numeric_to_double (QofNumeric in) |
gchar * | qof_numeric_to_string (QofNumeric n) |
gchar * | qof_numeric_dbg_to_string (QofNumeric n) |
Comparisons and Predicates | |
QofNumericErrorCode | qof_numeric_check (QofNumeric a) |
gint | qof_numeric_compare (QofNumeric a, QofNumeric b) |
gboolean | qof_numeric_zero_p (QofNumeric a) |
gboolean | qof_numeric_negative_p (QofNumeric a) |
gboolean | qof_numeric_positive_p (QofNumeric a) |
gboolean | qof_numeric_eq (QofNumeric a, QofNumeric b) |
gboolean | qof_numeric_equal (QofNumeric a, QofNumeric b) |
gint | qof_numeric_same (QofNumeric a, QofNumeric b, gint64 denom, gint how) |
Arithmetic Operations | |
QofNumeric | qof_numeric_add (QofNumeric a, QofNumeric b, gint64 denom, gint how) |
QofNumeric | qof_numeric_sub (QofNumeric a, QofNumeric b, gint64 denom, gint how) |
QofNumeric | qof_numeric_mul (QofNumeric a, QofNumeric b, gint64 denom, gint how) |
QofNumeric | qof_numeric_div (QofNumeric x, QofNumeric y, gint64 denom, gint how) |
QofNumeric | qof_numeric_neg (QofNumeric a) |
QofNumeric | qof_numeric_abs (QofNumeric a) |
static QofNumeric | qof_numeric_add_fixed (QofNumeric a, QofNumeric b) |
static QofNumeric | qof_numeric_sub_fixed (QofNumeric a, QofNumeric b) |
Arithmetic Functions with Exact Error Returns | |
QofNumeric | qof_numeric_add_with_error (QofNumeric a, QofNumeric b, gint64 denom, gint how, QofNumeric *error) |
QofNumeric | qof_numeric_sub_with_error (QofNumeric a, QofNumeric b, gint64 denom, gint how, QofNumeric *error) |
QofNumeric | qof_numeric_mul_with_error (QofNumeric a, QofNumeric b, gint64 denom, gint how, QofNumeric *error) |
QofNumeric | qof_numeric_div_with_error (QofNumeric a, QofNumeric b, gint64 denom, gint how, QofNumeric *error) |
Change Denominator | |
QofNumeric | qof_numeric_convert (QofNumeric in, gint64 denom, gint how) |
QofNumeric | qof_numeric_convert_with_error (QofNumeric in, gint64 denom, gint how, QofNumeric *error) |
QofNumeric | qof_numeric_reduce (QofNumeric in) |
Deprecated, backwards-compatible definitions | |
#define | QOF_RND_FLOOR QOF_HOW_RND_FLOOR |
#define | QOF_RND_CEIL QOF_HOW_RND_CEIL |
#define | QOF_RND_TRUNC QOF_HOW_RND_TRUNC |
#define | QOF_RND_PROMOTE QOF_HOW_RND_PROMOTE |
#define | QOF_RND_ROUND_HALF_DOWN QOF_HOW_RND_ROUND_HALF_DOWN |
#define | QOF_RND_ROUND_HALF_UP QOF_HOW_RND_ROUND_HALF_UP |
#define | QOF_RND_ROUND QOF_HOW_RND_ROUND |
#define | QOF_RND_NEVER QOF_HOW_RND_NEVER |
#define | QOF_DENOM_EXACT QOF_HOW_DENOM_EXACT |
#define | QOF_DENOM_REDUCE QOF_HOW_DENOM_REDUCE |
#define | QOF_DENOM_LCD QOF_HOW_DENOM_LCD |
#define | QOF_DENOM_FIXED QOF_HOW_DENOM_FIXED |
#define | QOF_DENOM_SIGFIG QOF_HOW_DENOM_SIGFIG |
#define | QOF_DENOM_SIGFIGS(X) QOF_HOW_DENOM_SIGFIGS(X) |
#define | QOF_NUMERIC_GET_SIGFIGS(X) QOF_HOW_GET_SIGFIGS(X) |
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.
#define QOF_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 231 of file qofnumeric.h.
#define QOF_DENOM_RECIPROCAL | ( | a | ) | (- ( a )) |
Use the value 1/n as the denominator of the output value.
Definition at line 234 of file qofnumeric.h.
#define QOF_HOW_DENOM_SIGFIGS | ( | n | ) | ( ((( n ) & 0xff) << 8) | QOF_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 203 of file qofnumeric.h.
#define QOF_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 QOF_HOW_DENOM_SIGFIG
Definition at line 116 of file qofnumeric.h.
typedef struct _QofNumeric QofNumeric |
A rational-number type.
This is a rational number, defined by numerator and denominator.
Definition at line 61 of file qofnumeric.h.
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"?
Possible rounding instructions are:
Definition at line 129 of file qofnumeric.h.
anonymous enum |
How to compute a denominator, or'ed into the "how" field.
Definition at line 167 of file qofnumeric.h.
enum QofNumericErrorCode |
Error codes
Definition at line 207 of file qofnumeric.h.
QofNumeric qof_numeric_abs | ( | QofNumeric | a | ) |
Return the absolute value of the argument
Definition at line 645 of file qofnumeric.c.
QofNumeric qof_numeric_add | ( | QofNumeric | a, |
QofNumeric | b, | ||
gint64 | denom, | ||
gint | how | ||
) |
Return a+b.
Definition at line 295 of file qofnumeric.c.
|
inlinestatic |
Shortcut for common case: QofNumeric_add(a, b, QOF_DENOM_AUTO, QOF_HOW_DENOM_FIXED | QOF_HOW_RND_NEVER);
Definition at line 411 of file qofnumeric.h.
QofNumeric qof_numeric_add_with_error | ( | QofNumeric | a, |
QofNumeric | b, | ||
gint64 | denom, | ||
gint | how, | ||
QofNumeric * | error | ||
) |
The same as QofNumeric_add, but uses 'error' for accumulating conversion roundoff error.
Definition at line 1009 of file qofnumeric.c.
QofNumericErrorCode qof_numeric_check | ( | QofNumeric | a | ) |
Check for error signal in value. Returns QOF_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 39 of file qofnumeric.c.
gint qof_numeric_compare | ( | QofNumeric | a, |
QofNumeric | b | ||
) |
Returns 1 if a>b, -1 if b>a, 0 if a == b
Definition at line 169 of file qofnumeric.c.
QofNumeric qof_numeric_convert | ( | QofNumeric | in, |
gint64 | denom, | ||
gint | how | ||
) |
Change the denominator of a QofNumeric value to the specified denominator under standard arguments 'denom' and 'how'.
Definition at line 657 of file qofnumeric.c.
QofNumeric qof_numeric_convert_with_error | ( | QofNumeric | in, |
gint64 | denom, | ||
gint | how, | ||
QofNumeric * | error | ||
) |
Same as QofNumeric_convert, but return a remainder value for accumulating conversion error.
|
inlinestatic |
Make a QofNumeric from numerator and denominator
Definition at line 243 of file qofnumeric.h.
gchar* qof_numeric_dbg_to_string | ( | QofNumeric | n | ) |
Convert to string. Uses a static, non-thread-safe buffer. For internal use only.
Definition at line 1098 of file qofnumeric.c.
|
inlinestatic |
QofNumeric qof_numeric_div | ( | QofNumeric | x, |
QofNumeric | 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 511 of file qofnumeric.c.
QofNumeric qof_numeric_div_with_error | ( | QofNumeric | a, |
QofNumeric | b, | ||
gint64 | denom, | ||
gint | how, | ||
QofNumeric * | error | ||
) |
The same as QofNumeric_div, but uses error for accumulating conversion roundoff error.
Definition at line 1066 of file qofnumeric.c.
gboolean qof_numeric_eq | ( | QofNumeric | a, |
QofNumeric | b | ||
) |
Equivalence predicate: Returns TRUE (1) if a and b are exactly the same (have the same numerator and denominator)
Definition at line 218 of file qofnumeric.c.
gboolean qof_numeric_equal | ( | QofNumeric | a, |
QofNumeric | 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 228 of file qofnumeric.c.
QofNumeric qof_numeric_error | ( | QofNumericErrorCode | error_code | ) |
Create a QofNumeric object that signals the error condition noted by error_code, rather than a number.
Definition at line 999 of file qofnumeric.c.
QofNumeric qof_numeric_from_double | ( | gdouble | in, |
gint64 | denom, | ||
gint | how | ||
) |
Convert a floating-point number to a QofNumeric. Both 'denom' and 'how' are used as in arithmetic, but QOF_DENOM_AUTO is not recognized; a denominator must be specified either explicitctly or through sigfigs.
Definition at line 914 of file qofnumeric.c.
gboolean qof_numeric_from_string | ( | const gchar * | str, |
QofNumeric * | n | ||
) |
Read a QofNumeric from str, skipping any leading whitespace. Return TRUE on success and store the resulting value in "n". Return NULL on error.
Definition at line 1116 of file qofnumeric.c.
QofNumeric qof_numeric_mul | ( | QofNumeric | a, |
QofNumeric | 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 400 of file qofnumeric.c.
QofNumeric qof_numeric_mul_with_error | ( | QofNumeric | a, |
QofNumeric | b, | ||
gint64 | denom, | ||
gint | how, | ||
QofNumeric * | error | ||
) |
The same as QofNumeric_mul, but uses error for accumulating conversion roundoff error.
Definition at line 1047 of file qofnumeric.c.
QofNumeric qof_numeric_neg | ( | QofNumeric | a | ) |
Negate the argument
Definition at line 632 of file qofnumeric.c.
gboolean qof_numeric_negative_p | ( | QofNumeric | a | ) |
|
inlinestatic |
gboolean qof_numeric_positive_p | ( | QofNumeric | a | ) |
QofNumeric qof_numeric_reduce | ( | QofNumeric | in | ) |
Return input after reducing it by Greated Common Factor (GCF) elimination
Definition at line 883 of file qofnumeric.c.
gint qof_numeric_same | ( | QofNumeric | a, |
QofNumeric | 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 QofNumeric_equal.
For example, if a == 7/16 and b == 3/4, QofNumeric_same(a, b, 2, QOF_HOW_RND_TRUNC) == 1 because both 7/16 and 3/4 round to 1/2 under truncation. However, QofNumeric_same(a, b, 2, QOF_HOW_RND_ROUND) == 0 because 7/16 rounds to 1/2 under unbiased rounding but 3/4 rounds to 2/2.
Definition at line 280 of file qofnumeric.c.
QofNumeric qof_numeric_sub | ( | QofNumeric | a, |
QofNumeric | b, | ||
gint64 | denom, | ||
gint | how | ||
) |
Return a-b.
Definition at line 383 of file qofnumeric.c.
|
inlinestatic |
Shortcut for most common case: QofNumeric_sub(a, b, QOF_DENOM_AUTO, QOF_HOW_DENOM_FIXED | QOF_HOW_RND_NEVER);
Definition at line 422 of file qofnumeric.h.
QofNumeric qof_numeric_sub_with_error | ( | QofNumeric | a, |
QofNumeric | b, | ||
gint64 | denom, | ||
gint | how, | ||
QofNumeric * | error | ||
) |
The same as QofNumeric_sub, but uses error for accumulating conversion roundoff error.
Definition at line 1029 of file qofnumeric.c.
gdouble qof_numeric_to_double | ( | QofNumeric | in | ) |
Convert numeric to floating-point value.
Definition at line 986 of file qofnumeric.c.
gchar* qof_numeric_to_string | ( | QofNumeric | 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 1084 of file qofnumeric.c.
|
inlinestatic |
create a zero-value QofNumeric
Definition at line 253 of file qofnumeric.h.
gboolean qof_numeric_zero_p | ( | QofNumeric | a | ) |
Returns 1 if the given QofNumeric is 0 (zero), else returns 0.
Definition at line 114 of file qofnumeric.c.