~ chicken-core (chicken-5) 1896e5828da59a1de858456e1e9942a2895943eb

commit 1896e5828da59a1de858456e1e9942a2895943eb
Author:     Jim Ursetto <zbigniewsz@gmail.com>
AuthorDate: Sat Mar 30 11:13:59 2013 -0500
Commit:     Jim Ursetto <zbigniewsz@gmail.com>
CommitDate: Sat Mar 30 11:13:59 2013 -0500

    manual: Document flonum-print-precision

diff --git a/manual/Unit library b/manual/Unit library
index 86f92f78..1efb5bdf 100644
--- a/manual/Unit library	
+++ b/manual/Unit library	
@@ -155,6 +155,44 @@ Returns {{#t}} if {{X}} is a flonum, or {{#f}} otherwise.
 
 Platform-specific flonum limits.
 
+<procedure>(flonum-print-precision [PRECISION])</procedure>
+
+Gets and sets the number of significant digits printed for a floating-point
+number. {{PRECISION}} must be a positive {{fixnum}}.  Returns
+the setting that was previously in effect.
+
+The default print precision is 15 on nearly all systems, and 7
+on the rare system on which the {{double}} type is only single-precision.
+
+'''Note:''' To ensure read/write invariance for ''all'' floating-point
+numbers, you must increase print precision from 15 to 17 (or from 7 to
+9).  For example:
+
+ > (define a (expt 2 -53))
+ > (define b (+ a (* 2 (expt 10 -32))))
+ > (eqv? a b)
+ #f
+ > (flonum-print-precision 15)
+ > (cons a b)
+ (1.11022302462516e-16 .
+  1.11022302462516e-16)            ;; same printed representation
+ > (flonum-print-precision 17)
+ > (cons a b)
+ (1.1102230246251565e-16 .
+  1.1102230246251568e-16)          ;; differs in last place
+
+On the downside, this will result in unnecessarily precise
+representations of many numbers:
+
+ > (flonum-print-precision 17)
+ > 0.1
+ 0.10000000000000001
+
+The maximum number of decimal digits required to uniquely represent
+all floating-point numbers of a certain precision is given by the
+formula {{ceil(1+N*log10(2))}}, where N is the number of bits of
+precision; for double-precision, {{N=53}}.
+
 ==== finite?
 
 <procedure>(finite? N)</procedure>