From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Sat, 2 Feb 2019 14:46:09 +0000 (-0800)
Subject: bpo-26256: Document algorithm speed for the Decimal module. (GH-4808) (#11736)
X-Git-Tag: v3.7.3rc1~107
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=a2f4c4023314f69333d2e8cee68e316619f3d68e;p=thirdparty%2FPython%2Fcpython.git

bpo-26256: Document algorithm speed for the Decimal module. (GH-4808) (#11736)

(cherry picked from commit 00e9c55d27aff3e445ab4c8629cf4d59f46ff945)

Co-authored-by: Cheryl Sabella <cheryl.sabella@gmail.com>
---

diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst
index f2a677e69363..bcae55eb8217 100644
--- a/Doc/library/decimal.rst
+++ b/Doc/library/decimal.rst
@@ -2115,3 +2115,23 @@ Alternatively, inputs can be rounded upon creation using the
 
    >>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
    Decimal('1.2345')
+
+Q. Is the CPython implementation fast for large numbers?
+
+A. Yes.  In the CPython and PyPy3 implementations, the C/CFFI versions of
+the decimal module integrate the high speed `libmpdec
+<https://www.bytereef.org/mpdecimal/doc/libmpdec/index.html>`_ library for
+arbitrary precision correctly-rounded decimal floating point arithmetic.
+``libmpdec`` uses `Karatsuba multiplication
+<https://en.wikipedia.org/wiki/Karatsuba_algorithm>`_
+for medium-sized numbers and the `Number Theoretic Transform
+<https://en.wikipedia.org/wiki/Discrete_Fourier_transform_(general)#Number-theoretic_transform>`_
+for very large numbers.  However, to realize this performance gain, the
+context needs to be set for unrounded calculations.
+
+    >>> c = getcontext()
+    >>> c.prec = MAX_PREC
+    >>> c.Emax = MAX_EMAX
+    >>> c.Emin = MIN_EMIN
+
+.. versionadded:: 3.3
\ No newline at end of file