[Python-checkins] GH-105774: Clarify operation of normalize() (GH-106093)
rhettinger
webhook-mailer at python.org
Tue Jun 27 00:12:26 EDT 2023
https://github.com/python/cpython/commit/a8210b6df1ed2793c484b3380182ba56c4254a4e
commit: a8210b6df1ed2793c484b3380182ba56c4254a4e
branch: main
author: Raymond Hettinger <rhettinger at users.noreply.github.com>
committer: rhettinger <rhettinger at users.noreply.github.com>
date: 2023-06-26T23:12:22-05:00
summary:
GH-105774: Clarify operation of normalize() (GH-106093)
files:
M Doc/library/decimal.rst
diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst
index 20c5c7daac73b..c2b96954c5f8e 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,26 @@ 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?
More information about the Python-checkins
mailing list