Mercurial > cpython-lru_cache-weakref
annotate Doc/lib/libmath.tex @ 32527:0da660e05e69 legacy-trunk
"#if WITH_THREAD" is incorrect; must be #ifdef instead; WITH_THREAD
isn't always set to an integer value when it's defined.
| author | Tim Peters <tim.peters@gmail.com> |
|---|---|
| date | Wed, 07 Jul 2004 20:42:07 +0000 |
| parents | 6392e8437588 |
| children | edbaf610227b |
| rev | line source |
|---|---|
| 8918 | 1 \section{\module{math} --- |
| 10646 | 2 Mathematical functions} |
| 3 | |
|
8716
760dcf197048
Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents:
7877
diff
changeset
|
4 \declaremodule{builtin}{math} |
|
760dcf197048
Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents:
7877
diff
changeset
|
5 \modulesynopsis{Mathematical functions (\function{sin()} etc.).} |
|
760dcf197048
Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents:
7877
diff
changeset
|
6 |
| 10646 | 7 This module is always available. It provides access to the |
|
12223
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
10646
diff
changeset
|
8 mathematical functions defined by the C standard. |
|
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
10646
diff
changeset
|
9 |
|
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
10646
diff
changeset
|
10 These functions cannot be used with complex numbers; use the functions |
|
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
10646
diff
changeset
|
11 of the same name from the \refmodule{cmath} module if you require |
|
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
10646
diff
changeset
|
12 support for complex numbers. The distinction between functions which |
|
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
10646
diff
changeset
|
13 support complex numbers and those which don't is made since most users |
|
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
10646
diff
changeset
|
14 do not want to learn quite as much mathematics as required to |
|
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
10646
diff
changeset
|
15 understand complex numbers. Receiving an exception instead of a |
|
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
10646
diff
changeset
|
16 complex result allows earlier detection of the unexpected complex |
|
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
10646
diff
changeset
|
17 number used as a parameter, so that the programmer can determine how |
|
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
10646
diff
changeset
|
18 and why it was generated in the first place. |
|
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
10646
diff
changeset
|
19 |
|
28872
6392e8437588
Reworded fabs() for consistency with the others. Noted that all
Tim Peters <tim.peters@gmail.com>
parents:
28859
diff
changeset
|
20 The following functions are provided by this module. Except |
|
6392e8437588
Reworded fabs() for consistency with the others. Noted that all
Tim Peters <tim.peters@gmail.com>
parents:
28859
diff
changeset
|
21 when explicitly noted otherwise, all return values are floats: |
| 6363 | 22 |
|
1471
2ec96140a36b
Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
23 \begin{funcdesc}{acos}{x} |
| 6363 | 24 Return the arc cosine of \var{x}. |
| 25 \end{funcdesc} | |
| 26 | |
| 27 \begin{funcdesc}{asin}{x} | |
| 28 Return the arc sine of \var{x}. | |
| 29 \end{funcdesc} | |
| 30 | |
| 31 \begin{funcdesc}{atan}{x} | |
| 32 Return the arc tangent of \var{x}. | |
| 33 \end{funcdesc} | |
| 34 | |
|
9607
8483953a9248
Rename the parameters of atan2(), based on comments from Guido & Peter
Fred Drake <fdrake@acm.org>
parents:
8918
diff
changeset
|
35 \begin{funcdesc}{atan2}{y, x} |
|
8483953a9248
Rename the parameters of atan2(), based on comments from Guido & Peter
Fred Drake <fdrake@acm.org>
parents:
8918
diff
changeset
|
36 Return \code{atan(\var{y} / \var{x})}. |
| 6363 | 37 \end{funcdesc} |
| 38 | |
| 39 \begin{funcdesc}{ceil}{x} | |
|
15602
e23d5b2e228c
Do not talk about "real" numbers; talk about "floats" or "floating point
Fred Drake <fdrake@acm.org>
parents:
14616
diff
changeset
|
40 Return the ceiling of \var{x} as a float. |
| 6363 | 41 \end{funcdesc} |
| 42 | |
| 43 \begin{funcdesc}{cos}{x} | |
| 44 Return the cosine of \var{x}. | |
| 45 \end{funcdesc} | |
| 46 | |
| 47 \begin{funcdesc}{cosh}{x} | |
| 48 Return the hyperbolic cosine of \var{x}. | |
| 49 \end{funcdesc} | |
| 50 | |
|
23425
62403b93f470
Added degrees() and radians() to mathmodule. Closing patch 552452 and
Raymond Hettinger <python@rcn.com>
parents:
15602
diff
changeset
|
51 \begin{funcdesc}{degrees}{x} |
|
62403b93f470
Added degrees() and radians() to mathmodule. Closing patch 552452 and
Raymond Hettinger <python@rcn.com>
parents:
15602
diff
changeset
|
52 Converts angle \var{x} from radians to degrees. |
|
62403b93f470
Added degrees() and radians() to mathmodule. Closing patch 552452 and
Raymond Hettinger <python@rcn.com>
parents:
15602
diff
changeset
|
53 \end{funcdesc} |
|
62403b93f470
Added degrees() and radians() to mathmodule. Closing patch 552452 and
Raymond Hettinger <python@rcn.com>
parents:
15602
diff
changeset
|
54 |
| 6363 | 55 \begin{funcdesc}{exp}{x} |
|
6647
a7ea74a27993
Get rid of math mode in some places.
Guido van Rossum <guido@python.org>
parents:
6485
diff
changeset
|
56 Return \code{e**\var{x}}. |
| 6363 | 57 \end{funcdesc} |
| 58 | |
| 59 \begin{funcdesc}{fabs}{x} | |
|
28872
6392e8437588
Reworded fabs() for consistency with the others. Noted that all
Tim Peters <tim.peters@gmail.com>
parents:
28859
diff
changeset
|
60 Return the absolute value of \var{x}. |
| 6363 | 61 \end{funcdesc} |
| 62 | |
| 63 \begin{funcdesc}{floor}{x} | |
|
15602
e23d5b2e228c
Do not talk about "real" numbers; talk about "floats" or "floating point
Fred Drake <fdrake@acm.org>
parents:
14616
diff
changeset
|
64 Return the floor of \var{x} as a float. |
|
1471
2ec96140a36b
Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
65 \end{funcdesc} |
| 6363 | 66 |
| 67 \begin{funcdesc}{fmod}{x, y} | |
|
14616
284508c653c7
Fixed legit gripe from c.l.py that math.fmod docs aren't confusing enough.
Tim Peters <tim.peters@gmail.com>
parents:
13912
diff
changeset
|
68 Return \code{fmod(\var{x}, \var{y})}, as defined by the platform C library. |
|
284508c653c7
Fixed legit gripe from c.l.py that math.fmod docs aren't confusing enough.
Tim Peters <tim.peters@gmail.com>
parents:
13912
diff
changeset
|
69 Note that the Python expression \code{\var{x} \%\ \var{y}} may not return |
|
284508c653c7
Fixed legit gripe from c.l.py that math.fmod docs aren't confusing enough.
Tim Peters <tim.peters@gmail.com>
parents:
13912
diff
changeset
|
70 the same result. |
| 6363 | 71 \end{funcdesc} |
| 72 | |
| 73 \begin{funcdesc}{frexp}{x} | |
|
13314
03aa26819ac2
Tim-blessed documentation for math.frexp().
Fred Drake <fdrake@acm.org>
parents:
12714
diff
changeset
|
74 % Blessed by Tim. |
|
03aa26819ac2
Tim-blessed documentation for math.frexp().
Fred Drake <fdrake@acm.org>
parents:
12714
diff
changeset
|
75 Return the mantissa and exponent of \var{x} as the pair |
|
03aa26819ac2
Tim-blessed documentation for math.frexp().
Fred Drake <fdrake@acm.org>
parents:
12714
diff
changeset
|
76 \code{(\var{m}, \var{e})}. \var{m} is a float and \var{e} is an |
|
03aa26819ac2
Tim-blessed documentation for math.frexp().
Fred Drake <fdrake@acm.org>
parents:
12714
diff
changeset
|
77 integer such that \code{\var{x} == \var{m} * 2**\var{e}}. |
|
03aa26819ac2
Tim-blessed documentation for math.frexp().
Fred Drake <fdrake@acm.org>
parents:
12714
diff
changeset
|
78 If \var{x} is zero, returns \code{(0.0, 0)}, otherwise |
|
03aa26819ac2
Tim-blessed documentation for math.frexp().
Fred Drake <fdrake@acm.org>
parents:
12714
diff
changeset
|
79 \code{0.5 <= abs(\var{m}) < 1}. |
| 6363 | 80 \end{funcdesc} |
| 81 | |
| 82 \begin{funcdesc}{hypot}{x, y} | |
|
7048
3eca5f37501a
Typographical nits: Always set parameter names in \var{} in the running text.
Fred Drake <fdrake@acm.org>
parents:
6647
diff
changeset
|
83 Return the Euclidean distance, \code{sqrt(\var{x}*\var{x} + \var{y}*\var{y})}. |
| 6363 | 84 \end{funcdesc} |
| 85 | |
| 86 \begin{funcdesc}{ldexp}{x, i} | |
|
6647
a7ea74a27993
Get rid of math mode in some places.
Guido van Rossum <guido@python.org>
parents:
6485
diff
changeset
|
87 Return \code{\var{x} * (2**\var{i})}. |
| 6363 | 88 \end{funcdesc} |
| 89 | |
|
26661
b12e326b4ea2
Apply SF patch 652930: Add optional base argument to math.log(x[, base]).
Raymond Hettinger <python@rcn.com>
parents:
23425
diff
changeset
|
90 \begin{funcdesc}{log}{x\optional{, base}} |
|
26684
a9974a48a4d6
Add markup for base parameter
Neal Norwitz <nnorwitz@gmail.com>
parents:
26661
diff
changeset
|
91 Returns the logarithm of \var{x} to the given \var{base}. |
|
a9974a48a4d6
Add markup for base parameter
Neal Norwitz <nnorwitz@gmail.com>
parents:
26661
diff
changeset
|
92 If the \var{base} is not specified, returns the natural logarithm of \var{x}. |
|
26661
b12e326b4ea2
Apply SF patch 652930: Add optional base argument to math.log(x[, base]).
Raymond Hettinger <python@rcn.com>
parents:
23425
diff
changeset
|
93 \versionchanged[\var{base} argument added]{2.3} |
|
7157
a6fa9f3cad13
Added descriptions for log() and log10().
Fred Drake <fdrake@acm.org>
parents:
7048
diff
changeset
|
94 \end{funcdesc} |
|
a6fa9f3cad13
Added descriptions for log() and log10().
Fred Drake <fdrake@acm.org>
parents:
7048
diff
changeset
|
95 |
|
a6fa9f3cad13
Added descriptions for log() and log10().
Fred Drake <fdrake@acm.org>
parents:
7048
diff
changeset
|
96 \begin{funcdesc}{log10}{x} |
|
a6fa9f3cad13
Added descriptions for log() and log10().
Fred Drake <fdrake@acm.org>
parents:
7048
diff
changeset
|
97 Return the base-10 logarithm of \var{x}. |
|
a6fa9f3cad13
Added descriptions for log() and log10().
Fred Drake <fdrake@acm.org>
parents:
7048
diff
changeset
|
98 \end{funcdesc} |
|
a6fa9f3cad13
Added descriptions for log() and log10().
Fred Drake <fdrake@acm.org>
parents:
7048
diff
changeset
|
99 |
| 6363 | 100 \begin{funcdesc}{modf}{x} |
| 101 Return the fractional and integer parts of \var{x}. Both results | |
|
15602
e23d5b2e228c
Do not talk about "real" numbers; talk about "floats" or "floating point
Fred Drake <fdrake@acm.org>
parents:
14616
diff
changeset
|
102 carry the sign of \var{x}. The integer part is returned as a float. |
| 6363 | 103 \end{funcdesc} |
| 104 | |
| 105 \begin{funcdesc}{pow}{x, y} | |
|
6647
a7ea74a27993
Get rid of math mode in some places.
Guido van Rossum <guido@python.org>
parents:
6485
diff
changeset
|
106 Return \code{\var{x}**\var{y}}. |
| 6363 | 107 \end{funcdesc} |
| 108 | |
|
23425
62403b93f470
Added degrees() and radians() to mathmodule. Closing patch 552452 and
Raymond Hettinger <python@rcn.com>
parents:
15602
diff
changeset
|
109 \begin{funcdesc}{radians}{x} |
|
62403b93f470
Added degrees() and radians() to mathmodule. Closing patch 552452 and
Raymond Hettinger <python@rcn.com>
parents:
15602
diff
changeset
|
110 Converts angle \var{x} from degrees to radians. |
|
62403b93f470
Added degrees() and radians() to mathmodule. Closing patch 552452 and
Raymond Hettinger <python@rcn.com>
parents:
15602
diff
changeset
|
111 \end{funcdesc} |
|
62403b93f470
Added degrees() and radians() to mathmodule. Closing patch 552452 and
Raymond Hettinger <python@rcn.com>
parents:
15602
diff
changeset
|
112 |
| 6363 | 113 \begin{funcdesc}{sin}{x} |
| 114 Return the sine of \var{x}. | |
| 115 \end{funcdesc} | |
| 116 | |
| 117 \begin{funcdesc}{sinh}{x} | |
| 118 Return the hyperbolic sine of \var{x}. | |
| 119 \end{funcdesc} | |
| 120 | |
| 121 \begin{funcdesc}{sqrt}{x} | |
| 122 Return the square root of \var{x}. | |
| 123 \end{funcdesc} | |
| 124 | |
| 125 \begin{funcdesc}{tan}{x} | |
| 126 Return the tangent of \var{x}. | |
| 127 \end{funcdesc} | |
| 128 | |
| 129 \begin{funcdesc}{tanh}{x} | |
| 130 Return the hyperbolic tangent of \var{x}. | |
| 131 \end{funcdesc} | |
|
1471
2ec96140a36b
Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
132 |
|
7157
a6fa9f3cad13
Added descriptions for log() and log10().
Fred Drake <fdrake@acm.org>
parents:
7048
diff
changeset
|
133 Note that \function{frexp()} and \function{modf()} have a different |
| 10646 | 134 call/return pattern than their C equivalents: they take a single |
|
7157
a6fa9f3cad13
Added descriptions for log() and log10().
Fred Drake <fdrake@acm.org>
parents:
7048
diff
changeset
|
135 argument and return a pair of values, rather than returning their |
|
a6fa9f3cad13
Added descriptions for log() and log10().
Fred Drake <fdrake@acm.org>
parents:
7048
diff
changeset
|
136 second return value through an `output parameter' (there is no such |
|
a6fa9f3cad13
Added descriptions for log() and log10().
Fred Drake <fdrake@acm.org>
parents:
7048
diff
changeset
|
137 thing in Python). |
|
1471
2ec96140a36b
Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
138 |
|
2ec96140a36b
Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
139 The module also defines two mathematical constants: |
| 6363 | 140 |
|
1471
2ec96140a36b
Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
141 \begin{datadesc}{pi} |
| 6363 | 142 The mathematical constant \emph{pi}. |
|
1471
2ec96140a36b
Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
143 \end{datadesc} |
| 5818 | 144 |
| 6363 | 145 \begin{datadesc}{e} |
| 146 The mathematical constant \emph{e}. | |
| 147 \end{datadesc} | |
| 148 | |
|
28855
b62d87816976
Add note about platform-specific behavior arising from discussion on bug
Skip Montanaro <skip@pobox.com>
parents:
26684
diff
changeset
|
149 \begin{notice} |
|
28859
103faa0c2e1e
Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents:
28855
diff
changeset
|
150 The \module{math} module consists mostly of thin wrappers around |
|
103faa0c2e1e
Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents:
28855
diff
changeset
|
151 the platform C math library functions. Behavior in exceptional cases is |
|
103faa0c2e1e
Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents:
28855
diff
changeset
|
152 loosely specified by the C standards, and Python inherits much of its |
|
103faa0c2e1e
Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents:
28855
diff
changeset
|
153 math-function error-reporting behavior from the platform C |
|
103faa0c2e1e
Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents:
28855
diff
changeset
|
154 implementation. As a result, |
|
103faa0c2e1e
Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents:
28855
diff
changeset
|
155 the specific exceptions raised in error cases (and even whether some |
|
28855
b62d87816976
Add note about platform-specific behavior arising from discussion on bug
Skip Montanaro <skip@pobox.com>
parents:
26684
diff
changeset
|
156 arguments are considered to be exceptional at all) are not defined in any |
|
b62d87816976
Add note about platform-specific behavior arising from discussion on bug
Skip Montanaro <skip@pobox.com>
parents:
26684
diff
changeset
|
157 useful cross-platform or cross-release way. For example, whether |
|
b62d87816976
Add note about platform-specific behavior arising from discussion on bug
Skip Montanaro <skip@pobox.com>
parents:
26684
diff
changeset
|
158 \code{math.log(0)} returns \code{-Inf} or raises \exception{ValueError} or |
|
28859
103faa0c2e1e
Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents:
28855
diff
changeset
|
159 \exception{OverflowError} isn't defined, and in |
|
103faa0c2e1e
Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents:
28855
diff
changeset
|
160 cases where \code{math.log(0)} raises \exception{OverflowError}, |
|
103faa0c2e1e
Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents:
28855
diff
changeset
|
161 \code{math.log(0L)} may raise \exception{ValueError} instead. |
|
28855
b62d87816976
Add note about platform-specific behavior arising from discussion on bug
Skip Montanaro <skip@pobox.com>
parents:
26684
diff
changeset
|
162 \end{notice} |
|
b62d87816976
Add note about platform-specific behavior arising from discussion on bug
Skip Montanaro <skip@pobox.com>
parents:
26684
diff
changeset
|
163 |
|
6485
2f258162aae2
Restore the \seealso formatting that got lost when I updated the math
Fred Drake <fdrake@acm.org>
parents:
6363
diff
changeset
|
164 \begin{seealso} |
|
2f258162aae2
Restore the \seealso formatting that got lost when I updated the math
Fred Drake <fdrake@acm.org>
parents:
6363
diff
changeset
|
165 \seemodule{cmath}{Complex number versions of many of these functions.} |
|
2f258162aae2
Restore the \seealso formatting that got lost when I updated the math
Fred Drake <fdrake@acm.org>
parents:
6363
diff
changeset
|
166 \end{seealso} |