From af0b38f8145636d9caf8da847f8c635c7ccddc30 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Sat, 13 Aug 2016 11:10:23 -0700 Subject: [PATCH] Issue #27720: Fix error in eng_to_decimal docs and add examples from the specification. --- Doc/library/decimal.rst | 16 +++++++++++----- Lib/decimal.py | 31 +++++++++++++++++++++++++------ 2 files changed, 36 insertions(+), 11 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 8d457e192659..d164089936e6 100644 --- 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 4797a7d91c12..e5329dde4946 100644 --- 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) -- 2.47.3