[Gmp-commit] /var/hg/gmp: Rewrite mpf introduction.

[mercurial at gmplib.org]

details:   /var/hg/gmp/rev/44286f32c22e
changeset: 16920:44286f32c22e
user:      Torbjorn Granlund <torbjorng at google.com>
date:      Sat Oct 31 20:04:07 2015 +0100
description:
Rewrite mpf introduction.

diffstat:

 doc/gmp.texi |  45 ++++++++++++++++++++++++---------------------
 1 files changed, 24 insertions(+), 21 deletions(-)

diffs (66 lines):

diff -r 9290d50bb9cf -r 44286f32c22e doc/gmp.texi
--- a/doc/gmp.texi	Fri Oct 30 19:00:28 2015 +0100
+++ b/doc/gmp.texi	Sat Oct 31 20:04:07 2015 +0100
@@ -4174,7 +4174,7 @@
   mp_limb_t *xp;
 
   n = mpz_size (x);
-  xp = mpz_limbs_modify(x, 2*n);
+  xp = mpz_limbs_modify (x, 2*n);
   for (i = 0; i < n; i++)
     xp[n+i] = xp[n-1-i];
   mpz_limbs_finish (x, mpz_sgn (x) < 0 ? - 2*n : 2*n);
@@ -4550,30 +4550,33 @@
 GMP floating point numbers are stored in objects of type @code{mpf_t} and
 functions operating on them have an @code{mpf_} prefix.
 
-The mantissa of each float has a user-selectable precision, limited only by
-available memory.  Each variable has its own precision, and that can be
-increased or decreased at any time.
-
-The exponent of each float is a fixed precision, one machine word on most
+The mantissa of each float has a user-selectable precision, in practice only
+limited by available memory.  Each variable has its own precision, and that can
+be increased or decreased at any time.  This selectable precision is a minimum
+value, GMP rounds it up to a whole limb.
+
+The accuracy of a calculation is determined by the priorly set precision of the
+destination variable and the numeric values of the input variables.  Input
+variables' set precisions do not affect calculations (except indirectly as
+their values might have been affected when they were assigned).
+
+The exponent of each float has fixed precision, one machine word on most
 systems.  In the current implementation the exponent is a count of limbs, so
 for example on a 32-bit system this means a range of roughly
 @math{2^@W{-68719476768}} to @math{2^@W{68719476736}}, or on a 64-bit system
-this will be greater.  Note however that @code{mpf_get_str} can only return an
-exponent which fits an @code{mp_exp_t} and currently @code{mpf_set_str}
-doesn't accept exponents bigger than a @code{long}.
-
-Each variable keeps a size for the mantissa data actually in use.  This means
+this will be much greater.  Note however that @code{mpf_get_str} can only
+return an exponent which fits an @code{mp_exp_t} and currently
+ at code{mpf_set_str} doesn't accept exponents bigger than a @code{long}.
+
+Each variable keeps track of the mantissa data actually in use.  This means
 that if a float is exactly represented in only a few bits then only those bits
-will be used in a calculation, even if the selected precision is high.
-
-All calculations are performed to the precision of the destination variable.
-Each function calculate with ``higher'' precision then truncate to the
-destination precision.
-
-The precision selected by the user for a variable is a minimum value, GMP may
-increase it to facilitate efficient calculation.  Currently this means
-rounding up to a whole limb, and then sometimes having a further partial limb,
-depending on the high limb of the mantissa.
+will be used in a calculation, even if the variable's selected precision is
+high.  This is a performance optimization; it does not affect the numeric
+results.
+
+Internally, GMP sometimes calculates with higher precision than that of the
+destination variable in order to limit errors.  Final results are always
+truncated to the destination variable's precision.
 
 The mantissa is stored in binary.  One consequence of this is that decimal
 fractions like @math{0.1} cannot be represented exactly.  The same is true of