Ladies and gentlemen, the new float.__repr__() has arrived.

1 files changed, 37 insertions, 0 deletions

diff --git a/Doc/whatsnew/3.1.rst b/Doc/whatsnew/3.1.rst
index 3057ea3..c1972ec 100644
--- a/Doc/whatsnew/3.1.rst
+++ b/Doc/whatsnew/3.1.rst
@@ -148,6 +148,43 @@ Some smaller changes made to the core Python language are:
 
   (Contributed by Mark Dickinson; :issue:`4707`.)
 
+* Python now uses David Gay's algorithm for finding the shortest floating
+  point representation that doesn't change its value.  This should help
+  mitigate the some of the confusion surrounding binary floating point
+  numbers.
+
+  The significance is easily seen with a number like ``1.1`` which does not
+  have an exact equivalent in binary floating point.  Since there is no exact
+  equivalent, an expression like ``float("1.1")`` evaluates to the nearest
+  representable value which is ``0x1.199999999999ap+0`` in hex or
+  ``1.100000000000000088817841970012523233890533447265625`` in decimal. That
+  nearest value was and still is used in subsequent floating point
+  calculations.
+
+  What is new is how the number gets displayed.  Formerly, Python used a
+  simple approach.  The value of ``repr(1.1)`` was computed as ``format(1.1,
+  '.17g')`` which evaluates to ``'1.1000000000000001'``. The advantage of
+  using 17 digits was that it relied on IEEE-754 guarantees to assure that
+  ``eval(repr(1.1))`` would round-trip exactly to its original value.  The
+  disadvantage is that many people found the output to be confusing (mistaking
+  intrinsic limitations of binary floating point representation as being a
+  problem with Python itself).
+
+  The new algorithm for ``repr(1.1)`` is smarter and returns ``1.1``.
+  Effectively, it searches all equivalent string representations (ones that
+  get stored as the same underlying float value) and returns the shortest
+  representation.
+
+  The new algorithm tends to emit cleaner representations when possible, but
+  it does not change the underlying values.  So, it is still the case that
+  ``1.1 + 2.2 != 3.3`` even though the representations may suggest otherwise.
+
+  The new algorithm depends on certain features in the underlying floating
+  point implementation.  If the required features are not found, the old
+  algorithm will continue to be used.  Also, the text pickle protocols
+  assure cross-platform portability by using the old algorithm.
+
+  (Contributed by Eric Smith and Mark Dickinson; :issue:`1580`)
 
 New, Improved, and Deprecated Modules
 =====================================