cpython-lru_cache-weakref: Doc/tutorial/floatingpoint.rst annotate

annotate Doc/tutorial/floatingpoint.rst @ 70817:dd775b1561ba

Fix markup.

author	Georg Brandl <georg@python.org>
date	Tue, 14 Jun 2011 21:09:55 +0200
parents	3c9232a684ae
children	e19ccbbe70dd

rev	line source
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 .. _tut-fp-issues:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3 **************************************************
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 Floating Point Arithmetic: Issues and Limitations
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 **************************************************
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 .. sectionauthor:: Tim Peters <tim_one@users.sourceforge.net>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10 Floating-point numbers are represented in computer hardware as base 2 (binary)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 fractions. For example, the decimal fraction ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 0.125
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 has value 1/10 + 2/100 + 5/1000, and in the same way the binary fraction ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 0.001
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 has value 0/2 + 0/4 + 1/8. These two fractions have identical values, the only
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 real difference being that the first is written in base 10 fractional notation,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 and the second in base 2.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 Unfortunately, most decimal fractions cannot be represented exactly as binary
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 fractions. A consequence is that, in general, the decimal floating-point
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 numbers you enter are only approximated by the binary floating-point numbers
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 actually stored in the machine.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 The problem is easier to understand at first in base 10. Consider the fraction
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29 1/3. You can approximate that as a base 10 fraction::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 0.3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33 or, better, ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 0.33
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37 or, better, ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 0.333
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 and so on. No matter how many digits you're willing to write down, the result
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 will never be exactly 1/3, but will be an increasingly better approximation of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43 1/3.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 In the same way, no matter how many base 2 digits you're willing to use, the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 decimal value 0.1 cannot be represented exactly as a base 2 fraction. In base
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47 2, 1/10 is the infinitely repeating fraction ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49 0.0001100110011001100110011001100110011001100110011...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50
53337 8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	51 Stop at any finite number of bits, and you get an approximation. On most
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	52 machines today, floats are approximated using a binary fraction with
54957 380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	53 the numerator using the first 53 bits starting with the most significant bit and
53337 8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	54 with the denominator as a power of two. In the case of 1/10, the binary fraction
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	55 is ``3602879701896397 / 2 ** 55`` which is close to but not exactly
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	56 equal to the true value of 1/10.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57
53337 8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	58 Many users are not aware of the approximation because of the way values are
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	59 displayed. Python only prints a decimal approximation to the true decimal
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	60 value of the binary approximation stored by the machine. On most machines, if
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	61 Python were to print the true decimal value of the binary approximation stored
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	62 for 0.1, it would have to display ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64 >>> 0.1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 0.1000000000000000055511151231257827021181583404541015625
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66
53337 8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	67 That is more digits than most people find useful, so Python keeps the number
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	68 of digits manageable by displaying a rounded value instead ::
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	69
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	70 >>> 1 / 10
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	71 0.1
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	72
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	73 Just remember, even though the printed result looks like the exact value
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	74 of 1/10, the actual stored value is the nearest representable binary fraction.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75
53337 8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	76 Interestingly, there are many different decimal numbers that share the same
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	77 nearest approximate binary fraction. For example, the numbers ``0.1`` and
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	78 ``0.10000000000000001`` and
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	79 ``0.1000000000000000055511151231257827021181583404541015625`` are all
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	80 approximated by ``3602879701896397 / 2 ** 55``. Since all of these decimal
53359 43e46e4e02f0 Remove leftover word. Georg Brandl <georg@python.org> parents: 53337 diff changeset	81 values share the same approximation, any one of them could be displayed
53337 8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	82 while still preserving the invariant ``eval(repr(x)) == x``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83
63286 056436065290 Merged revisions 83224 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 55589 diff changeset	84 Historically, the Python prompt and built-in :func:`repr` function would choose
55589 546aa134d773 Merged revisions 73656,73658,73663,73666 via svnmerge from Georg Brandl <georg@python.org> parents: 54957 diff changeset	85 the one with 17 significant digits, ``0.10000000000000001``. Starting with
53337 8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	86 Python 3.1, Python (on most systems) is now able to choose the shortest of
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	87 these and simply display ``0.1``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 Note that this is in the very nature of binary floating-point: this is not a bug
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90 in Python, and it is not a bug in your code either. You'll see the same kind of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 thing in all languages that support your hardware's floating-point arithmetic
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 (although some languages may not display the difference by default, or in all
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93 output modes).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94
63750 eafe07d40eb7 Issue #9337: Make float.__str__ identical to float.__repr__. Mark Dickinson <dickinsm@gmail.com> parents: 63285 diff changeset	95 For more pleasant output, you may may wish to use string formatting to produce a limited number of significant digits::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96
63750 eafe07d40eb7 Issue #9337: Make float.__str__ identical to float.__repr__. Mark Dickinson <dickinsm@gmail.com> parents: 63285 diff changeset	97 >>> format(math.pi, '.12g') # give 12 significant digits
53337 8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	98 '3.14159265359'
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	99
63750 eafe07d40eb7 Issue #9337: Make float.__str__ identical to float.__repr__. Mark Dickinson <dickinsm@gmail.com> parents: 63285 diff changeset	100 >>> format(math.pi, '.2f') # give 2 digits after the point
eafe07d40eb7 Issue #9337: Make float.__str__ identical to float.__repr__. Mark Dickinson <dickinsm@gmail.com> parents: 63285 diff changeset	101 '3.14'
eafe07d40eb7 Issue #9337: Make float.__str__ identical to float.__repr__. Mark Dickinson <dickinsm@gmail.com> parents: 63285 diff changeset	102
53337 8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	103 >>> repr(math.pi)
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	104 '3.141592653589793'
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105
53337 8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	106
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	107 It's important to realize that this is, in a real sense, an illusion: you're
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	108 simply rounding the display of the true machine value.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109
53480 3162eb09c2c3 Remove the round() discussion which is now out-of-date. Raymond Hettinger <python@rcn.com> parents: 53359 diff changeset	110 One illusion may beget another. For example, since 0.1 is not exactly 1/10,
53491 383e32ab607c Improve the rounding and summing examples. Raymond Hettinger <python@rcn.com> parents: 53480 diff changeset	111 summing three values of 0.1 may not yield exactly 0.3, either::
383e32ab607c Improve the rounding and summing examples. Raymond Hettinger <python@rcn.com> parents: 53480 diff changeset	112
383e32ab607c Improve the rounding and summing examples. Raymond Hettinger <python@rcn.com> parents: 53480 diff changeset	113 >>> .1 + .1 + .1 == .3
383e32ab607c Improve the rounding and summing examples. Raymond Hettinger <python@rcn.com> parents: 53480 diff changeset	114 False
383e32ab607c Improve the rounding and summing examples. Raymond Hettinger <python@rcn.com> parents: 53480 diff changeset	115
383e32ab607c Improve the rounding and summing examples. Raymond Hettinger <python@rcn.com> parents: 53480 diff changeset	116 Also, since the 0.1 cannot get any closer to the exact value of 1/10 and
383e32ab607c Improve the rounding and summing examples. Raymond Hettinger <python@rcn.com> parents: 53480 diff changeset	117 0.3 cannot get any closer to the exact value of 3/10, then pre-rounding with
383e32ab607c Improve the rounding and summing examples. Raymond Hettinger <python@rcn.com> parents: 53480 diff changeset	118 :func:`round` function cannot help::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119
53491 383e32ab607c Improve the rounding and summing examples. Raymond Hettinger <python@rcn.com> parents: 53480 diff changeset	120 >>> round(.1, 1) + round(.1, 1) + round(.1, 1) == round(.3, 1)
383e32ab607c Improve the rounding and summing examples. Raymond Hettinger <python@rcn.com> parents: 53480 diff changeset	121 False
383e32ab607c Improve the rounding and summing examples. Raymond Hettinger <python@rcn.com> parents: 53480 diff changeset	122
383e32ab607c Improve the rounding and summing examples. Raymond Hettinger <python@rcn.com> parents: 53480 diff changeset	123 Though the numbers cannot be made closer to their intended exact values,
383e32ab607c Improve the rounding and summing examples. Raymond Hettinger <python@rcn.com> parents: 53480 diff changeset	124 the :func:`round` function can be useful for post-rounding so that results
55589 546aa134d773 Merged revisions 73656,73658,73663,73666 via svnmerge from Georg Brandl <georg@python.org> parents: 54957 diff changeset	125 with inexact values become comparable to one another::
53491 383e32ab607c Improve the rounding and summing examples. Raymond Hettinger <python@rcn.com> parents: 53480 diff changeset	126
55589 546aa134d773 Merged revisions 73656,73658,73663,73666 via svnmerge from Georg Brandl <georg@python.org> parents: 54957 diff changeset	127 >>> round(.1 + .1 + .1, 10) == round(.3, 10)
53491 383e32ab607c Improve the rounding and summing examples. Raymond Hettinger <python@rcn.com> parents: 53480 diff changeset	128 True
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130 Binary floating-point arithmetic holds many surprises like this. The problem
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131 with "0.1" is explained in precise detail below, in the "Representation Error"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 section. See `The Perils of Floating Point <http://www.lahey.com/float.htm>`_
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 for a more complete account of other common surprises.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135 As that says near the end, "there are no easy answers." Still, don't be unduly
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136 wary of floating-point! The errors in Python float operations are inherited
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137 from the floating-point hardware, and on most machines are on the order of no
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138 more than 1 part in 2\\53 per operation. That's more than adequate for most
55589 546aa134d773 Merged revisions 73656,73658,73663,73666 via svnmerge from Georg Brandl <georg@python.org> parents: 54957 diff changeset	139 tasks, but you do need to keep in mind that it's not decimal arithmetic and
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140 that every float operation can suffer a new rounding error.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 While pathological cases do exist, for most casual use of floating-point
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143 arithmetic you'll see the result you expect in the end if you simply round the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 display of your final results to the number of decimal digits you expect.
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 43219 diff changeset	145 :func:`str` usually suffices, and for finer control see the :meth:`str.format`
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 43219 diff changeset	146 method's format specifiers in :ref:`formatstrings`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147
49438 9e41c5e7e360 Issue 3412: Mention fractions and decimal in the tutorial section on floating point. Raymond Hettinger <python@rcn.com> parents: 49437 diff changeset	148 For use cases which require exact decimal representation, try using the
9e41c5e7e360 Issue 3412: Mention fractions and decimal in the tutorial section on floating point. Raymond Hettinger <python@rcn.com> parents: 49437 diff changeset	149 :mod:`decimal` module which implements decimal arithmetic suitable for
9e41c5e7e360 Issue 3412: Mention fractions and decimal in the tutorial section on floating point. Raymond Hettinger <python@rcn.com> parents: 49437 diff changeset	150 accounting applications and high-precision applications.
9e41c5e7e360 Issue 3412: Mention fractions and decimal in the tutorial section on floating point. Raymond Hettinger <python@rcn.com> parents: 49437 diff changeset	151
9e41c5e7e360 Issue 3412: Mention fractions and decimal in the tutorial section on floating point. Raymond Hettinger <python@rcn.com> parents: 49437 diff changeset	152 Another form of exact arithmetic is supported by the :mod:`fractions` module
9e41c5e7e360 Issue 3412: Mention fractions and decimal in the tutorial section on floating point. Raymond Hettinger <python@rcn.com> parents: 49437 diff changeset	153 which implements arithmetic based on rational numbers (so the numbers like
9e41c5e7e360 Issue 3412: Mention fractions and decimal in the tutorial section on floating point. Raymond Hettinger <python@rcn.com> parents: 49437 diff changeset	154 1/3 can be represented exactly).
9e41c5e7e360 Issue 3412: Mention fractions and decimal in the tutorial section on floating point. Raymond Hettinger <python@rcn.com> parents: 49437 diff changeset	155
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	156 If you are a heavy user of floating point operations you should take a look
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	157 at the Numerical Python package and many other packages for mathematical and
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	158 statistical operations supplied by the SciPy project. See <http://scipy.org>.
49437 c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	159
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	160 Python provides tools that may help on those rare occasions when you really
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	161 do want to know the exact value of a float. The
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	162 :meth:`float.as_integer_ratio` method expresses the value of a float as a
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	163 fraction::
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	164
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	165 >>> x = 3.14159
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	166 >>> x.as_integer_ratio()
55589 546aa134d773 Merged revisions 73656,73658,73663,73666 via svnmerge from Georg Brandl <georg@python.org> parents: 54957 diff changeset	167 (3537115888337719, 1125899906842624)
49437 c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	168
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	169 Since the ratio is exact, it can be used to losslessly recreate the
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	170 original value::
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	171
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	172 >>> x == 3537115888337719 / 1125899906842624
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	173 True
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	174
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	175 The :meth:`float.hex` method expresses a float in hexadecimal (base
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	176 16), again giving the exact value stored by your computer::
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	177
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	178 >>> x.hex()
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	179 '0x1.921f9f01b866ep+1'
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	180
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	181 This precise hexadecimal representation can be used to reconstruct
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	182 the float value exactly::
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	183
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	184 >>> x == float.fromhex('0x1.921f9f01b866ep+1')
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	185 True
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	186
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	187 Since the representation is exact, it is useful for reliably porting values
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	188 across different versions of Python (platform independence) and exchanging
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	189 data with other languages that support the same format (such as Java and C99).
c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	190
53494 caf2b91ef06a Add link to math.fsum(). Raymond Hettinger <python@rcn.com> parents: 53491 diff changeset	191 Another helpful tool is the :func:`math.fsum` function which helps mitigate
caf2b91ef06a Add link to math.fsum(). Raymond Hettinger <python@rcn.com> parents: 53491 diff changeset	192 loss-of-precision during summation. It tracks "lost digits" as values are
caf2b91ef06a Add link to math.fsum(). Raymond Hettinger <python@rcn.com> parents: 53491 diff changeset	193 added onto a running total. That can make a difference in overall accuracy
caf2b91ef06a Add link to math.fsum(). Raymond Hettinger <python@rcn.com> parents: 53491 diff changeset	194 so that the errors do not accumulate to the point where they affect the
caf2b91ef06a Add link to math.fsum(). Raymond Hettinger <python@rcn.com> parents: 53491 diff changeset	195 final total:
caf2b91ef06a Add link to math.fsum(). Raymond Hettinger <python@rcn.com> parents: 53491 diff changeset	196
caf2b91ef06a Add link to math.fsum(). Raymond Hettinger <python@rcn.com> parents: 53491 diff changeset	197 >>> sum([0.1] * 10) == 1.0
caf2b91ef06a Add link to math.fsum(). Raymond Hettinger <python@rcn.com> parents: 53491 diff changeset	198 False
caf2b91ef06a Add link to math.fsum(). Raymond Hettinger <python@rcn.com> parents: 53491 diff changeset	199 >>> math.fsum([0.1] * 10) == 1.0
caf2b91ef06a Add link to math.fsum(). Raymond Hettinger <python@rcn.com> parents: 53491 diff changeset	200 True
49437 c0478651460f Issue 3288: document as_integer_ratio(), fromhex(), and hex(). Raymond Hettinger <python@rcn.com> parents: 48677 diff changeset	201
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202 .. _tut-fp-error:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204 Representation Error
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 ====================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207 This section explains the "0.1" example in detail, and shows how you can perform
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208 an exact analysis of cases like this yourself. Basic familiarity with binary
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 floating-point representation is assumed.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211 :dfn:`Representation error` refers to the fact that some (most, actually)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 decimal fractions cannot be represented exactly as binary (base 2) fractions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213 This is the chief reason why Python (or Perl, C, C++, Java, Fortran, and many
53337 8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	214 others) often won't display the exact decimal number you expect.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216 Why is that? 1/10 is not exactly representable as a binary fraction. Almost all
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217 machines today (November 2000) use IEEE-754 floating point arithmetic, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 almost all platforms map Python floats to IEEE-754 "double precision". 754
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219 doubles contain 53 bits of precision, so on input the computer strives to
51384 7a0525613644 Merged revisions 69350 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49438 diff changeset	220 convert 0.1 to the closest fraction it can of the form J/2*\ N* where J is
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221 an integer containing exactly 53 bits. Rewriting ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223 1 / 10 ~= J / (2**N)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225 as ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227 J ~= 2**N / 10
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 and recalling that J has exactly 53 bits (is ``>= 252`` but ``< 253``),
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 the best value for N is 56::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231
54957 380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	232 >>> 252 <= 256 // 10 < 2**53
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	233 True
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235 That is, 56 is the only value for N that leaves J with exactly 53 bits. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 best possible value for J is then that quotient rounded::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238 >>> q, r = divmod(2**56, 10)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 >>> r
48677 6e4f47a69efa Remove long integer output. Georg Brandl <georg@python.org> parents: 47283 diff changeset	240 6
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242 Since the remainder is more than half of 10, the best approximation is obtained
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 by rounding up::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245 >>> q+1
48677 6e4f47a69efa Remove long integer output. Georg Brandl <georg@python.org> parents: 47283 diff changeset	246 7205759403792794
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247
54957 380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	248 Therefore the best possible approximation to 1/10 in 754 double precision is::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249
54957 380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	250 7205759403792794 / 2 ** 56
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251
53337 8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	252 Dividing both the numerator and denominator by two reduces the fraction to::
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	253
54957 380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	254 3602879701896397 / 2 ** 55
53337 8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	255
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256 Note that since we rounded up, this is actually a little bit larger than 1/10;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257 if we had not rounded up, the quotient would have been a little bit smaller than
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258 1/10. But in no case can it be exactly 1/10!
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 So the computer never "sees" 1/10: what it sees is the exact fraction given
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 above, the best 754 double approximation it can get::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262
53337 8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	263 >>> 0.1 * 2 ** 55
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	264 3602879701896397.0
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265
54957 380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	266 If we multiply that fraction by 10\\55, we can see the value out to
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	267 55 decimal digits::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268
54957 380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	269 >>> 3602879701896397 * 10 55 // 2 55
53337 8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	270 1000000000000000055511151231257827021181583404541015625
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271
54957 380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	272 meaning that the exact number stored in the computer is equal to
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	273 the decimal value 0.1000000000000000055511151231257827021181583404541015625.
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	274 Instead of displaying the full decimal value, many languages (including
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	275 older versions of Python), round the result to 17 significant digits::
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	276
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	277 >>> format(0.1, '.17f')
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	278 '0.10000000000000001'
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279
53337 8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	280 The :mod:`fractions` and :mod:`decimal` modules make these calculations
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	281 easy::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282
53337 8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	283 >>> from decimal import Decimal
8300b274fdd3 Update for the new float.__repr__() Raymond Hettinger <python@rcn.com> parents: 51776 diff changeset	284 >>> from fractions import Fraction
54957 380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	285
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	286 >>> Fraction.from_float(0.1)
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	287 Fraction(3602879701896397, 36028797018963968)
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	288
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	289 >>> (0.1).as_integer_ratio()
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	290 (3602879701896397, 36028797018963968)
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	291
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	292 >>> Decimal.from_float(0.1)
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	293 Decimal('0.1000000000000000055511151231257827021181583404541015625')
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	294
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	295 >>> format(Decimal.from_float(0.1), '.17')
380af9e80c2e Clean-up floating point tutorial Raymond Hettinger <python@rcn.com> parents: 53494 diff changeset	296 '0.10000000000000001'

Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/floatingpoint.rst @ 70817:dd775b1561ba