1 | | == Flonums package == |
2 | | |
3 | | ''Flonums'' are a subset of the inexact real numbers provided by a Scheme implementation. In most Schemes, the flonums and the inexact reals are the same. |
4 | | |
5 | | == R6RS flonum library == |
6 | | |
7 | | The R6RS-specific integer division procedures have been removed, as have the condition types. |
8 | | |
9 | | {{{ |
10 | | #!html |
11 | | <p> |
12 | | This section uses <i>fl</i>, <i>fl<sub>1</sub></i>, <i>fl<sub>2</sub></i>, etc., as |
13 | | parameter names for flonum arguments, and <i>ifl</i> |
| 1 | == Abstract == |
| 2 | |
| 3 | ''Flonums'' are a subset of the inexact real numbers provided by a Scheme implementation. In most Schemes, the flonums and the inexact reals are the same. It is required that if two flonums are equal in the sense of `=`, they are also equal in the sense of `eqv?`. That is, if 12.0f0 is a 32-bit inexact number, and 12.0 is a 64-bit inexact number, they cannot both be flonums. In this situation, it is recommended that the 64-bit numbers be flonums. |
| 4 | |
| 5 | == Rationale == |
| 6 | |
| 7 | Flonum arithmetic is already supported by many systems, mainly to remove type-dispatching overhead. Standardizing flonum arithmetic increases the portability of code that uses it. Standardizing the range of flonums would make flonum operations inefficient on some systems, which would defeat their purpose. Therefore, this SRFI specifies some of the semantics of flonums, but makes the range implementation-dependent. |
| 8 | |
| 9 | The sources of the procedures in this SRFI are R7RS-small, [http://srfi.schemers.org/srfi-141/srfi-141.html SRFI 141], [http://www.r6rs.org/final/html/r6rs-lib/r6rs-lib-Z-H-12.html#node_sec_11.3 the R6RS flonum library], and the [http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/math.h.html C99/Posix library] `<math.h>`, which should be available directly or indirectly to Scheme implementers. (The C90 version of `<math.h>` lacks ``arcsinh``, ``arccosh``, ``arctanh``, ``erf``, and ``tgamma``.) |
| 10 | |
| 11 | == Specification == |
| 12 | |
| 13 | Flonum operations must be at least as accurate as their generic counterparts applied to flonum arguments. It is an error, except as otherwise noted, for an argument not to be a flonum. In some cases, operations should be more accurate than their naive generic expansions because they have a smaller total roundoff error. If the generic result is a non-real number, the result is `+nan.0` if the implementation supports that number, or an arbitrary flonum if not. |
| 14 | |
| 15 | This SRFI uses ''x, y, z'' as |
| 16 | parameter names for flonum arguments, and ''ix, iy, iz'' |
15 | | <tt>integer?</tt> predicate returns true.</p> |
16 | | <p> |
17 | | </p> |
18 | | <p></p> |
19 | | <div align=left><tt>(<a name="node_idx_950"></a>flonum?<i> obj</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
20 | | <p> |
21 | | Returns <tt>#t</tt> if <i>obj</i> is a flonum, <tt>#f</tt> otherwise. |
22 | | </p> |
23 | | <p></p> |
24 | | <p> |
25 | | </p> |
26 | | <p></p> |
27 | | <div align=left><tt>(<a name="node_idx_952"></a>flonum<i> x</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
28 | | <p> |
29 | | Returns the best flonum representation of |
30 | | <i>x</i>.</p> |
31 | | <p> |
32 | | The value returned is a flonum that is numerically closest to the |
33 | | argument.</p> |
34 | | <p> |
35 | | </p> |
36 | | <blockquote><em>Note:<span style="margin-left: .5em">‌</span></em> |
37 | | If flonums are represented in binary floating point, then |
38 | | implementations should break ties by preferring |
39 | | the floating-point representation whose least significant bit is |
40 | | zero. |
41 | | </blockquote> |
42 | | <p></p> |
43 | | <p> |
44 | | </p> |
45 | | <p></p> |
46 | | <div align=left><tt>(<a name="node_idx_954"></a>fl=?<i> <i>fl<sub>1</sub></i> <i>fl<sub>2</sub></i> <i>fl<sub>3</sub></i> <tt>...</tt></i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
47 | | |
48 | | <div align=left><tt>(<a name="node_idx_956"></a>fl<?<i> <i>fl<sub>1</sub></i> <i>fl<sub>2</sub></i> <i>fl<sub>3</sub></i> <tt>...</tt></i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
49 | | |
50 | | <div align=left><tt>(<a name="node_idx_958"></a>fl<=?<i> <i>fl<sub>1</sub></i> <i>fl<sub>2</sub></i> <i>fl<sub>3</sub></i> <tt>...</tt></i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
51 | | |
52 | | <div align=left><tt>(<a name="node_idx_960"></a>fl>?<i> <i>fl<sub>1</sub></i> <i>fl<sub>2</sub></i> <i>fl<sub>3</sub></i> <tt>...</tt></i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
53 | | |
54 | | <div align=left><tt>(<a name="node_idx_962"></a>fl>=?<i> <i>fl<sub>1</sub></i> <i>fl<sub>2</sub></i> <i>fl<sub>3</sub></i> <tt>...</tt></i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
55 | | <p> |
56 | | These procedures return <tt>#t</tt> if their arguments are (respectively): |
57 | | equal, monotonically increasing, monotonically decreasing, |
58 | | monotonically nondecreasing, or monotonically nonincreasing, |
59 | | <tt>#f</tt> otherwise. These |
60 | | predicates must be transitive.</p> |
61 | | <p> |
62 | | </p> |
63 | | |
64 | | <tt>(fl= +inf.0 +inf.0) <span style="margin-left: 2em">‌</span>⇒ <tt>#t</tt> |
65 | | <p class=nopadding>(fl= -inf.0 +inf.0) <span style="margin-left: 2em">‌</span>⇒ <tt>#f</tt></p> |
66 | | |
67 | | <p class=nopadding>(fl= -inf.0 -inf.0) <span style="margin-left: 2em">‌</span>⇒ <tt>#t</tt></p> |
68 | | |
69 | | <p class=nopadding>(fl= 0.0 -0.0) <span style="margin-left: 2em">‌</span>⇒ <tt>#t</tt></p> |
70 | | |
71 | | <p class=nopadding>(fl< 0.0 -0.0) <span style="margin-left: 2em">‌</span>⇒ <tt>#f</tt></p> |
72 | | |
73 | | <p class=nopadding>(fl= +nan.0 <i>fl</i>) <span style="margin-left: 2em">‌</span>⇒ <tt>#f</tt></p> |
74 | | |
75 | | <p class=nopadding>(fl< +nan.0 <i>fl</i>) <span style="margin-left: 2em">‌</span>⇒ <tt>#f</tt></p> |
76 | | <p></tt> |
77 | | </p> |
78 | | <p></p> |
79 | | <p> |
80 | | </p> |
81 | | <p></p> |
82 | | <div align=left><tt>(<a name="node_idx_964"></a>flinteger?<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
83 | | |
84 | | <div align=left><tt>(<a name="node_idx_966"></a>flzero?<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
85 | | |
86 | | <div align=left><tt>(<a name="node_idx_968"></a>flpositive?<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
87 | | |
88 | | <div align=left><tt>(<a name="node_idx_970"></a>flnegative?<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
89 | | |
90 | | <div align=left><tt>(<a name="node_idx_972"></a>flodd?<i> ifl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
91 | | |
92 | | <div align=left><tt>(<a name="node_idx_974"></a>fleven?<i> ifl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
93 | | |
94 | | <div align=left><tt>(<a name="node_idx_976"></a>flfinite?<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
95 | | |
96 | | <div align=left><tt>(<a name="node_idx_978"></a>flinfinite?<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
97 | | |
98 | | <div align=left><tt>(<a name="node_idx_980"></a>flnan?<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
99 | | <p> |
100 | | These numerical predicates test a flonum for a particular property, |
101 | | returning <tt>#t</tt> or <tt>#f</tt>. |
102 | | The <tt>flinteger?</tt> procedure tests whether the number object is an integer, |
103 | | <tt>flzero?</tt> tests whether |
104 | | it is <tt>fl=?</tt> to zero, <tt>flpositive?</tt> tests whether it is greater |
105 | | than zero, <tt>flnegative?</tt> tests whether it is less |
106 | | than zero, <tt>flodd?</tt> tests whether it is odd, |
107 | | <tt>fleven?</tt> tests whether it is even, |
108 | | <tt>flfinite?</tt> tests whether it is not an infinity and not a NaN, |
109 | | <tt>flinfinite?</tt> tests whether it is an infinity, and |
110 | | <tt>flnan?</tt> tests whether it is a NaN.</p> |
111 | | <p> |
112 | | </p> |
113 | | |
114 | | <tt>(flnegative? -0.0) <span style="margin-left: 2em">‌</span>⇒ <tt>#f</tt> |
115 | | <p class=nopadding>(flfinite? +inf.0) <span style="margin-left: 2em">‌</span>⇒ <tt>#f</tt></p> |
116 | | |
117 | | <p class=nopadding>(flfinite? 5.0) <span style="margin-left: 2em">‌</span>⇒ <tt>#t</tt></p> |
118 | | |
119 | | <p class=nopadding>(flinfinite? 5.0) <span style="margin-left: 2em">‌</span>⇒ <tt>#f</tt></p> |
120 | | |
121 | | <p class=nopadding>(flinfinite? +inf.0) <span style="margin-left: 2em">‌</span>⇒ <tt>#t</tt></p> |
122 | | <p></tt></p> |
123 | | <p> |
124 | | </p> |
125 | | <blockquote><em>Note:<span style="margin-left: .5em">‌</span></em> |
126 | | <tt>(flnegative? -0.0)</tt> must return <tt>#f</tt>, |
127 | | else it would lose the correspondence with |
128 | | <tt>(fl< -0.0 0.0)</tt>, which is <tt>#f</tt> |
129 | | according to IEEE 754 [<a href="r6rs-lib-Z-H-21.html#node_bib_7">7</a>]. |
130 | | </blockquote> |
131 | | <p></p> |
132 | | <p> |
133 | | </p> |
134 | | <p></p> |
135 | | <div align=left><tt>(<a name="node_idx_982"></a>flmax<i> <i>fl<sub>1</sub></i> <i>fl<sub>2</sub></i> <tt>...</tt></i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
136 | | |
137 | | <div align=left><tt>(<a name="node_idx_984"></a>flmin<i> <i>fl<sub>1</sub></i> <i>fl<sub>2</sub></i> <tt>...</tt></i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
138 | | <p> |
139 | | These procedures return the maximum or minimum of their arguments. |
140 | | They always return a NaN when one or more of the arguments is a NaN. |
141 | | </p> |
142 | | <p></p> |
143 | | <p> |
144 | | </p> |
145 | | <p></p> |
146 | | <div align=left><tt>(<a name="node_idx_986"></a>fl+<i> <i>fl<sub>1</sub></i> <tt>...</tt></i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
147 | | |
148 | | <div align=left><tt>(<a name="node_idx_988"></a>fl*<i> <i>fl<sub>1</sub></i> <tt>...</tt></i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
149 | | <p> |
150 | | These procedures return the flonum sum or product of their flonum |
| 18 | `integer?` predicate returns true. |
| 19 | |
| 20 | === Constants === |
| 21 | |
| 22 | The following C99 constants are provided as Scheme variables. |
| 23 | |
| 24 | `fl-e` |
| 25 | |
| 26 | Value of the mathematical constant ''e''. (C99 `M_E`) |
| 27 | |
| 28 | `fl-log2-e` |
| 29 | |
| 30 | Value of `(fllog fl-e 2.0)`. (C99 `M_LOG2E`) |
| 31 | |
| 32 | `fl-log10-e` |
| 33 | |
| 34 | Value of `(fllog fl-e 10.0)`. (C99 `M_LOG10E`) |
| 35 | |
| 36 | `fl-ln-2` |
| 37 | |
| 38 | Value of `(fllog 2.0)` (C99 `M_LN2`) |
| 39 | |
| 40 | `fl-ln-10` |
| 41 | |
| 42 | Value of `(fllog 10.0)` (C99 `M_LN10`) |
| 43 | |
| 44 | `fl-pi` |
| 45 | |
| 46 | Value of the mathematical constant π. (C99 `M_PI`) |
| 47 | |
| 48 | `fl-pi/2` |
| 49 | |
| 50 | Value of `(fl/ fl-pi 2.0)` (C99 `M_PI_2`) |
| 51 | |
| 52 | `fl-pi/4` |
| 53 | |
| 54 | Value of `(fl/ fl-pi 4.0)` (C99 `M_PI_4`) |
| 55 | |
| 56 | `fl-1/pi` |
| 57 | |
| 58 | Value of `(fl/ 1.0 fl-pi)`. (C99 `M_1_PI`) |
| 59 | |
| 60 | `fl-2/pi` |
| 61 | |
| 62 | Value of `(fl/ 2.0 fl-pi)`. (C99 `M_2_PI`) |
| 63 | |
| 64 | `fl-2/sqrt-pi` |
| 65 | |
| 66 | Value of `(fl/ 2.0 (flsqrt fl-pi))`. (C99 `M_2_SQRTPI`) |
| 67 | |
| 68 | `fl-sqrt-2` |
| 69 | |
| 70 | Value of `(flsqrt 2.0)`. (C99 `M_SQRT2`) |
| 71 | |
| 72 | `fl-1/sqrt-2` |
| 73 | |
| 74 | Value of `(fl/ 1,0 (flsqrt 2.0))`. (C99 `M_SQRT1_2`) |
| 75 | |
| 76 | `fl-maximum` |
| 77 | |
| 78 | Value of the largest finite flonum. |
| 79 | |
| 80 | `fl-fast-multiply-add` |
| 81 | |
| 82 | Equal to `#t` if `(fl+* x y z)` is known to be faster than `(fl+ (fl* x y) z), or `#f` otherwise. (C99 `FP_FAST_FMA`) |
| 83 | |
| 84 | `fl-integer-exponent-zero` |
| 85 | |
| 86 | Value of `(flinteger-binary-log 0)`. (C99 `FP_ILOGB0`) |
| 87 | |
| 88 | `fl-integer-exponent-nan` |
| 89 | |
| 90 | Value of `(flinteger-binary-log +0.nan)`. (C99 `FP_ILOGBNAN`) |
| 91 | |
| 92 | == Constructors == |
| 93 | |
| 94 | `(flonum `''number''`)` |
| 95 | |
| 96 | Returns the closest flonum equivalent to ''number'' in the sense of `=` and `<`. |
| 97 | |
| 98 | `(fladjacent `''x y''`)` |
| 99 | |
| 100 | Returns a flonum adjacent to ''x'' in the direction of ''y''. Specifically: if ''x < y'', returns the smallest flonum larger than ''x''; if ''x > y'', returns the largest flonum smaller than ''x''; if ''x = y'', returns ''x''. (C99 `nextafter`) |
| 101 | |
| 102 | `(flcopysign `''x y''`)` |
| 103 | |
| 104 | Returns a flonum whose magnitude is the magnitude of ''x'' and whose sign is the sign of ''y''. (C99 `copysign`) |
| 105 | |
| 106 | === Predicates === |
| 107 | |
| 108 | `(flonum? `''obj''`)` |
| 109 | |
| 110 | Returns `#t` if ''obj'' is a flonum and `#f` otherwise. |
| 111 | |
| 112 | `(fl= `''x y z'' ...`)` |
| 113 | |
| 114 | `(fl< `''x y z'' ...`)` |
| 115 | |
| 116 | `(fl> `''x y z'' ...`)` |
| 117 | |
| 118 | `(fl<= `''x y z'' ...`)` |
| 119 | |
| 120 | `(fl>= `''x y z'' ...`)` |
| 121 | |
| 122 | These procedures return `#t` if their arguments are (respectively): equal, monotonically increasing, monotonically decreasing, monotonically nondecreasing, or monotonically nonincreasing; they return `#f` otherwise. These predicates must be transitive. |
| 123 | |
| 124 | `(flinteger? `''x''`) |
| 125 | |
| 126 | `(flzero? `''x''`)` |
| 127 | |
| 128 | `(flpositive? `''x''`)` |
| 129 | |
| 130 | `(flnegative? `''x''`)` |
| 131 | |
| 132 | `(flodd? `''ix''`)` |
| 133 | |
| 134 | `(fleven? `''ix''`)` |
| 135 | |
| 136 | `(flfinite? `''ix''`)` |
| 137 | |
| 138 | `(flinfinite? `''ix''`)` |
| 139 | |
| 140 | `(flnan? `''ix''`)` |
| 141 | |
| 142 | These numerical predicates test a flonum for a particular property, returning `#t` or `#f`. The `flinteger?` procedure tests whether the flonum is an integer, `flzero?` tests whether it is `fl=?` to zero, `flpositive?` tests whether it is greater than zero, `flnegative?` tests whether it is less than zero, `flodd?` tests whether it is odd, `fleven?` tests whether it is even, `flfinite?` tests whether it is not an infinity and not a NaN, `flinfinite?` tests whether it is an infinity, and `flnan?` tests whether it is a NaN. |
| 143 | |
| 144 | Note that `(flnegative? -0.0)<` must return `#f`; |
| 145 | otherwise it would lose the correspondence with |
| 146 | `(fl< -0.0 0.0)`, which is `#f` |
| 147 | according to IEEE 754. |
| 148 | |
| 149 | === Arithmetic === |
| 150 | |
| 151 | `(fl+ `''x''`)` |
| 152 | |
| 153 | `(fl* `''x''`)` |
| 154 | |
| 155 | Return the flonum sum or product of their flonum |
181 | | difference or quotient. (For implementations that represent flonums |
182 | | using IEEE binary floating point, the meaning of “best” is |
183 | | reasonably well-defined by the IEEE standards.)</p> |
184 | | <p> |
185 | | </p> |
186 | | |
187 | | <tt>(fl- +inf.0 +inf.0) <span style="margin-left: 2em">‌</span>⇒ +nan.0<p></tt></p> |
188 | | <p> |
189 | | For undefined quotients, <tt>fl/</tt> behaves as specified by the |
190 | | IEEE standards:</p> |
191 | | <p> |
192 | | </p> |
193 | | |
194 | | <tt>(fl/ 1.0 0.0) <span style="margin-left: 2em">‌</span>⇒ +inf.0 |
195 | | <p class=nopadding>(fl/ -1.0 0.0) <span style="margin-left: 2em">‌</span>⇒ -inf.0</p> |
196 | | |
197 | | <p class=nopadding>(fl/ 0.0 0.0) <span style="margin-left: 2em">‌</span>⇒ +nan.0</p> |
198 | | <p></tt> |
199 | | </p> |
200 | | <p></p> |
201 | | <p> |
202 | | </p> |
203 | | <p></p> |
204 | | <div align=left><tt>(<a name="node_idx_998"></a>flabs<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
205 | | <p> |
206 | | Returns the absolute value of <i>fl</i>. |
207 | | </p> |
208 | | <p></p> |
209 | | <p> |
210 | | </p> |
211 | | <p></p> |
212 | | <div align=left><tt>(<a name="node_idx_1012"></a>flnumerator<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
213 | | |
214 | | <div align=left><tt>(<a name="node_idx_1014"></a>fldenominator<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
215 | | <p> |
216 | | These procedures return the numerator or denominator of <i>fl</i> |
217 | | as a flonum; the result is computed as if <i>fl</i> was represented as |
| 175 | difference or quotient. For undefined quotients, `fl/` |
| 176 | behaves as specified by the |
| 177 | IEEE standards. |
| 178 | |
| 179 | For implementations that represent flonums |
| 180 | using IEEE binary floating point, the meaning of "best" is |
| 181 | reasonably well-defined by the IEEE standards. |
| 182 | |
| 183 | `(flmax `''x'' ...`)` |
| 184 | |
| 185 | `(flmin `''x'' ...`)` |
| 186 | |
| 187 | Return the maximum/minimum argument. If there are no arguments, these procedures return `+inf.0`/`-inf.0` if the implementation provides these numbers, and `fl-maximum` / its negation otherwise. |
| 188 | |
| 189 | `(flabs `''x''`)` |
| 190 | |
| 191 | Returns the absolute value of ''x''. |
| 192 | |
| 193 | `(flabsdiff `''x y''`)` |
| 194 | |
| 195 | Returns `(flabs (fl- x y))`. (C99 `fdim`) |
| 196 | |
| 197 | `(flsgn `''x''`)` |
| 198 | |
| 199 | Returns `(flcopy-sign 1.0 x)`. |
| 200 | |
| 201 | `(flnumerator `''x''`)` |
| 202 | |
| 203 | `(fldenominator `''x''`)` |
| 204 | |
| 205 | Returns the numerator/enominator of ``x`` |
| 206 | as a flonum; the result is computed as if <i>x</i> was represented as |
264 | | given a NaN:</p> |
265 | | <p> |
266 | | </p> |
267 | | |
268 | | <tt>(flfloor +inf.0) <span style="margin-left: 2em">‌</span>⇒ +inf.0 |
269 | | <p class=nopadding>(flceiling -inf.0) <span style="margin-left: 2em">‌</span>⇒ -inf.0</p> |
270 | | |
271 | | <p class=nopadding>(fltruncate +nan.0) <span style="margin-left: 2em">‌</span>⇒ +nan.0</p> |
272 | | <p></tt> |
273 | | </p> |
274 | | <p></p> |
275 | | <p> |
276 | | </p> |
277 | | <p></p> |
278 | | <div align=left><tt>(<a name="node_idx_1024"></a>flexp<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
279 | | |
280 | | <div align=left><tt>(<a name="node_idx_1026"></a>fllog<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
281 | | |
282 | | <div align=left><tt>(<a name="node_idx_1028"></a>fllog<i> <i>fl<sub>1</sub></i> <i>fl<sub>2</sub></i></i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
283 | | |
284 | | <div align=left><tt>(<a name="node_idx_1030"></a>flsin<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
285 | | |
286 | | <div align=left><tt>(<a name="node_idx_1032"></a>flcos<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
287 | | |
288 | | <div align=left><tt>(<a name="node_idx_1034"></a>fltan<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
289 | | |
290 | | <div align=left><tt>(<a name="node_idx_1036"></a>flasin<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
291 | | |
292 | | <div align=left><tt>(<a name="node_idx_1038"></a>flacos<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
293 | | |
294 | | <div align=left><tt>(<a name="node_idx_1040"></a>flatan<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
295 | | |
296 | | <div align=left><tt>(<a name="node_idx_1042"></a>flatan<i> <i>fl<sub>1</sub></i> <i>fl<sub>2</sub></i></i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
297 | | <p> |
298 | | These procedures compute the usual transcendental functions. |
299 | | The <tt>flexp</tt> procedure computes the base-<em>e</em> exponential of <i>fl</i>. |
300 | | The <tt>fllog</tt> procedure with a single argument computes the natural logarithm of |
301 | | <i>fl</i> (not the base ten logarithm); <tt>(fllog <i>fl<sub>1</sub></i> |
302 | | <i>fl<sub>2</sub></i>)</tt> computes the base-<i>fl<sub>2</sub></i> logarithm of <i>fl<sub>1</sub></i>. |
303 | | The <tt>flasin</tt>, <tt>flacos</tt>, and <tt>flatan</tt> procedures compute arcsine, |
304 | | arccosine, and arctangent, respectively. <tt>(flatan <i>fl<sub>1</sub></i> |
305 | | <i>fl<sub>2</sub></i>)</tt> computes the arc tangent of <i>fl<sub>1</sub></i>/<i>fl<sub>2</sub></i>.</p> |
306 | | <p> |
307 | | See report |
308 | | section on “Transcendental functions” for the underlying |
309 | | mathematical operations. In the event that these operations do not |
310 | | yield a real result for the given arguments, the result may be a NaN, |
311 | | or may be some unspecified flonum.</p> |
312 | | <p> |
| 231 | given a NaN. |
| 232 | |
| 233 | === Exponents and logarithms === |
| 234 | |
| 235 | |
| 236 | |
| 237 | === Trigonometric functions === |
| 238 | |
| 239 | `(flsin `''x''`)` (C99 `sin`) |
| 240 | |
| 241 | `(flcos `''x''`)` (C99 `cos`) |
| 242 | |
| 243 | `(fltan `''x''`)` (C99 `tan`) |
| 244 | |
| 245 | `(flasin `''x''`)` (C99 `asin`) |
| 246 | |
| 247 | `(flacos `''x''`)` (C99 `acos`) |
| 248 | |
| 249 | `(flatan `''x'' [''y'']`)` (C99 `atan` and `atan2`) |
| 250 | |
| 251 | `(flsinh `''x''`)` (C99 `sinh`) |
| 252 | |
| 253 | `(flcosh `''x''`)` (C99 `cosh`) |
| 254 | |
| 255 | `(fltanh `''x''`)` (C99 `tanh`) |
| 256 | |
| 257 | `(flasinh `''x''`)` (C99 `asinh`) |
| 258 | |
| 259 | `(flacosh `''x''`)` (C99 `acosh`) |
| 260 | |
| 261 | `(flatanh `''x''`)` (C99 `atanh`) |
| 262 | |
| 263 | These are the usual trigonometric functions. Note that if the result is not a real number, `+nan.0` is returned if available, or if not, an arbitrary flonum. The `flatan` function, when passed two arguments, returns `(flatan (/ y x))` without requiring the use of complex numbers. |
314 | | should follow the relevant standards for these procedures.</p> |
315 | | <p> |
316 | | </p> |
317 | | |
318 | | <tt>(flexp +inf.0) <span style="margin-left: 2em">‌</span>⇒ +inf.0 |
319 | | <p class=nopadding>(flexp -inf.0) <span style="margin-left: 2em">‌</span>⇒ 0.0</p> |
320 | | |
321 | | <p class=nopadding>(fllog +inf.0) <span style="margin-left: 2em">‌</span>⇒ +inf.0</p> |
322 | | |
323 | | <p class=nopadding>(fllog 0.0) <span style="margin-left: 2em">‌</span>⇒ -inf.0</p> |
324 | | |
325 | | <p class=nopadding>(fllog -0.0) <span style="margin-left: 2em">‌</span>⇒ <i>unspecified</i><br> |
326 | | ; if -0.0 is distinguished</p> |
327 | | |
328 | | <p class=nopadding>(fllog -inf.0) <span style="margin-left: 2em">‌</span>⇒ +nan.0</p> |
329 | | |
330 | | <p class=nopadding>(flatan -inf.0) <br><span style="margin-left: 2em">‌</span><span style="margin-left: 2em">‌</span>⇒ -1.5707963267948965<br> |
331 | | ; approximately</p> |
332 | | |
333 | | <p class=nopadding>(flatan +inf.0) <br><span style="margin-left: 2em">‌</span><span style="margin-left: 2em">‌</span>⇒ 1.5707963267948965<br> |
334 | | ; approximately</p> |
335 | | <p></tt> |
336 | | </p> |
337 | | <p></p> |
338 | | <p> |
339 | | </p> |
340 | | <p></p> |
341 | | <div align=left><tt>(<a name="node_idx_1044"></a>flsqrt<i> fl</i>)</tt><span style="margin-left: .5em">‌</span><span style="margin-left: .5em">‌</span>procedure </div> |
342 | | <p> |
| 265 | should follow the relevant standards for these procedures. |
| 266 | |
| 267 | ||`flremquo`||`double remquo(double, double, int *)`||returns two values, rounded remainder and low-order ''n'' bits of the quotient (''n'' is implementation-defined) |
| 268 | |
| 269 | |
| 270 | === Integer division === |
| 271 | |
| 272 | The following procedures are the flonum counterparts of procedures from [http://srfi.schemers.org/srfi-141/srfi-141.html SRFI 141]: |
| 273 | |
| 274 | {{{ |
| 275 | flfloor/ flfloor-quotient flfloor-remainder |
| 276 | flceiling/ flceiling-quotient flceiling-remainder |
| 277 | fltruncate/ fltruncate-quotient fltruncate-remainder |
| 278 | flround/ flround-quotient flround-remainder |
| 279 | fleuclidean/ fleuclidean-quotient fleuclidean-remainder |
| 280 | flbalanced/ flbalanced-quotient flbalanced-remainder |
| 281 | }}} |
| 282 | |
| 283 | They have the same arguments and semantics as their generic counterparts, |
| 284 | except that it is an error if the arguments are not flonums. |
| 285 | |
| 286 | === Special functions === |
| 287 | |
| 288 | ||Scheme name||C signature||Comments|| |
| 289 | ||`flcomplementary-error-function`||`double erfc(double)`||-|| |
| 290 | ||`flerror-function`||`double erf(double)`||-|| |
| 291 | ||`flfirst-bessel`||`double jn(int n, double)`||bessel function of the first kind, order n|| |
| 292 | ||`flgamma`||`double tgamma(double)`||-|| |
| 293 | ||`fllog-gamma`||`double lgamma(double)`||returns two values, log(|gamma(x)|) and sgn(gamma(x))|| |
| 294 | ||`flsecond-bessel`||`double yn(int n, double)`||bessel function of the second kind, order ''n''|| |
| 295 | |
| 296 | === Junk === |
| 297 | |
| 298 | {{{ |
| 299 | #!html |
386 | | == Integer division == |
| 317 | |
| 318 | === Decoding flonums === |
| 319 | |
| 320 | decode-float float => significand, exponent, sign |
| 321 | |
| 322 | scale-float float integer => scaled-float |
| 323 | |
| 324 | float-radix float => float-radix |
| 325 | |
| 326 | float-sign float-1 &optional float-2 => signed-float |
| 327 | |
| 328 | float-digits float => digits1 |
| 329 | |
| 330 | float-precision float => digits2 |
| 331 | |
| 332 | integer-decode-float float => significand, exponent, integer-sign |
| 333 | |
| 334 | |
| 335 | |
| 336 | Description: |
| 337 | |
| 338 | decode-float computes three values that characterize float. The first value is of the same type as float and represents the significand. The second value represents the exponent to which the radix (notated in this description by b) must be raised to obtain the value that, when multiplied with the first result, produces the absolute value of float. If float is zero, any integer value may be returned, provided that the identity shown for scale-float holds. The third value is of the same type as float and is 1.0 if float is greater than or equal to zero or -1.0 otherwise. |
| 339 | |
| 340 | decode-float divides float by an integral power of b so as to bring its value between 1/b (inclusive) and 1 (exclusive), and returns the quotient as the first value. If float is zero, however, the result equals the absolute value of float (that is, if there is a negative zero, its significand is considered to be a positive zero). |
| 341 | |
| 342 | scale-float returns `(* float (expt (float b float) integer))`, where b is the radix of the floating-point representation. float is not necessarily between 1/b and 1. |
| 343 | |
| 344 | float-radix returns the radix of float. |
| 345 | |
| 346 | float-sign returns a number z such that z and float-1 have the same sign and also such that z and float-2 have the same absolute value. If float-2 is not supplied, its value is `(float 1 float-1)`. If an implementation has distinct representations for negative zero and positive zero, then `(float-sign -0.0) => -1.0`. |
| 347 | |
| 348 | float-digits returns the number of radix b digits used in the representation of float (including any implicit digits, such as a ``hidden bit''). |
| 349 | |
| 350 | float-precision returns the number of significant radix b digits present in float; if float is a float zero, then the result is an integer zero. |
| 351 | |
| 352 | For normalized floats, the results of float-digits and float-precision are the same, but the precision is less than the number of representation digits for a denormalized or zero number. |
| 353 | |
| 354 | integer-decode-float computes three values that characterize float - the significand scaled so as to be an integer, and the same last two values that are returned by decode-float. If float is zero, integer-decode-float returns zero as the first value. The second value bears the same relationship to the first value as for decode-float: |
421 | | These are variants of the DivisionRiastradh integer division functions that accept flonums and return a flonum. |
422 | | |
423 | | `(decode-float `''z''`)` and friends |
424 | | |
425 | | See [http://www.lispworks.com/documentation/lw50/CLHS/Body/f_dec_fl.htm CL DECODE-FLOAT and friends]. |
426 | | |
427 | | |
428 | | == C99 <math.h> constants == |
429 | | |
430 | | The following constants are defined in terms of the constants of the <math.h> header of ISO/IEC 9899:1999 (C language). |
431 | | |
432 | | ||Scheme name||C name||Comments|| |
433 | | ||`fl:e`||`M_E`||Value of e|| |
434 | | ||`fl:log2-e`||`M_LOG2E`||Value of log,,2,, e|| |
435 | | ||`fl:log10-e`||`M_LOG10E`||Value of log,,10,, e|| |
436 | | ||`fl:ln-2`||`M_LN2`||Value of log,,e,, 2|| |
437 | | ||`fl:ln-10`||`M_LN10`||Value of log,,e,, 10|| |
438 | | ||`fl:pi`||`M_PI`||Value of pi|| |
439 | | ||`fl:pi/2`||`M_PI_2`||Value of pi/2|| |
440 | | ||`fl:pi/4`||`M_PI_4`||Value of pi/4|| |
441 | | ||`fl:one-over-pi`||`M_1_PI`||Value of 1/pi|| |
442 | | ||`fl:two-over-pi`||`M_2_PI`||Value of 2/pi|| |
443 | | ||`fl:two-over-sqrt-pi`||`M_2_SQRTPI`||Value of 2/sqrt(pi)|| |
444 | | ||`fl:sqrt-2`||`M_SQRT2`||Value of sqrt(2)|| |
445 | | ||`fl:one-over-sqrt-2`||`M_SQRT1_2`||Value of 1/sqrt(2)|| |
446 | | ||`fl:maximum-flonum`||`HUGE_VAL`||`+inf.0` or else\\the largest finite flonum|| |
447 | | ||`fl:fast-multiply-add`||`#t` if `FP_FAST_FMA` is 1,\\or `#f` otherwise||multiply-add is fast|| |
448 | | ||`fl:integer-exponent-zero`||`FP_ILOGB0`||what `(flinteger-binary-log 0)` returns|| |
449 | | ||`fl:integer-exponent-nan`||`FP_ILOGBNAN`||what `(flinteger-binary-log +0.nan)` returns|| |
450 | | |
451 | | == C99 <math.h> procedures == |
452 | | |
453 | | The following procedures are defined in terms of the functions of the <math.h> header of ISO/IEC 9899:1999 (C language). In the C signatures, the types "double" and "int" are mapped to Scheme flonums and (suitably bounded) Scheme exact integers respectively. |
454 | | |
455 | | ||Scheme name||C signature||Comments|| |
456 | | ||`flacosh`||`double acosh(double)`||hyperbolic arc cosine|| |
457 | | ||`flasinh`||`double asinh(double)`||hyperbolic arc sine|| |
458 | | ||`flatanh`||`double atanh(double)`||hyperbolic arc tangent|| |
459 | | ||`flcbrt`||`double cbrt(double);`||cube root|| |
460 | | ||`flcomplementary-error-function`||`double erfc(double)`||-|| |
461 | | ||`flcopy-sign`||`double copysign(double x, double y)`||result has magnitude of x and sign of y|| |
462 | | ||`flcosh`||`double cosh(double)`||hyperbolic cosine|| |
463 | | ||`flmake-flonum`||`double ldexp(double x, int n)`||x*2^n^|| |
464 | | ||`flerror-function`||`double erf(double)`||-|| |
465 | | ||`flexp`||`double exp(double)`||e^x^|| |
466 | | ||`flexp-binary`||`double exp,,2,,(double)`||base-2 exponential|| |
467 | | ||`flexp-minus-1`||`double expm1(double)`||e^x^-1|| |
468 | | ||`flexponent`||`double logb(double x)`||the exponent of x, which is the integral part of log_r(|x|), as a signed floating-point value, for non-zero x, where r is the radix of the machine's floating-point arithmetic|| |
469 | | ||`flfirst-bessel-order-0`||`double j0(double)`||bessel function of the first kind, order 0|| |
470 | | ||`flfirst-bessel-order-1`||`double j1(double)`||bessel function of the first kind, order 1|| |
471 | | ||`flfirst-bessel`||`double jn(int n, double)`||bessel function of the first kind, order n|| |
472 | | ||`flfraction-exponent`||`double modf(double, double *)`||returns two values, fraction and int exponent|| |
473 | | ||`flgamma`||`double tgamma(double)`||-|| |
474 | | ||`flhypotenuse`||`double hypot(double, double)`||sqrt(x^2^+y^2^)|| |
475 | | ||`flinteger-exponent`||`int ilogb(double)`||binary log as int|| |
476 | | ||`fllog-binary`||`double log2(double)`||log base 2|| |
477 | | ||`fllog-decimal`||`double log10(double)`||log base 10|| |
478 | | ||`fllog-gamma`||`double lgamma(double)`||returns two values, log(|gamma(x)|) and sgn(gamma(x))|| |
479 | | ||`fllog-one-plus`||`double log1p(double x)`||log (1+x)|| |
480 | | ||`flmultiply-add`||`double fma(double a, double b, double c)`||a*b+c|| |
481 | | ||`flnext-after`||`double nextafter(double, double)`||next flonum following x in the direction of y|| |
482 | | ||`flnormalized-fraction-exponent`||`double frexp(double, int *)`||returns two values, fraction in range [1/2,1) and int exponent|| |
483 | | ||`flpositive-difference`||`double fdim(double, double)`||-|| |
484 | | ||`flremquo`||`double remquo(double, double, int *)`||returns two values, rounded remainder and low-order ''n'' bits of the quotient (''n'' is implementation-defined) |
485 | | ||`flscalbn`||`double scalbn(double x, int y)`||x*r^y^, where r is the machine float radix|| |
486 | | ||`flsecond-bessel-order-0`||`double y0(double)`||bessel function of the second kind, order 0|| |
487 | | ||`flsecond-bessel-order-1`||`double y1(double)`||bessel function of the second kind, order 1|| |
488 | | ||`flsecond-bessel`||`double yn(int n, double)`||bessel function of the second kind, order ''n''|| |
489 | | ||`flsinh`||`double sinh(double)`||hyperbolic sine|| |
490 | | ||`fltanh`||`double tanh(double)`||hyperbolic tangent|| |
491 | | |
492 | | |
493 | | == General remarks == |
494 | | |
495 | | In the event that these operations do not yield a real result for the given arguments, the result may be `+nan.0`, or may be some unspecified flonum. |
496 | | |
497 | | Implementations that use IEEE binary floating-point arithmetic should follow the relevant standards for these procedures. |
498 | | |
| 362 | === NaN functions === |
| 363 | |
| 364 | The following functions are applicable not only to flonum NaNs but to all inexact real NaNs, which is why their names do not begin with `fl`. |
| 365 | |
| 366 | `(make-nan `''payload''`)` |
| 367 | |
| 368 | Returns a NaN, using the exact integer ''payload'' in an implementation-defined way to generate the payload bits. In particular, the sign bit of the NaN is set from the sign of `payload`. If the implementation does not support NaNs, it is an error. |
| 369 | |
| 370 | `(nan-payload `''nan''`)` |
| 371 | |
| 372 | Returns the payload of ''nan''. |
| 373 | |
| 374 | `(nan-signaling? `''nan''`)` |
| 375 | |
| 376 | Returns `#t` if ''nan'' is a signaling NaN, and `#f` otherwise. This function is required because different floating-point processors implement the signaling bit in different ways: on most processors, the most significant bit of the payload is clear if the NaN is signaling, but on the PA-RISC and MIPS processors it is set. |
| 377 | |
| 378 | `(nan= `''x y''`)` |
| 379 | |
| 380 | Returns `#t` if ''x'' and ''y'' are both NaNs the same payload. |
| 381 | |
| 382 | |
| 383 | |
| 384 | |