]>
Commit | Line | Data |
---|---|---|
f2b60f7d | 1 | //! Constants for the `f64` double-precision floating point type. |
c1a9b12d | 2 | //! |
29967ef6 | 3 | //! *[See also the `f64` primitive type](primitive@f64).* |
94b46f34 XL |
4 | //! |
5 | //! Mathematically significant numbers are provided in the `consts` sub-module. | |
74b04a01 | 6 | //! |
5869c6ff XL |
7 | //! For the constants defined directly in this module |
8 | //! (as distinct from those defined in the `consts` sub-module), | |
9 | //! new code should instead use the associated constants | |
10 | //! defined directly on the `f64` type. | |
970d7e83 | 11 | |
85aaf69f | 12 | #![stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 13 | #![allow(missing_docs)] |
970d7e83 | 14 | |
1b1a35ee XL |
15 | #[cfg(test)] |
16 | mod tests; | |
17 | ||
9cc50fc6 | 18 | #[cfg(not(test))] |
532ac7d7 | 19 | use crate::intrinsics; |
9cc50fc6 | 20 | #[cfg(not(test))] |
532ac7d7 | 21 | use crate::sys::cmath; |
1a4d82fc | 22 | |
92a42be0 | 23 | #[stable(feature = "rust1", since = "1.0.0")] |
5869c6ff XL |
24 | #[allow(deprecated, deprecated_in_future)] |
25 | pub use core::f64::{ | |
26 | consts, DIGITS, EPSILON, INFINITY, MANTISSA_DIGITS, MAX, MAX_10_EXP, MAX_EXP, MIN, MIN_10_EXP, | |
27 | MIN_EXP, MIN_POSITIVE, NAN, NEG_INFINITY, RADIX, | |
28 | }; | |
1a4d82fc | 29 | |
c34b1796 | 30 | #[cfg(not(test))] |
c34b1796 | 31 | impl f64 { |
04454e1e | 32 | /// Returns the largest integer less than or equal to `self`. |
c34b1796 | 33 | /// |
94b46f34 XL |
34 | /// # Examples |
35 | /// | |
c34b1796 | 36 | /// ``` |
532ac7d7 | 37 | /// let f = 3.7_f64; |
c34b1796 | 38 | /// let g = 3.0_f64; |
532ac7d7 | 39 | /// let h = -3.7_f64; |
c34b1796 AL |
40 | /// |
41 | /// assert_eq!(f.floor(), 3.0); | |
42 | /// assert_eq!(g.floor(), 3.0); | |
532ac7d7 | 43 | /// assert_eq!(h.floor(), -4.0); |
c34b1796 | 44 | /// ``` |
04454e1e | 45 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 46 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
47 | #[stable(feature = "rust1", since = "1.0.0")] |
48 | #[inline] | |
e9174d1e SL |
49 | pub fn floor(self) -> f64 { |
50 | unsafe { intrinsics::floorf64(self) } | |
51 | } | |
970d7e83 | 52 | |
04454e1e | 53 | /// Returns the smallest integer greater than or equal to `self`. |
c34b1796 | 54 | /// |
94b46f34 XL |
55 | /// # Examples |
56 | /// | |
c34b1796 AL |
57 | /// ``` |
58 | /// let f = 3.01_f64; | |
59 | /// let g = 4.0_f64; | |
60 | /// | |
61 | /// assert_eq!(f.ceil(), 4.0); | |
62 | /// assert_eq!(g.ceil(), 4.0); | |
63 | /// ``` | |
04454e1e | 64 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 65 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
66 | #[stable(feature = "rust1", since = "1.0.0")] |
67 | #[inline] | |
e9174d1e SL |
68 | pub fn ceil(self) -> f64 { |
69 | unsafe { intrinsics::ceilf64(self) } | |
70 | } | |
970d7e83 | 71 | |
9ffffee4 FG |
72 | /// Returns the nearest integer to `self`. If a value is half-way between two |
73 | /// integers, round away from `0.0`. | |
c34b1796 | 74 | /// |
94b46f34 XL |
75 | /// # Examples |
76 | /// | |
c34b1796 AL |
77 | /// ``` |
78 | /// let f = 3.3_f64; | |
79 | /// let g = -3.3_f64; | |
487cf647 | 80 | /// let h = -3.7_f64; |
c34b1796 AL |
81 | /// |
82 | /// assert_eq!(f.round(), 3.0); | |
83 | /// assert_eq!(g.round(), -3.0); | |
487cf647 | 84 | /// assert_eq!(h.round(), -4.0); |
c34b1796 | 85 | /// ``` |
04454e1e | 86 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 87 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
88 | #[stable(feature = "rust1", since = "1.0.0")] |
89 | #[inline] | |
e9174d1e SL |
90 | pub fn round(self) -> f64 { |
91 | unsafe { intrinsics::roundf64(self) } | |
92 | } | |
970d7e83 | 93 | |
04454e1e FG |
94 | /// Returns the integer part of `self`. |
95 | /// This means that non-integer numbers are always truncated towards zero. | |
c34b1796 | 96 | /// |
94b46f34 XL |
97 | /// # Examples |
98 | /// | |
c34b1796 | 99 | /// ``` |
532ac7d7 XL |
100 | /// let f = 3.7_f64; |
101 | /// let g = 3.0_f64; | |
102 | /// let h = -3.7_f64; | |
c34b1796 AL |
103 | /// |
104 | /// assert_eq!(f.trunc(), 3.0); | |
532ac7d7 XL |
105 | /// assert_eq!(g.trunc(), 3.0); |
106 | /// assert_eq!(h.trunc(), -3.0); | |
c34b1796 | 107 | /// ``` |
04454e1e | 108 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 109 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
110 | #[stable(feature = "rust1", since = "1.0.0")] |
111 | #[inline] | |
e9174d1e SL |
112 | pub fn trunc(self) -> f64 { |
113 | unsafe { intrinsics::truncf64(self) } | |
114 | } | |
970d7e83 | 115 | |
04454e1e | 116 | /// Returns the fractional part of `self`. |
c34b1796 | 117 | /// |
94b46f34 XL |
118 | /// # Examples |
119 | /// | |
c34b1796 | 120 | /// ``` |
dfeec247 XL |
121 | /// let x = 3.6_f64; |
122 | /// let y = -3.6_f64; | |
123 | /// let abs_difference_x = (x.fract() - 0.6).abs(); | |
124 | /// let abs_difference_y = (y.fract() - (-0.6)).abs(); | |
c34b1796 AL |
125 | /// |
126 | /// assert!(abs_difference_x < 1e-10); | |
127 | /// assert!(abs_difference_y < 1e-10); | |
128 | /// ``` | |
04454e1e | 129 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 130 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
131 | #[stable(feature = "rust1", since = "1.0.0")] |
132 | #[inline] | |
60c5eb7d XL |
133 | pub fn fract(self) -> f64 { |
134 | self - self.trunc() | |
135 | } | |
970d7e83 | 136 | |
04454e1e | 137 | /// Computes the absolute value of `self`. |
c34b1796 | 138 | /// |
94b46f34 XL |
139 | /// # Examples |
140 | /// | |
c34b1796 | 141 | /// ``` |
c34b1796 AL |
142 | /// let x = 3.5_f64; |
143 | /// let y = -3.5_f64; | |
144 | /// | |
145 | /// let abs_difference_x = (x.abs() - x).abs(); | |
146 | /// let abs_difference_y = (y.abs() - (-y)).abs(); | |
147 | /// | |
148 | /// assert!(abs_difference_x < 1e-10); | |
149 | /// assert!(abs_difference_y < 1e-10); | |
150 | /// | |
151 | /// assert!(f64::NAN.abs().is_nan()); | |
152 | /// ``` | |
04454e1e | 153 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 154 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
155 | #[stable(feature = "rust1", since = "1.0.0")] |
156 | #[inline] | |
83c7162d XL |
157 | pub fn abs(self) -> f64 { |
158 | unsafe { intrinsics::fabsf64(self) } | |
159 | } | |
970d7e83 | 160 | |
c34b1796 AL |
161 | /// Returns a number that represents the sign of `self`. |
162 | /// | |
163 | /// - `1.0` if the number is positive, `+0.0` or `INFINITY` | |
164 | /// - `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY` | |
04454e1e | 165 | /// - NaN if the number is NaN |
c34b1796 | 166 | /// |
94b46f34 XL |
167 | /// # Examples |
168 | /// | |
c34b1796 | 169 | /// ``` |
c34b1796 AL |
170 | /// let f = 3.5_f64; |
171 | /// | |
172 | /// assert_eq!(f.signum(), 1.0); | |
173 | /// assert_eq!(f64::NEG_INFINITY.signum(), -1.0); | |
174 | /// | |
175 | /// assert!(f64::NAN.signum().is_nan()); | |
176 | /// ``` | |
04454e1e | 177 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 178 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
179 | #[stable(feature = "rust1", since = "1.0.0")] |
180 | #[inline] | |
83c7162d | 181 | pub fn signum(self) -> f64 { |
f9f354fc | 182 | if self.is_nan() { Self::NAN } else { 1.0_f64.copysign(self) } |
83c7162d | 183 | } |
970d7e83 | 184 | |
0bf4aa26 | 185 | /// Returns a number composed of the magnitude of `self` and the sign of |
532ac7d7 | 186 | /// `sign`. |
0bf4aa26 | 187 | /// |
532ac7d7 | 188 | /// Equal to `self` if the sign of `self` and `sign` are the same, otherwise |
04454e1e FG |
189 | /// equal to `-self`. If `self` is a NaN, then a NaN with the sign bit of |
190 | /// `sign` is returned. Note, however, that conserving the sign bit on NaN | |
191 | /// across arithmetical operations is not generally guaranteed. | |
192 | /// See [explanation of NaN as a special value](primitive@f32) for more info. | |
0bf4aa26 XL |
193 | /// |
194 | /// # Examples | |
195 | /// | |
196 | /// ``` | |
0bf4aa26 XL |
197 | /// let f = 3.5_f64; |
198 | /// | |
199 | /// assert_eq!(f.copysign(0.42), 3.5_f64); | |
200 | /// assert_eq!(f.copysign(-0.42), -3.5_f64); | |
201 | /// assert_eq!((-f).copysign(0.42), 3.5_f64); | |
202 | /// assert_eq!((-f).copysign(-0.42), -3.5_f64); | |
203 | /// | |
204 | /// assert!(f64::NAN.copysign(1.0).is_nan()); | |
205 | /// ``` | |
04454e1e | 206 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 207 | #[must_use = "method returns a new number and does not mutate the original value"] |
532ac7d7 | 208 | #[stable(feature = "copysign", since = "1.35.0")] |
60c5eb7d | 209 | #[inline] |
532ac7d7 XL |
210 | pub fn copysign(self, sign: f64) -> f64 { |
211 | unsafe { intrinsics::copysignf64(self, sign) } | |
0bf4aa26 XL |
212 | } |
213 | ||
c34b1796 | 214 | /// Fused multiply-add. Computes `(self * a) + b` with only one rounding |
94b46f34 XL |
215 | /// error, yielding a more accurate result than an unfused multiply-add. |
216 | /// | |
fc512014 XL |
217 | /// Using `mul_add` *may* be more performant than an unfused multiply-add if |
218 | /// the target architecture has a dedicated `fma` CPU instruction. However, | |
219 | /// this is not always true, and will be heavily dependant on designing | |
220 | /// algorithms with specific target hardware in mind. | |
94b46f34 XL |
221 | /// |
222 | /// # Examples | |
c34b1796 AL |
223 | /// |
224 | /// ``` | |
225 | /// let m = 10.0_f64; | |
226 | /// let x = 4.0_f64; | |
227 | /// let b = 60.0_f64; | |
228 | /// | |
229 | /// // 100.0 | |
e1599b0c | 230 | /// let abs_difference = (m.mul_add(x, b) - ((m * x) + b)).abs(); |
c34b1796 AL |
231 | /// |
232 | /// assert!(abs_difference < 1e-10); | |
233 | /// ``` | |
04454e1e | 234 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 235 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
236 | #[stable(feature = "rust1", since = "1.0.0")] |
237 | #[inline] | |
e9174d1e SL |
238 | pub fn mul_add(self, a: f64, b: f64) -> f64 { |
239 | unsafe { intrinsics::fmaf64(self, a, b) } | |
240 | } | |
85aaf69f | 241 | |
0731742a | 242 | /// Calculates Euclidean division, the matching method for `rem_euclid`. |
83c7162d XL |
243 | /// |
244 | /// This computes the integer `n` such that | |
0731742a | 245 | /// `self = n * rhs + self.rem_euclid(rhs)`. |
83c7162d XL |
246 | /// In other words, the result is `self / rhs` rounded to the integer `n` |
247 | /// such that `self >= n * rhs`. | |
c34b1796 | 248 | /// |
94b46f34 XL |
249 | /// # Examples |
250 | /// | |
c34b1796 | 251 | /// ``` |
83c7162d XL |
252 | /// let a: f64 = 7.0; |
253 | /// let b = 4.0; | |
0731742a XL |
254 | /// assert_eq!(a.div_euclid(b), 1.0); // 7.0 > 4.0 * 1.0 |
255 | /// assert_eq!((-a).div_euclid(b), -2.0); // -7.0 >= 4.0 * -2.0 | |
256 | /// assert_eq!(a.div_euclid(-b), -1.0); // 7.0 >= -4.0 * -1.0 | |
257 | /// assert_eq!((-a).div_euclid(-b), 2.0); // -7.0 >= -4.0 * 2.0 | |
83c7162d | 258 | /// ``` |
04454e1e | 259 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 260 | #[must_use = "method returns a new number and does not mutate the original value"] |
83c7162d | 261 | #[inline] |
416331ca | 262 | #[stable(feature = "euclidean_division", since = "1.38.0")] |
0731742a | 263 | pub fn div_euclid(self, rhs: f64) -> f64 { |
83c7162d XL |
264 | let q = (self / rhs).trunc(); |
265 | if self % rhs < 0.0 { | |
e1599b0c | 266 | return if rhs > 0.0 { q - 1.0 } else { q + 1.0 }; |
83c7162d XL |
267 | } |
268 | q | |
269 | } | |
270 | ||
0731742a | 271 | /// Calculates the least nonnegative remainder of `self (mod rhs)`. |
83c7162d | 272 | /// |
8faf50e0 | 273 | /// In particular, the return value `r` satisfies `0.0 <= r < rhs.abs()` in |
9fa01778 | 274 | /// most cases. However, due to a floating point round-off error it can |
8faf50e0 XL |
275 | /// result in `r == rhs.abs()`, violating the mathematical definition, if |
276 | /// `self` is much smaller than `rhs.abs()` in magnitude and `self < 0.0`. | |
277 | /// This result is not an element of the function's codomain, but it is the | |
278 | /// closest floating point number in the real numbers and thus fulfills the | |
0731742a | 279 | /// property `self == self.div_euclid(rhs) * rhs + self.rem_euclid(rhs)` |
487cf647 | 280 | /// approximately. |
c34b1796 | 281 | /// |
94b46f34 XL |
282 | /// # Examples |
283 | /// | |
c34b1796 | 284 | /// ``` |
83c7162d XL |
285 | /// let a: f64 = 7.0; |
286 | /// let b = 4.0; | |
0731742a XL |
287 | /// assert_eq!(a.rem_euclid(b), 3.0); |
288 | /// assert_eq!((-a).rem_euclid(b), 1.0); | |
289 | /// assert_eq!(a.rem_euclid(-b), 3.0); | |
290 | /// assert_eq!((-a).rem_euclid(-b), 1.0); | |
8faf50e0 | 291 | /// // limitation due to round-off error |
ba9703b0 | 292 | /// assert!((-f64::EPSILON).rem_euclid(3.0) != 0.0); |
83c7162d | 293 | /// ``` |
04454e1e | 294 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 295 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 | 296 | #[inline] |
416331ca | 297 | #[stable(feature = "euclidean_division", since = "1.38.0")] |
0731742a | 298 | pub fn rem_euclid(self, rhs: f64) -> f64 { |
83c7162d | 299 | let r = self % rhs; |
60c5eb7d | 300 | if r < 0.0 { r + rhs.abs() } else { r } |
83c7162d | 301 | } |
c34b1796 | 302 | |
9346a6ac | 303 | /// Raises a number to an integer power. |
c34b1796 | 304 | /// |
04454e1e FG |
305 | /// Using this function is generally faster than using `powf`. |
306 | /// It might have a different sequence of rounding operations than `powf`, | |
307 | /// so the results are not guaranteed to agree. | |
c34b1796 | 308 | /// |
94b46f34 XL |
309 | /// # Examples |
310 | /// | |
c34b1796 AL |
311 | /// ``` |
312 | /// let x = 2.0_f64; | |
e1599b0c | 313 | /// let abs_difference = (x.powi(2) - (x * x)).abs(); |
c34b1796 AL |
314 | /// |
315 | /// assert!(abs_difference < 1e-10); | |
316 | /// ``` | |
04454e1e | 317 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 318 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
319 | #[stable(feature = "rust1", since = "1.0.0")] |
320 | #[inline] | |
83c7162d XL |
321 | pub fn powi(self, n: i32) -> f64 { |
322 | unsafe { intrinsics::powif64(self, n) } | |
323 | } | |
c34b1796 | 324 | |
9346a6ac | 325 | /// Raises a number to a floating point power. |
c34b1796 | 326 | /// |
94b46f34 XL |
327 | /// # Examples |
328 | /// | |
c34b1796 AL |
329 | /// ``` |
330 | /// let x = 2.0_f64; | |
e1599b0c | 331 | /// let abs_difference = (x.powf(2.0) - (x * x)).abs(); |
c34b1796 AL |
332 | /// |
333 | /// assert!(abs_difference < 1e-10); | |
334 | /// ``` | |
04454e1e | 335 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 336 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
337 | #[stable(feature = "rust1", since = "1.0.0")] |
338 | #[inline] | |
e9174d1e SL |
339 | pub fn powf(self, n: f64) -> f64 { |
340 | unsafe { intrinsics::powf64(self, n) } | |
341 | } | |
c34b1796 | 342 | |
dfeec247 | 343 | /// Returns the square root of a number. |
c34b1796 | 344 | /// |
136023e0 | 345 | /// Returns NaN if `self` is a negative number other than `-0.0`. |
c34b1796 | 346 | /// |
94b46f34 XL |
347 | /// # Examples |
348 | /// | |
c34b1796 AL |
349 | /// ``` |
350 | /// let positive = 4.0_f64; | |
351 | /// let negative = -4.0_f64; | |
136023e0 | 352 | /// let negative_zero = -0.0_f64; |
c34b1796 AL |
353 | /// |
354 | /// let abs_difference = (positive.sqrt() - 2.0).abs(); | |
355 | /// | |
356 | /// assert!(abs_difference < 1e-10); | |
357 | /// assert!(negative.sqrt().is_nan()); | |
136023e0 | 358 | /// assert!(negative_zero.sqrt() == negative_zero); |
c34b1796 | 359 | /// ``` |
04454e1e | 360 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 361 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
362 | #[stable(feature = "rust1", since = "1.0.0")] |
363 | #[inline] | |
e9174d1e | 364 | pub fn sqrt(self) -> f64 { |
dfeec247 | 365 | unsafe { intrinsics::sqrtf64(self) } |
e9174d1e | 366 | } |
c34b1796 | 367 | |
c34b1796 AL |
368 | /// Returns `e^(self)`, (the exponential function). |
369 | /// | |
94b46f34 XL |
370 | /// # Examples |
371 | /// | |
c34b1796 AL |
372 | /// ``` |
373 | /// let one = 1.0_f64; | |
374 | /// // e^1 | |
375 | /// let e = one.exp(); | |
376 | /// | |
377 | /// // ln(e) - 1 == 0 | |
378 | /// let abs_difference = (e.ln() - 1.0).abs(); | |
379 | /// | |
380 | /// assert!(abs_difference < 1e-10); | |
381 | /// ``` | |
04454e1e | 382 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 383 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
384 | #[stable(feature = "rust1", since = "1.0.0")] |
385 | #[inline] | |
e9174d1e SL |
386 | pub fn exp(self) -> f64 { |
387 | unsafe { intrinsics::expf64(self) } | |
388 | } | |
c34b1796 AL |
389 | |
390 | /// Returns `2^(self)`. | |
391 | /// | |
94b46f34 XL |
392 | /// # Examples |
393 | /// | |
c34b1796 AL |
394 | /// ``` |
395 | /// let f = 2.0_f64; | |
396 | /// | |
397 | /// // 2^2 - 4 == 0 | |
398 | /// let abs_difference = (f.exp2() - 4.0).abs(); | |
399 | /// | |
400 | /// assert!(abs_difference < 1e-10); | |
401 | /// ``` | |
04454e1e | 402 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 403 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
404 | #[stable(feature = "rust1", since = "1.0.0")] |
405 | #[inline] | |
e9174d1e SL |
406 | pub fn exp2(self) -> f64 { |
407 | unsafe { intrinsics::exp2f64(self) } | |
408 | } | |
c34b1796 AL |
409 | |
410 | /// Returns the natural logarithm of the number. | |
411 | /// | |
94b46f34 XL |
412 | /// # Examples |
413 | /// | |
c34b1796 AL |
414 | /// ``` |
415 | /// let one = 1.0_f64; | |
416 | /// // e^1 | |
417 | /// let e = one.exp(); | |
418 | /// | |
419 | /// // ln(e) - 1 == 0 | |
420 | /// let abs_difference = (e.ln() - 1.0).abs(); | |
421 | /// | |
422 | /// assert!(abs_difference < 1e-10); | |
423 | /// ``` | |
04454e1e | 424 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 425 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
426 | #[stable(feature = "rust1", since = "1.0.0")] |
427 | #[inline] | |
e9174d1e | 428 | pub fn ln(self) -> f64 { |
60c5eb7d | 429 | self.log_wrapper(|n| unsafe { intrinsics::logf64(n) }) |
e9174d1e | 430 | } |
c34b1796 AL |
431 | |
432 | /// Returns the logarithm of the number with respect to an arbitrary base. | |
433 | /// | |
94222f64 | 434 | /// The result might not be correctly rounded owing to implementation details; |
2c00a5a8 XL |
435 | /// `self.log2()` can produce more accurate results for base 2, and |
436 | /// `self.log10()` can produce more accurate results for base 10. | |
c34b1796 | 437 | /// |
94b46f34 XL |
438 | /// # Examples |
439 | /// | |
2c00a5a8 | 440 | /// ``` |
60c5eb7d | 441 | /// let twenty_five = 25.0_f64; |
c34b1796 | 442 | /// |
60c5eb7d XL |
443 | /// // log5(25) - 2 == 0 |
444 | /// let abs_difference = (twenty_five.log(5.0) - 2.0).abs(); | |
c34b1796 | 445 | /// |
2c00a5a8 | 446 | /// assert!(abs_difference < 1e-10); |
c34b1796 | 447 | /// ``` |
04454e1e | 448 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 449 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
450 | #[stable(feature = "rust1", since = "1.0.0")] |
451 | #[inline] | |
60c5eb7d XL |
452 | pub fn log(self, base: f64) -> f64 { |
453 | self.ln() / base.ln() | |
454 | } | |
c34b1796 AL |
455 | |
456 | /// Returns the base 2 logarithm of the number. | |
457 | /// | |
94b46f34 XL |
458 | /// # Examples |
459 | /// | |
c34b1796 | 460 | /// ``` |
60c5eb7d | 461 | /// let four = 4.0_f64; |
c34b1796 | 462 | /// |
60c5eb7d XL |
463 | /// // log2(4) - 2 == 0 |
464 | /// let abs_difference = (four.log2() - 2.0).abs(); | |
c34b1796 AL |
465 | /// |
466 | /// assert!(abs_difference < 1e-10); | |
467 | /// ``` | |
04454e1e | 468 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 469 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
470 | #[stable(feature = "rust1", since = "1.0.0")] |
471 | #[inline] | |
e9174d1e | 472 | pub fn log2(self) -> f64 { |
a7813a04 XL |
473 | self.log_wrapper(|n| { |
474 | #[cfg(target_os = "android")] | |
60c5eb7d | 475 | return crate::sys::android::log2f64(n); |
a7813a04 | 476 | #[cfg(not(target_os = "android"))] |
60c5eb7d | 477 | return unsafe { intrinsics::log2f64(n) }; |
a7813a04 | 478 | }) |
e9174d1e | 479 | } |
c34b1796 AL |
480 | |
481 | /// Returns the base 10 logarithm of the number. | |
482 | /// | |
94b46f34 XL |
483 | /// # Examples |
484 | /// | |
c34b1796 | 485 | /// ``` |
60c5eb7d | 486 | /// let hundred = 100.0_f64; |
c34b1796 | 487 | /// |
60c5eb7d XL |
488 | /// // log10(100) - 2 == 0 |
489 | /// let abs_difference = (hundred.log10() - 2.0).abs(); | |
c34b1796 AL |
490 | /// |
491 | /// assert!(abs_difference < 1e-10); | |
492 | /// ``` | |
04454e1e | 493 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 494 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
495 | #[stable(feature = "rust1", since = "1.0.0")] |
496 | #[inline] | |
e9174d1e | 497 | pub fn log10(self) -> f64 { |
60c5eb7d | 498 | self.log_wrapper(|n| unsafe { intrinsics::log10f64(n) }) |
e9174d1e | 499 | } |
c34b1796 | 500 | |
c34b1796 AL |
501 | /// The positive difference of two numbers. |
502 | /// | |
503 | /// * If `self <= other`: `0:0` | |
504 | /// * Else: `self - other` | |
505 | /// | |
94b46f34 XL |
506 | /// # Examples |
507 | /// | |
c34b1796 AL |
508 | /// ``` |
509 | /// let x = 3.0_f64; | |
510 | /// let y = -3.0_f64; | |
511 | /// | |
512 | /// let abs_difference_x = (x.abs_sub(1.0) - 2.0).abs(); | |
513 | /// let abs_difference_y = (y.abs_sub(1.0) - 0.0).abs(); | |
514 | /// | |
515 | /// assert!(abs_difference_x < 1e-10); | |
516 | /// assert!(abs_difference_y < 1e-10); | |
517 | /// ``` | |
04454e1e | 518 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 519 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
520 | #[stable(feature = "rust1", since = "1.0.0")] |
521 | #[inline] | |
04454e1e | 522 | #[deprecated( |
60c5eb7d | 523 | since = "1.10.0", |
04454e1e FG |
524 | note = "you probably meant `(self - other).abs()`: \ |
525 | this operation is `(self - other).max(0.0)` \ | |
526 | except that `abs_sub` also propagates NaNs (also \ | |
527 | known as `fdim` in C). If you truly need the positive \ | |
528 | difference, consider using that expression or the C function \ | |
529 | `fdim`, depending on how you wish to handle NaN (please consider \ | |
530 | filing an issue describing your use-case too)." | |
60c5eb7d | 531 | )] |
e1599b0c XL |
532 | pub fn abs_sub(self, other: f64) -> f64 { |
533 | unsafe { cmath::fdim(self, other) } | |
534 | } | |
c34b1796 | 535 | |
6a06907d | 536 | /// Returns the cube root of a number. |
c34b1796 | 537 | /// |
94b46f34 XL |
538 | /// # Examples |
539 | /// | |
c34b1796 AL |
540 | /// ``` |
541 | /// let x = 8.0_f64; | |
542 | /// | |
543 | /// // x^(1/3) - 2 == 0 | |
544 | /// let abs_difference = (x.cbrt() - 2.0).abs(); | |
545 | /// | |
546 | /// assert!(abs_difference < 1e-10); | |
547 | /// ``` | |
04454e1e | 548 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 549 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
550 | #[stable(feature = "rust1", since = "1.0.0")] |
551 | #[inline] | |
552 | pub fn cbrt(self) -> f64 { | |
553 | unsafe { cmath::cbrt(self) } | |
554 | } | |
555 | ||
9346a6ac | 556 | /// Calculates the length of the hypotenuse of a right-angle triangle given |
c34b1796 AL |
557 | /// legs of length `x` and `y`. |
558 | /// | |
94b46f34 XL |
559 | /// # Examples |
560 | /// | |
c34b1796 AL |
561 | /// ``` |
562 | /// let x = 2.0_f64; | |
563 | /// let y = 3.0_f64; | |
564 | /// | |
565 | /// // sqrt(x^2 + y^2) | |
566 | /// let abs_difference = (x.hypot(y) - (x.powi(2) + y.powi(2)).sqrt()).abs(); | |
567 | /// | |
568 | /// assert!(abs_difference < 1e-10); | |
569 | /// ``` | |
04454e1e | 570 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 571 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
572 | #[stable(feature = "rust1", since = "1.0.0")] |
573 | #[inline] | |
574 | pub fn hypot(self, other: f64) -> f64 { | |
575 | unsafe { cmath::hypot(self, other) } | |
576 | } | |
577 | ||
578 | /// Computes the sine of a number (in radians). | |
579 | /// | |
94b46f34 XL |
580 | /// # Examples |
581 | /// | |
c34b1796 | 582 | /// ``` |
ba9703b0 | 583 | /// let x = std::f64::consts::FRAC_PI_2; |
c34b1796 AL |
584 | /// |
585 | /// let abs_difference = (x.sin() - 1.0).abs(); | |
586 | /// | |
587 | /// assert!(abs_difference < 1e-10); | |
588 | /// ``` | |
04454e1e | 589 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 590 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
591 | #[stable(feature = "rust1", since = "1.0.0")] |
592 | #[inline] | |
593 | pub fn sin(self) -> f64 { | |
594 | unsafe { intrinsics::sinf64(self) } | |
595 | } | |
596 | ||
597 | /// Computes the cosine of a number (in radians). | |
598 | /// | |
94b46f34 XL |
599 | /// # Examples |
600 | /// | |
c34b1796 | 601 | /// ``` |
ba9703b0 | 602 | /// let x = 2.0 * std::f64::consts::PI; |
c34b1796 AL |
603 | /// |
604 | /// let abs_difference = (x.cos() - 1.0).abs(); | |
605 | /// | |
606 | /// assert!(abs_difference < 1e-10); | |
607 | /// ``` | |
04454e1e | 608 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 609 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
610 | #[stable(feature = "rust1", since = "1.0.0")] |
611 | #[inline] | |
612 | pub fn cos(self) -> f64 { | |
613 | unsafe { intrinsics::cosf64(self) } | |
614 | } | |
615 | ||
616 | /// Computes the tangent of a number (in radians). | |
617 | /// | |
94b46f34 XL |
618 | /// # Examples |
619 | /// | |
c34b1796 | 620 | /// ``` |
ba9703b0 | 621 | /// let x = std::f64::consts::FRAC_PI_4; |
c34b1796 AL |
622 | /// let abs_difference = (x.tan() - 1.0).abs(); |
623 | /// | |
624 | /// assert!(abs_difference < 1e-14); | |
625 | /// ``` | |
04454e1e | 626 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 627 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
628 | #[stable(feature = "rust1", since = "1.0.0")] |
629 | #[inline] | |
630 | pub fn tan(self) -> f64 { | |
631 | unsafe { cmath::tan(self) } | |
632 | } | |
633 | ||
634 | /// Computes the arcsine of a number. Return value is in radians in | |
635 | /// the range [-pi/2, pi/2] or NaN if the number is outside the range | |
636 | /// [-1, 1]. | |
637 | /// | |
94b46f34 XL |
638 | /// # Examples |
639 | /// | |
c34b1796 | 640 | /// ``` |
ba9703b0 | 641 | /// let f = std::f64::consts::FRAC_PI_2; |
c34b1796 AL |
642 | /// |
643 | /// // asin(sin(pi/2)) | |
ba9703b0 | 644 | /// let abs_difference = (f.sin().asin() - std::f64::consts::FRAC_PI_2).abs(); |
c34b1796 AL |
645 | /// |
646 | /// assert!(abs_difference < 1e-10); | |
647 | /// ``` | |
04454e1e | 648 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 649 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
650 | #[stable(feature = "rust1", since = "1.0.0")] |
651 | #[inline] | |
652 | pub fn asin(self) -> f64 { | |
653 | unsafe { cmath::asin(self) } | |
654 | } | |
655 | ||
656 | /// Computes the arccosine of a number. Return value is in radians in | |
657 | /// the range [0, pi] or NaN if the number is outside the range | |
658 | /// [-1, 1]. | |
659 | /// | |
94b46f34 XL |
660 | /// # Examples |
661 | /// | |
c34b1796 | 662 | /// ``` |
ba9703b0 | 663 | /// let f = std::f64::consts::FRAC_PI_4; |
c34b1796 AL |
664 | /// |
665 | /// // acos(cos(pi/4)) | |
ba9703b0 | 666 | /// let abs_difference = (f.cos().acos() - std::f64::consts::FRAC_PI_4).abs(); |
c34b1796 AL |
667 | /// |
668 | /// assert!(abs_difference < 1e-10); | |
669 | /// ``` | |
04454e1e | 670 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 671 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
672 | #[stable(feature = "rust1", since = "1.0.0")] |
673 | #[inline] | |
674 | pub fn acos(self) -> f64 { | |
675 | unsafe { cmath::acos(self) } | |
676 | } | |
677 | ||
678 | /// Computes the arctangent of a number. Return value is in radians in the | |
679 | /// range [-pi/2, pi/2]; | |
680 | /// | |
94b46f34 XL |
681 | /// # Examples |
682 | /// | |
c34b1796 AL |
683 | /// ``` |
684 | /// let f = 1.0_f64; | |
685 | /// | |
686 | /// // atan(tan(1)) | |
687 | /// let abs_difference = (f.tan().atan() - 1.0).abs(); | |
688 | /// | |
689 | /// assert!(abs_difference < 1e-10); | |
690 | /// ``` | |
04454e1e | 691 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 692 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
693 | #[stable(feature = "rust1", since = "1.0.0")] |
694 | #[inline] | |
695 | pub fn atan(self) -> f64 { | |
696 | unsafe { cmath::atan(self) } | |
697 | } | |
698 | ||
0531ce1d | 699 | /// Computes the four quadrant arctangent of `self` (`y`) and `other` (`x`) in radians. |
c34b1796 AL |
700 | /// |
701 | /// * `x = 0`, `y = 0`: `0` | |
702 | /// * `x >= 0`: `arctan(y/x)` -> `[-pi/2, pi/2]` | |
703 | /// * `y >= 0`: `arctan(y/x) + pi` -> `(pi/2, pi]` | |
704 | /// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)` | |
705 | /// | |
94b46f34 XL |
706 | /// # Examples |
707 | /// | |
c34b1796 | 708 | /// ``` |
0531ce1d XL |
709 | /// // Positive angles measured counter-clockwise |
710 | /// // from positive x axis | |
711 | /// // -pi/4 radians (45 deg clockwise) | |
c34b1796 AL |
712 | /// let x1 = 3.0_f64; |
713 | /// let y1 = -3.0_f64; | |
714 | /// | |
0531ce1d | 715 | /// // 3pi/4 radians (135 deg counter-clockwise) |
c34b1796 AL |
716 | /// let x2 = -3.0_f64; |
717 | /// let y2 = 3.0_f64; | |
718 | /// | |
ba9703b0 XL |
719 | /// let abs_difference_1 = (y1.atan2(x1) - (-std::f64::consts::FRAC_PI_4)).abs(); |
720 | /// let abs_difference_2 = (y2.atan2(x2) - (3.0 * std::f64::consts::FRAC_PI_4)).abs(); | |
c34b1796 AL |
721 | /// |
722 | /// assert!(abs_difference_1 < 1e-10); | |
723 | /// assert!(abs_difference_2 < 1e-10); | |
724 | /// ``` | |
04454e1e | 725 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 726 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
727 | #[stable(feature = "rust1", since = "1.0.0")] |
728 | #[inline] | |
729 | pub fn atan2(self, other: f64) -> f64 { | |
730 | unsafe { cmath::atan2(self, other) } | |
731 | } | |
732 | ||
733 | /// Simultaneously computes the sine and cosine of the number, `x`. Returns | |
734 | /// `(sin(x), cos(x))`. | |
735 | /// | |
94b46f34 XL |
736 | /// # Examples |
737 | /// | |
c34b1796 | 738 | /// ``` |
ba9703b0 | 739 | /// let x = std::f64::consts::FRAC_PI_4; |
c34b1796 AL |
740 | /// let f = x.sin_cos(); |
741 | /// | |
742 | /// let abs_difference_0 = (f.0 - x.sin()).abs(); | |
743 | /// let abs_difference_1 = (f.1 - x.cos()).abs(); | |
744 | /// | |
745 | /// assert!(abs_difference_0 < 1e-10); | |
a7813a04 | 746 | /// assert!(abs_difference_1 < 1e-10); |
c34b1796 | 747 | /// ``` |
04454e1e | 748 | #[rustc_allow_incoherent_impl] |
c34b1796 AL |
749 | #[stable(feature = "rust1", since = "1.0.0")] |
750 | #[inline] | |
751 | pub fn sin_cos(self) -> (f64, f64) { | |
752 | (self.sin(), self.cos()) | |
753 | } | |
754 | ||
755 | /// Returns `e^(self) - 1` in a way that is accurate even if the | |
756 | /// number is close to zero. | |
757 | /// | |
94b46f34 XL |
758 | /// # Examples |
759 | /// | |
c34b1796 | 760 | /// ``` |
29967ef6 | 761 | /// let x = 1e-16_f64; |
c34b1796 | 762 | /// |
29967ef6 XL |
763 | /// // for very small x, e^x is approximately 1 + x + x^2 / 2 |
764 | /// let approx = x + x * x / 2.0; | |
765 | /// let abs_difference = (x.exp_m1() - approx).abs(); | |
c34b1796 | 766 | /// |
29967ef6 | 767 | /// assert!(abs_difference < 1e-20); |
c34b1796 | 768 | /// ``` |
04454e1e | 769 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 770 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
771 | #[stable(feature = "rust1", since = "1.0.0")] |
772 | #[inline] | |
773 | pub fn exp_m1(self) -> f64 { | |
774 | unsafe { cmath::expm1(self) } | |
775 | } | |
776 | ||
777 | /// Returns `ln(1+n)` (natural logarithm) more accurately than if | |
778 | /// the operations were performed separately. | |
779 | /// | |
94b46f34 XL |
780 | /// # Examples |
781 | /// | |
c34b1796 | 782 | /// ``` |
29967ef6 | 783 | /// let x = 1e-16_f64; |
c34b1796 | 784 | /// |
29967ef6 XL |
785 | /// // for very small x, ln(1 + x) is approximately x - x^2 / 2 |
786 | /// let approx = x - x * x / 2.0; | |
787 | /// let abs_difference = (x.ln_1p() - approx).abs(); | |
c34b1796 | 788 | /// |
29967ef6 | 789 | /// assert!(abs_difference < 1e-20); |
c34b1796 | 790 | /// ``` |
04454e1e | 791 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 792 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
793 | #[stable(feature = "rust1", since = "1.0.0")] |
794 | #[inline] | |
795 | pub fn ln_1p(self) -> f64 { | |
796 | unsafe { cmath::log1p(self) } | |
797 | } | |
798 | ||
799 | /// Hyperbolic sine function. | |
800 | /// | |
94b46f34 XL |
801 | /// # Examples |
802 | /// | |
c34b1796 | 803 | /// ``` |
ba9703b0 | 804 | /// let e = std::f64::consts::E; |
c34b1796 AL |
805 | /// let x = 1.0_f64; |
806 | /// | |
807 | /// let f = x.sinh(); | |
808 | /// // Solving sinh() at 1 gives `(e^2-1)/(2e)` | |
e1599b0c | 809 | /// let g = ((e * e) - 1.0) / (2.0 * e); |
c34b1796 AL |
810 | /// let abs_difference = (f - g).abs(); |
811 | /// | |
812 | /// assert!(abs_difference < 1e-10); | |
813 | /// ``` | |
04454e1e | 814 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 815 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
816 | #[stable(feature = "rust1", since = "1.0.0")] |
817 | #[inline] | |
818 | pub fn sinh(self) -> f64 { | |
819 | unsafe { cmath::sinh(self) } | |
820 | } | |
821 | ||
822 | /// Hyperbolic cosine function. | |
823 | /// | |
94b46f34 XL |
824 | /// # Examples |
825 | /// | |
c34b1796 | 826 | /// ``` |
ba9703b0 | 827 | /// let e = std::f64::consts::E; |
c34b1796 AL |
828 | /// let x = 1.0_f64; |
829 | /// let f = x.cosh(); | |
830 | /// // Solving cosh() at 1 gives this result | |
e1599b0c | 831 | /// let g = ((e * e) + 1.0) / (2.0 * e); |
c34b1796 AL |
832 | /// let abs_difference = (f - g).abs(); |
833 | /// | |
834 | /// // Same result | |
835 | /// assert!(abs_difference < 1.0e-10); | |
836 | /// ``` | |
04454e1e | 837 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 838 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
839 | #[stable(feature = "rust1", since = "1.0.0")] |
840 | #[inline] | |
841 | pub fn cosh(self) -> f64 { | |
842 | unsafe { cmath::cosh(self) } | |
843 | } | |
844 | ||
845 | /// Hyperbolic tangent function. | |
846 | /// | |
94b46f34 XL |
847 | /// # Examples |
848 | /// | |
c34b1796 | 849 | /// ``` |
ba9703b0 | 850 | /// let e = std::f64::consts::E; |
c34b1796 AL |
851 | /// let x = 1.0_f64; |
852 | /// | |
853 | /// let f = x.tanh(); | |
854 | /// // Solving tanh() at 1 gives `(1 - e^(-2))/(1 + e^(-2))` | |
e1599b0c | 855 | /// let g = (1.0 - e.powi(-2)) / (1.0 + e.powi(-2)); |
c34b1796 AL |
856 | /// let abs_difference = (f - g).abs(); |
857 | /// | |
858 | /// assert!(abs_difference < 1.0e-10); | |
859 | /// ``` | |
04454e1e | 860 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 861 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
862 | #[stable(feature = "rust1", since = "1.0.0")] |
863 | #[inline] | |
864 | pub fn tanh(self) -> f64 { | |
865 | unsafe { cmath::tanh(self) } | |
866 | } | |
867 | ||
868 | /// Inverse hyperbolic sine function. | |
869 | /// | |
94b46f34 XL |
870 | /// # Examples |
871 | /// | |
c34b1796 AL |
872 | /// ``` |
873 | /// let x = 1.0_f64; | |
874 | /// let f = x.sinh().asinh(); | |
875 | /// | |
876 | /// let abs_difference = (f - x).abs(); | |
877 | /// | |
878 | /// assert!(abs_difference < 1.0e-10); | |
879 | /// ``` | |
04454e1e | 880 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 881 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
882 | #[stable(feature = "rust1", since = "1.0.0")] |
883 | #[inline] | |
884 | pub fn asinh(self) -> f64 { | |
487cf647 FG |
885 | let ax = self.abs(); |
886 | let ix = 1.0 / ax; | |
887 | (ax + (ax / (Self::hypot(1.0, ix) + ix))).ln_1p().copysign(self) | |
c34b1796 AL |
888 | } |
889 | ||
890 | /// Inverse hyperbolic cosine function. | |
891 | /// | |
94b46f34 XL |
892 | /// # Examples |
893 | /// | |
c34b1796 AL |
894 | /// ``` |
895 | /// let x = 1.0_f64; | |
896 | /// let f = x.cosh().acosh(); | |
897 | /// | |
898 | /// let abs_difference = (f - x).abs(); | |
899 | /// | |
900 | /// assert!(abs_difference < 1.0e-10); | |
901 | /// ``` | |
04454e1e | 902 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 903 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
904 | #[stable(feature = "rust1", since = "1.0.0")] |
905 | #[inline] | |
906 | pub fn acosh(self) -> f64 { | |
487cf647 FG |
907 | if self < 1.0 { |
908 | Self::NAN | |
909 | } else { | |
910 | (self + ((self - 1.0).sqrt() * (self + 1.0).sqrt())).ln() | |
911 | } | |
c34b1796 AL |
912 | } |
913 | ||
914 | /// Inverse hyperbolic tangent function. | |
915 | /// | |
94b46f34 XL |
916 | /// # Examples |
917 | /// | |
c34b1796 | 918 | /// ``` |
ba9703b0 | 919 | /// let e = std::f64::consts::E; |
c34b1796 AL |
920 | /// let f = e.tanh().atanh(); |
921 | /// | |
922 | /// let abs_difference = (f - e).abs(); | |
923 | /// | |
924 | /// assert!(abs_difference < 1.0e-10); | |
925 | /// ``` | |
04454e1e | 926 | #[rustc_allow_incoherent_impl] |
60c5eb7d | 927 | #[must_use = "method returns a new number and does not mutate the original value"] |
c34b1796 AL |
928 | #[stable(feature = "rust1", since = "1.0.0")] |
929 | #[inline] | |
930 | pub fn atanh(self) -> f64 { | |
931 | 0.5 * ((2.0 * self) / (1.0 - self)).ln_1p() | |
932 | } | |
7453a54e SL |
933 | |
934 | // Solaris/Illumos requires a wrapper around log, log2, and log10 functions | |
0731742a | 935 | // because of their non-standard behavior (e.g., log(-n) returns -Inf instead |
7453a54e | 936 | // of expected NaN). |
04454e1e | 937 | #[rustc_allow_incoherent_impl] |
7453a54e | 938 | fn log_wrapper<F: Fn(f64) -> f64>(self, log_fn: F) -> f64 { |
ba9703b0 | 939 | if !cfg!(any(target_os = "solaris", target_os = "illumos")) { |
7453a54e | 940 | log_fn(self) |
29967ef6 XL |
941 | } else if self.is_finite() { |
942 | if self > 0.0 { | |
943 | log_fn(self) | |
944 | } else if self == 0.0 { | |
945 | Self::NEG_INFINITY // log(0) = -Inf | |
7453a54e | 946 | } else { |
29967ef6 | 947 | Self::NAN // log(-n) = NaN |
7453a54e | 948 | } |
29967ef6 XL |
949 | } else if self.is_nan() { |
950 | self // log(NaN) = NaN | |
951 | } else if self > 0.0 { | |
952 | self // log(Inf) = Inf | |
953 | } else { | |
954 | Self::NAN // log(-Inf) = NaN | |
7453a54e SL |
955 | } |
956 | } | |
c34b1796 | 957 | } |