diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index b59e9cdef5b..ee746e933de 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -849,11 +849,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) @@ -1423,7 +1425,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 7bcf75f9afd..21e875c31c4 100644 --- a/Lib/_pydecimal.py +++ b/Lib/_pydecimal.py @@ -1118,12 +1118,11 @@ def __str__(self, eng=False, context=None): 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) @@ -5552,9 +5551,29 @@ def subtract(self, a, b): 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)