Issue #27720: Fix error in eng_to_decimal docs and add examples from the specification.

diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst
index 8d457e192659f0cd1dcdefa65da55982fc79e581..d164089936e679a4211b5780d290e4c95de66642 100644 (file)
--- a/Doc/library/decimal.rst
+++ b/Doc/library/decimal.rst
@@ -883,11 +883,13 @@ Decimal objects
 
    .. method:: to_eng_string([context])
 
-      Convert to an engineering-type string.
+      Convert to a string, using engineering notation if an exponent is needed.
 
-      Engineering notation has an exponent which is a multiple of 3, so there
-      are up to 3 digits left of the decimal place.  For example, converts
-      ``Decimal('123E+1')`` to ``Decimal('1.23E+3')``.
+      Engineering notation has an exponent which is a multiple of 3.  This
+      can leave up to 3 digits to the left of the decimal place and may
+      require the addition of either one or two trailing zeros.
+
+      For example, this converts ``Decimal('123E+1')`` to ``Decimal('1.23E+3')``.
 
    .. method:: to_integral([rounding[, context]])
 
@@ -1453,7 +1455,11 @@ In addition to the three supplied contexts, new contexts can be created with the
 
    .. method:: to_eng_string(x)
 
-      Converts a number to a string, using scientific notation.
+      Convert to a string, using engineering notation if an exponent is needed.
+
+      Engineering notation has an exponent which is a multiple of 3.  This
+      can leave up to 3 digits to the left of the decimal place and may
+      require the addition of either one or two trailing zeros.
 
 
    .. method:: to_integral_exact(x)

diff --git a/Lib/decimal.py b/Lib/decimal.py
index 4797a7d91c12e04919eb7aedf4882e4391fc5068..e5329dde494652faacff2eba11e695876aaae1aa 100644 (file)
--- a/Lib/decimal.py
+++ b/Lib/decimal.py
@@ -1048,12 +1048,11 @@ class Decimal(object):
         return sign + intpart + fracpart + exp
 
     def to_eng_string(self, context=None):
-        """Convert to engineering-type string.
+        """Convert to a string, using engineering notation if an exponent is needed.
 
-        Engineering notation has an exponent which is a multiple of 3, so there
-        are up to 3 digits left of the decimal place.
-
-        Same rules for when in exponential and when as a value as in __str__.
+        Engineering notation has an exponent which is a multiple of 3.  This
+        can leave up to 3 digits to the left of the decimal place and may
+        require the addition of either one or two trailing zeros.
         """
         return self.__str__(eng=True, context=context)
 
@@ -5339,9 +5338,29 @@ class Context(object):
             return r
 
     def to_eng_string(self, a):
-        """Converts a number to a string, using scientific notation.
+        """Convert to a string, using engineering notation if an exponent is needed.
+
+        Engineering notation has an exponent which is a multiple of 3.  This
+        can leave up to 3 digits to the left of the decimal place and may
+        require the addition of either one or two trailing zeros.
 
         The operation is not affected by the context.
+
+        >>> ExtendedContext.to_eng_string(Decimal('123E+1'))
+        '1.23E+3'
+        >>> ExtendedContext.to_eng_string(Decimal('123E+3'))
+        '123E+3'
+        >>> ExtendedContext.to_eng_string(Decimal('123E-10'))
+        '12.3E-9'
+        >>> ExtendedContext.to_eng_string(Decimal('-123E-12'))
+        '-123E-12'
+        >>> ExtendedContext.to_eng_string(Decimal('7E-7'))
+        '700E-9'
+        >>> ExtendedContext.to_eng_string(Decimal('7E+1'))
+        '70'
+        >>> ExtendedContext.to_eng_string(Decimal('0E+1'))
+        '0.00E+3'
+
         """
         a = _convert_other(a, raiseit=True)
         return a.to_eng_string(context=self)