summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorKevin B Kenny <kennykb@acm.org>2011-01-15 19:07:01 (GMT)
committerKevin B Kenny <kennykb@acm.org>2011-01-15 19:07:01 (GMT)
commitc342aae64b0aa06acf5b0e56ac8809572824ee26 (patch)
tree0974bfd4c963917887bf30cec9330b5cfe4e0193 /doc
parent63b366c72bff6d044874c992d5a767695c977b22 (diff)
downloadtcl-c342aae64b0aa06acf5b0e56ac8809572824ee26.zip
tcl-c342aae64b0aa06acf5b0e56ac8809572824ee26.tar.gz
tcl-c342aae64b0aa06acf5b0e56ac8809572824ee26.tar.bz2
* doc/tclvars.n:
* generic/tclStrToD.c: * generic/tclUtil.c (Tcl_PrintDouble): * tests/util.test (util-16.*): Restored full Tcl 8.4 compatibility for the formatting of floating point numbers when $::tcl_precision is not zero. Added compatibility tests to make sure that excess trailing zeroes are suppressed for all eight major code paths. [Bug 3157475]
Diffstat (limited to 'doc')
-rw-r--r--doc/tclvars.n36
1 files changed, 27 insertions, 9 deletions
diff --git a/doc/tclvars.n b/doc/tclvars.n
index c294be8..ef04a67 100644
--- a/doc/tclvars.n
+++ b/doc/tclvars.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: tclvars.n,v 1.35.2.1 2010/11/15 21:32:31 andreas_kupries Exp $
+'\" RCS: @(#) $Id: tclvars.n,v 1.35.2.2 2011/01/15 19:07:01 kennykb Exp $
'\"
.so man.macros
.TH tclvars n 8.0 Tcl "Tcl Built-In Commands"
@@ -299,9 +299,9 @@ is same as the result of evaluating \fIsizeof(void*)\fR in C.)
.RE
.TP
\fBtcl_precision\fR
+.
This variable controls the number of digits to generate
when converting floating-point values to strings. It defaults
-.VS 8.5
to 0. \fIApplications should not change this value;\fR it is
provided for compatibility with legacy code.
.PP
@@ -315,25 +315,43 @@ will convert as \fI1.4\fR rather than \fI1.3999999999999999\fR
even though the latter is nearer to the exact value of the
binary number.
.RE
-.VE 8.5
.PP
.RS
-17 digits is
+If \Btcl_precision\fB is not zero, then when Tcl converts a floating
+point number, it creates a decimal representation of at most
+\fBtcl_precision\fR significant digits; the result may be shorter if
+the shorter result represents the original number exactly. If no
+result of at most \fBtcl_precision\fR digits is an exact representation
+of the original number, the one that is closest to the original
+number is chosen.
+If the original number lies precisely between two equally accurate
+decimal representations, then the one with an even value for the least
+significant digit is chosen; for instance, if tcl_precision is 3, then
+0.3125 will convert to 0.312, not 0.313, while 0.6875 will convert to
+0.688, not 0.687. Any string of trailing zeroes that remains is trimmed.
+.RE
+.PP
+.RS
+a \fBtcl_precision\fR value of 17 digits is
.QW perfect
for IEEE floating-point in that it allows
double-precision values to be converted to strings and back to
-binary with no loss of information. However, using 17 digits prevents
-any rounding, which produces longer, less intuitive results. For example,
-\fBexpr {1.4}\fR returns 1.3999999999999999 with \fBtcl_precision\fR
-set to 17, vs. 1.4 if \fBtcl_precision\fR is 12.
+binary with no loss of information. For this reason, you will often
+see it as a value in legacy code that must run on Tcl versions before
+8.5. It is no longer recommended; as noted above, a zero value is the
+preferred method.
.RE
.PP
.RS
All interpreters in a thread share a single \fBtcl_precision\fR value:
changing it in one interpreter will affect all other interpreters as
-well. However, safe interpreters are not allowed to modify the
+well. Safe interpreters are not allowed to modify the
variable.
.RE
+.PP
+.RS
+Valid values for \Btcl_precision\fR range from 0 to 17.
+.RE
.TP
\fBtcl_rcFileName\fR
This variable is used during initialization to indicate the name of a