From c03f2fa76ec5b9670a65bf43ca1be8a66689ae97 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Sun, 25 Jun 2023 18:37:37 -0500 Subject: [PATCH 1/4] GH-105774: Clarify operation of normalize() --- Doc/library/decimal.rst | 42 +++++++++++++++++++++++++++++++++++------ 1 file changed, 36 insertions(+), 6 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 20c5c7daac73bb..b6dd648fa32199 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -743,12 +743,23 @@ Decimal objects .. method:: normalize(context=None) - Normalize the number by stripping the rightmost trailing zeros and - converting any result equal to ``Decimal('0')`` to - ``Decimal('0e0')``. Used for producing canonical values for attributes - of an equivalence class. For example, ``Decimal('32.100')`` and - ``Decimal('0.321000e+2')`` both normalize to the equivalent value - ``Decimal('32.1')``. + Used for producing canonical values of an equivalence + class within either the current context or the specified context. + + This has the same semantics as the unary plus operation, except that if + the final result is finite it is reduced to its simplest form, with all + trailing zeros removed and its sign preserved. That is, while the + coefficient is non-zero and a multiple of ten the coefficient is divided + by ten and the exponent is incremented by 1. Otherwise (the coefficient is + zero) the exponent is set to 0. In all cases the sign is unchanged. + + For example, ``Decimal('32.100')`` and ``Decimal('0.321000e+2')``both + normalize to the equivalent value ``Decimal('32.1')``. + + Note that rounding is applied *before* reducing to simplest form. + + In the latest versions of the specification, this operation is also known + as ``reduce``. .. method:: number_class(context=None) @@ -2078,6 +2089,25 @@ representative: >>> [v.normalize() for v in values] [Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2')] +Q. When does rounding occur in a computation? +A. It occurs *after* the computation. The philosophy of the decimal + specification is that numbers are considered exact and are created + independent of the current context. They can even have greater + precision than current context. Computations process with those + exact inputs and then rounding (or other context operations) is + applied to the *result* of the computation:: + + >>> getcontext().prec = 5 + >>> pi = Decimal('3.1415926535') # More than 5 digits + >>> pi # All digits are retained + Decimal('3.1415926535') + >>> pi + 0 # Rounded after an addition + Decimal('3.1416') + >>> pi - Decimal('0.00005') # Subtract unrounded numbers, then round + Decimal('3.1415') + >>> pi + 0 - Decimal('0.00005'). # Intermediate values are rounded + Decimal('3.1416') + Q. Some decimal values always print with exponential notation. Is there a way to get a non-exponential representation? From 0cab2cde6c41adbaecb1c21e85011070fd445c94 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Sun, 25 Jun 2023 18:45:33 -0500 Subject: [PATCH 2/4] Add space after literal --- Doc/library/decimal.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index b6dd648fa32199..5a75adbb7bf24d 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -753,7 +753,7 @@ Decimal objects by ten and the exponent is incremented by 1. Otherwise (the coefficient is zero) the exponent is set to 0. In all cases the sign is unchanged. - For example, ``Decimal('32.100')`` and ``Decimal('0.321000e+2')``both + For example, ``Decimal('32.100')`` and ``Decimal('0.321000e+2')`` both normalize to the equivalent value ``Decimal('32.1')``. Note that rounding is applied *before* reducing to simplest form. From db91d7eec22a451d33256dc0606bc98c16ec7740 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Sun, 25 Jun 2023 18:50:24 -0500 Subject: [PATCH 3/4] Match indentation of other sections --- Doc/library/decimal.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 5a75adbb7bf24d..d922bc45dcf931 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -2090,12 +2090,13 @@ representative: [Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2')] Q. When does rounding occur in a computation? + A. It occurs *after* the computation. The philosophy of the decimal - specification is that numbers are considered exact and are created - independent of the current context. They can even have greater - precision than current context. Computations process with those - exact inputs and then rounding (or other context operations) is - applied to the *result* of the computation:: +specification is that numbers are considered exact and are created +independent of the current context. They can even have greater +precision than current context. Computations process with those +exact inputs and then rounding (or other context operations) is +applied to the *result* of the computation:: >>> getcontext().prec = 5 >>> pi = Decimal('3.1415926535') # More than 5 digits From 3aba7fc302c07f14dff2fa7ef30b1c8f78fab2d3 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Sun, 25 Jun 2023 18:53:09 -0500 Subject: [PATCH 4/4] Match indentation of other sections --- Doc/library/decimal.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index d922bc45dcf931..c2b96954c5f8ef 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -2098,16 +2098,16 @@ precision than current context. Computations process with those exact inputs and then rounding (or other context operations) is applied to the *result* of the computation:: - >>> getcontext().prec = 5 - >>> pi = Decimal('3.1415926535') # More than 5 digits - >>> pi # All digits are retained - Decimal('3.1415926535') - >>> pi + 0 # Rounded after an addition - Decimal('3.1416') - >>> pi - Decimal('0.00005') # Subtract unrounded numbers, then round - Decimal('3.1415') - >>> pi + 0 - Decimal('0.00005'). # Intermediate values are rounded - Decimal('3.1416') + >>> getcontext().prec = 5 + >>> pi = Decimal('3.1415926535') # More than 5 digits + >>> pi # All digits are retained + Decimal('3.1415926535') + >>> pi + 0 # Rounded after an addition + Decimal('3.1416') + >>> pi - Decimal('0.00005') # Subtract unrounded numbers, then round + Decimal('3.1415') + >>> pi + 0 - Decimal('0.00005'). # Intermediate values are rounded + Decimal('3.1416') Q. Some decimal values always print with exponential notation. Is there a way to get a non-exponential representation?