/Lib/test/ieee754.txt

  1======================================
  2Python IEEE 754 floating point support
  3======================================
  4
  5>>> from sys import float_info as FI
  6>>> from math import *
  7>>> PI = pi
  8>>> E = e
  9
 10You must never compare two floats with == because you are not going to get
 11what you expect. We treat two floats as equal if the difference between them
 12is small than epsilon.
 13>>> EPS = 1E-15
 14>>> def equal(x, y):
 15...     """Almost equal helper for floats"""
 16...     return abs(x - y) < EPS
 17
 18
 19NaNs and INFs
 20=============
 21
 22In Python 2.6 and newer NaNs (not a number) and infinity can be constructed
 23from the strings 'inf' and 'nan'.
 24
 25>>> INF = float('inf')
 26>>> NINF = float('-inf')
 27>>> NAN = float('nan')
 28
 29>>> INF
 30inf
 31>>> NINF
 32-inf
 33>>> NAN
 34nan
 35
 36The math module's ``isnan`` and ``isinf`` functions can be used to detect INF
 37and NAN:
 38>>> isinf(INF), isinf(NINF), isnan(NAN)
 39(True, True, True)
 40>>> INF == -NINF
 41True
 42
 43Infinity
 44--------
 45
 46Ambiguous operations like ``0 * inf`` or ``inf - inf`` result in NaN.
 47>>> INF * 0
 48nan
 49>>> INF - INF
 50nan
 51>>> INF / INF
 52nan
 53
 54However unambigous operations with inf return inf:
 55>>> INF * INF
 56inf
 57>>> 1.5 * INF
 58inf
 59>>> 0.5 * INF
 60inf
 61>>> INF / 1000
 62inf
 63
 64Not a Number
 65------------
 66
 67NaNs are never equal to another number, even itself
 68>>> NAN == NAN
 69False
 70>>> NAN < 0
 71False
 72>>> NAN >= 0
 73False
 74
 75All operations involving a NaN return a NaN except for the power of *0* and *1*.
 76>>> 1 + NAN
 77nan
 78>>> 1 * NAN
 79nan
 80>>> 0 * NAN
 81nan
 82>>> 1 ** NAN
 831.0
 84>>> 0 ** NAN
 850.0
 86>>> (1.0 + FI.epsilon) * NAN
 87nan
 88
 89Misc Functions
 90==============
 91
 92The power of 1 raised to x is always 1.0, even for special values like 0,
 93infinity and NaN.
 94
 95>>> pow(1, 0)
 961.0
 97>>> pow(1, INF)
 981.0
 99>>> pow(1, -INF)
1001.0
101>>> pow(1, NAN)
1021.0
103
104The power of 0 raised to x is defined as 0, if x is positive. Negative
105values are a domain error or zero division error and NaN result in a
106silent NaN.
107
108>>> pow(0, 0)
1091.0
110>>> pow(0, INF)
1110.0
112>>> pow(0, -INF)
113Traceback (most recent call last):
114...
115ValueError: math domain error
116>>> 0 ** -1
117Traceback (most recent call last):
118...
119ZeroDivisionError: 0.0 cannot be raised to a negative power
120>>> pow(0, NAN)
121nan
122
123
124Trigonometric Functions
125=======================
126
127>>> sin(INF)
128Traceback (most recent call last):
129...
130ValueError: math domain error
131>>> sin(NINF)
132Traceback (most recent call last):
133...
134ValueError: math domain error
135>>> sin(NAN)
136nan
137>>> cos(INF)
138Traceback (most recent call last):
139...
140ValueError: math domain error
141>>> cos(NINF)
142Traceback (most recent call last):
143...
144ValueError: math domain error
145>>> cos(NAN)
146nan
147>>> tan(INF)
148Traceback (most recent call last):
149...
150ValueError: math domain error
151>>> tan(NINF)
152Traceback (most recent call last):
153...
154ValueError: math domain error
155>>> tan(NAN)
156nan
157
158Neither pi nor tan are exact, but you can assume that tan(pi/2) is a large value
159and tan(pi) is a very small value:
160>>> tan(PI/2) > 1E10
161True
162>>> -tan(-PI/2) > 1E10
163True
164>>> tan(PI) < 1E-15
165True
166
167>>> asin(NAN), acos(NAN), atan(NAN)
168(nan, nan, nan)
169>>> asin(INF), asin(NINF)
170Traceback (most recent call last):
171...
172ValueError: math domain error
173>>> acos(INF), acos(NINF)
174Traceback (most recent call last):
175...
176ValueError: math domain error
177>>> equal(atan(INF), PI/2), equal(atan(NINF), -PI/2)
178(True, True)
179
180
181Hyberbolic Functions
182====================
183