diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 971600c35b8..b5ce0b1a8ee 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -836,11 +836,13 @@ Decimal objects .. method:: to_eng_string(context=None) - 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=None, context=None) @@ -1410,7 +1412,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/_pydecimal.py b/Lib/_pydecimal.py index c719424472e..900a1a796c0 100644 --- a/Lib/_pydecimal.py +++ b/Lib/_pydecimal.py @@ -1068,12 +1068,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) @@ -5502,9 +5501,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)