1 | //! Constants for the `f64` double-precision floating point type. |
2 | //! |
3 | //! *[See also the `f64` primitive type](primitive@f64).* |
4 | //! |
5 | //! Mathematically significant numbers are provided in the `consts` sub-module. |
6 | //! |
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. |
11 | |
12 | #![stable (feature = "rust1" , since = "1.0.0" )] |
13 | #![allow (missing_docs)] |
14 | |
15 | #[cfg (test)] |
16 | mod tests; |
17 | |
18 | #[cfg (not(test))] |
19 | use crate::intrinsics; |
20 | #[cfg (not(test))] |
21 | use crate::sys::cmath; |
22 | |
23 | #[stable (feature = "rust1" , since = "1.0.0" )] |
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 | }; |
29 | |
30 | #[cfg (not(test))] |
31 | impl f64 { |
32 | /// Returns the largest integer less than or equal to `self`. |
33 | /// |
34 | /// This function always returns the precise result. |
35 | /// |
36 | /// # Examples |
37 | /// |
38 | /// ``` |
39 | /// let f = 3.7_f64; |
40 | /// let g = 3.0_f64; |
41 | /// let h = -3.7_f64; |
42 | /// |
43 | /// assert_eq!(f.floor(), 3.0); |
44 | /// assert_eq!(g.floor(), 3.0); |
45 | /// assert_eq!(h.floor(), -4.0); |
46 | /// ``` |
47 | #[rustc_allow_incoherent_impl ] |
48 | #[must_use = "method returns a new number and does not mutate the original value" ] |
49 | #[stable (feature = "rust1" , since = "1.0.0" )] |
50 | #[inline ] |
51 | pub fn floor(self) -> f64 { |
52 | unsafe { intrinsics::floorf64(self) } |
53 | } |
54 | |
55 | /// Returns the smallest integer greater than or equal to `self`. |
56 | /// |
57 | /// This function always returns the precise result. |
58 | /// |
59 | /// # Examples |
60 | /// |
61 | /// ``` |
62 | /// let f = 3.01_f64; |
63 | /// let g = 4.0_f64; |
64 | /// |
65 | /// assert_eq!(f.ceil(), 4.0); |
66 | /// assert_eq!(g.ceil(), 4.0); |
67 | /// ``` |
68 | #[doc (alias = "ceiling" )] |
69 | #[rustc_allow_incoherent_impl ] |
70 | #[must_use = "method returns a new number and does not mutate the original value" ] |
71 | #[stable (feature = "rust1" , since = "1.0.0" )] |
72 | #[inline ] |
73 | pub fn ceil(self) -> f64 { |
74 | unsafe { intrinsics::ceilf64(self) } |
75 | } |
76 | |
77 | /// Returns the nearest integer to `self`. If a value is half-way between two |
78 | /// integers, round away from `0.0`. |
79 | /// |
80 | /// This function always returns the precise result. |
81 | /// |
82 | /// # Examples |
83 | /// |
84 | /// ``` |
85 | /// let f = 3.3_f64; |
86 | /// let g = -3.3_f64; |
87 | /// let h = -3.7_f64; |
88 | /// let i = 3.5_f64; |
89 | /// let j = 4.5_f64; |
90 | /// |
91 | /// assert_eq!(f.round(), 3.0); |
92 | /// assert_eq!(g.round(), -3.0); |
93 | /// assert_eq!(h.round(), -4.0); |
94 | /// assert_eq!(i.round(), 4.0); |
95 | /// assert_eq!(j.round(), 5.0); |
96 | /// ``` |
97 | #[rustc_allow_incoherent_impl ] |
98 | #[must_use = "method returns a new number and does not mutate the original value" ] |
99 | #[stable (feature = "rust1" , since = "1.0.0" )] |
100 | #[inline ] |
101 | pub fn round(self) -> f64 { |
102 | unsafe { intrinsics::roundf64(self) } |
103 | } |
104 | |
105 | /// Returns the nearest integer to a number. Rounds half-way cases to the number |
106 | /// with an even least significant digit. |
107 | /// |
108 | /// This function always returns the precise result. |
109 | /// |
110 | /// # Examples |
111 | /// |
112 | /// ``` |
113 | /// let f = 3.3_f64; |
114 | /// let g = -3.3_f64; |
115 | /// let h = 3.5_f64; |
116 | /// let i = 4.5_f64; |
117 | /// |
118 | /// assert_eq!(f.round_ties_even(), 3.0); |
119 | /// assert_eq!(g.round_ties_even(), -3.0); |
120 | /// assert_eq!(h.round_ties_even(), 4.0); |
121 | /// assert_eq!(i.round_ties_even(), 4.0); |
122 | /// ``` |
123 | #[rustc_allow_incoherent_impl ] |
124 | #[must_use = "method returns a new number and does not mutate the original value" ] |
125 | #[stable (feature = "round_ties_even" , since = "1.77.0" )] |
126 | #[inline ] |
127 | pub fn round_ties_even(self) -> f64 { |
128 | unsafe { intrinsics::rintf64(self) } |
129 | } |
130 | |
131 | /// Returns the integer part of `self`. |
132 | /// This means that non-integer numbers are always truncated towards zero. |
133 | /// |
134 | /// This function always returns the precise result. |
135 | /// |
136 | /// # Examples |
137 | /// |
138 | /// ``` |
139 | /// let f = 3.7_f64; |
140 | /// let g = 3.0_f64; |
141 | /// let h = -3.7_f64; |
142 | /// |
143 | /// assert_eq!(f.trunc(), 3.0); |
144 | /// assert_eq!(g.trunc(), 3.0); |
145 | /// assert_eq!(h.trunc(), -3.0); |
146 | /// ``` |
147 | #[doc (alias = "truncate" )] |
148 | #[rustc_allow_incoherent_impl ] |
149 | #[must_use = "method returns a new number and does not mutate the original value" ] |
150 | #[stable (feature = "rust1" , since = "1.0.0" )] |
151 | #[inline ] |
152 | pub fn trunc(self) -> f64 { |
153 | unsafe { intrinsics::truncf64(self) } |
154 | } |
155 | |
156 | /// Returns the fractional part of `self`. |
157 | /// |
158 | /// This function always returns the precise result. |
159 | /// |
160 | /// # Examples |
161 | /// |
162 | /// ``` |
163 | /// let x = 3.6_f64; |
164 | /// let y = -3.6_f64; |
165 | /// let abs_difference_x = (x.fract() - 0.6).abs(); |
166 | /// let abs_difference_y = (y.fract() - (-0.6)).abs(); |
167 | /// |
168 | /// assert!(abs_difference_x < 1e-10); |
169 | /// assert!(abs_difference_y < 1e-10); |
170 | /// ``` |
171 | #[rustc_allow_incoherent_impl ] |
172 | #[must_use = "method returns a new number and does not mutate the original value" ] |
173 | #[stable (feature = "rust1" , since = "1.0.0" )] |
174 | #[inline ] |
175 | pub fn fract(self) -> f64 { |
176 | self - self.trunc() |
177 | } |
178 | |
179 | /// Computes the absolute value of `self`. |
180 | /// |
181 | /// This function always returns the precise result. |
182 | /// |
183 | /// # Examples |
184 | /// |
185 | /// ``` |
186 | /// let x = 3.5_f64; |
187 | /// let y = -3.5_f64; |
188 | /// |
189 | /// assert_eq!(x.abs(), x); |
190 | /// assert_eq!(y.abs(), -y); |
191 | /// |
192 | /// assert!(f64::NAN.abs().is_nan()); |
193 | /// ``` |
194 | #[rustc_allow_incoherent_impl ] |
195 | #[must_use = "method returns a new number and does not mutate the original value" ] |
196 | #[stable (feature = "rust1" , since = "1.0.0" )] |
197 | #[inline ] |
198 | pub fn abs(self) -> f64 { |
199 | unsafe { intrinsics::fabsf64(self) } |
200 | } |
201 | |
202 | /// Returns a number that represents the sign of `self`. |
203 | /// |
204 | /// - `1.0` if the number is positive, `+0.0` or `INFINITY` |
205 | /// - `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY` |
206 | /// - NaN if the number is NaN |
207 | /// |
208 | /// # Examples |
209 | /// |
210 | /// ``` |
211 | /// let f = 3.5_f64; |
212 | /// |
213 | /// assert_eq!(f.signum(), 1.0); |
214 | /// assert_eq!(f64::NEG_INFINITY.signum(), -1.0); |
215 | /// |
216 | /// assert!(f64::NAN.signum().is_nan()); |
217 | /// ``` |
218 | #[rustc_allow_incoherent_impl ] |
219 | #[must_use = "method returns a new number and does not mutate the original value" ] |
220 | #[stable (feature = "rust1" , since = "1.0.0" )] |
221 | #[inline ] |
222 | pub fn signum(self) -> f64 { |
223 | if self.is_nan() { Self::NAN } else { 1.0_f64.copysign(self) } |
224 | } |
225 | |
226 | /// Returns a number composed of the magnitude of `self` and the sign of |
227 | /// `sign`. |
228 | /// |
229 | /// Equal to `self` if the sign of `self` and `sign` are the same, otherwise |
230 | /// equal to `-self`. If `self` is a NaN, then a NaN with the sign bit of |
231 | /// `sign` is returned. Note, however, that conserving the sign bit on NaN |
232 | /// across arithmetical operations is not generally guaranteed. |
233 | /// See [explanation of NaN as a special value](primitive@f32) for more info. |
234 | /// |
235 | /// # Examples |
236 | /// |
237 | /// ``` |
238 | /// let f = 3.5_f64; |
239 | /// |
240 | /// assert_eq!(f.copysign(0.42), 3.5_f64); |
241 | /// assert_eq!(f.copysign(-0.42), -3.5_f64); |
242 | /// assert_eq!((-f).copysign(0.42), 3.5_f64); |
243 | /// assert_eq!((-f).copysign(-0.42), -3.5_f64); |
244 | /// |
245 | /// assert!(f64::NAN.copysign(1.0).is_nan()); |
246 | /// ``` |
247 | #[rustc_allow_incoherent_impl ] |
248 | #[must_use = "method returns a new number and does not mutate the original value" ] |
249 | #[stable (feature = "copysign" , since = "1.35.0" )] |
250 | #[inline ] |
251 | pub fn copysign(self, sign: f64) -> f64 { |
252 | unsafe { intrinsics::copysignf64(self, sign) } |
253 | } |
254 | |
255 | /// Fused multiply-add. Computes `(self * a) + b` with only one rounding |
256 | /// error, yielding a more accurate result than an unfused multiply-add. |
257 | /// |
258 | /// Using `mul_add` *may* be more performant than an unfused multiply-add if |
259 | /// the target architecture has a dedicated `fma` CPU instruction. However, |
260 | /// this is not always true, and will be heavily dependant on designing |
261 | /// algorithms with specific target hardware in mind. |
262 | /// |
263 | /// # Precision |
264 | /// |
265 | /// The result of this operation is guaranteed to be the rounded |
266 | /// infinite-precision result. It is specified by IEEE 754 as |
267 | /// `fusedMultiplyAdd` and guaranteed not to change. |
268 | /// |
269 | /// # Examples |
270 | /// |
271 | /// ``` |
272 | /// let m = 10.0_f64; |
273 | /// let x = 4.0_f64; |
274 | /// let b = 60.0_f64; |
275 | /// |
276 | /// assert_eq!(m.mul_add(x, b), 100.0); |
277 | /// assert_eq!(m * x + b, 100.0); |
278 | /// |
279 | /// let one_plus_eps = 1.0_f64 + f64::EPSILON; |
280 | /// let one_minus_eps = 1.0_f64 - f64::EPSILON; |
281 | /// let minus_one = -1.0_f64; |
282 | /// |
283 | /// // The exact result (1 + eps) * (1 - eps) = 1 - eps * eps. |
284 | /// assert_eq!(one_plus_eps.mul_add(one_minus_eps, minus_one), -f64::EPSILON * f64::EPSILON); |
285 | /// // Different rounding with the non-fused multiply and add. |
286 | /// assert_eq!(one_plus_eps * one_minus_eps + minus_one, 0.0); |
287 | /// ``` |
288 | #[rustc_allow_incoherent_impl ] |
289 | #[must_use = "method returns a new number and does not mutate the original value" ] |
290 | #[stable (feature = "rust1" , since = "1.0.0" )] |
291 | #[inline ] |
292 | pub fn mul_add(self, a: f64, b: f64) -> f64 { |
293 | unsafe { intrinsics::fmaf64(self, a, b) } |
294 | } |
295 | |
296 | /// Calculates Euclidean division, the matching method for `rem_euclid`. |
297 | /// |
298 | /// This computes the integer `n` such that |
299 | /// `self = n * rhs + self.rem_euclid(rhs)`. |
300 | /// In other words, the result is `self / rhs` rounded to the integer `n` |
301 | /// such that `self >= n * rhs`. |
302 | /// |
303 | /// # Precision |
304 | /// |
305 | /// The result of this operation is guaranteed to be the rounded |
306 | /// infinite-precision result. |
307 | /// |
308 | /// # Examples |
309 | /// |
310 | /// ``` |
311 | /// let a: f64 = 7.0; |
312 | /// let b = 4.0; |
313 | /// assert_eq!(a.div_euclid(b), 1.0); // 7.0 > 4.0 * 1.0 |
314 | /// assert_eq!((-a).div_euclid(b), -2.0); // -7.0 >= 4.0 * -2.0 |
315 | /// assert_eq!(a.div_euclid(-b), -1.0); // 7.0 >= -4.0 * -1.0 |
316 | /// assert_eq!((-a).div_euclid(-b), 2.0); // -7.0 >= -4.0 * 2.0 |
317 | /// ``` |
318 | #[rustc_allow_incoherent_impl ] |
319 | #[must_use = "method returns a new number and does not mutate the original value" ] |
320 | #[inline ] |
321 | #[stable (feature = "euclidean_division" , since = "1.38.0" )] |
322 | pub fn div_euclid(self, rhs: f64) -> f64 { |
323 | let q = (self / rhs).trunc(); |
324 | if self % rhs < 0.0 { |
325 | return if rhs > 0.0 { q - 1.0 } else { q + 1.0 }; |
326 | } |
327 | q |
328 | } |
329 | |
330 | /// Calculates the least nonnegative remainder of `self (mod rhs)`. |
331 | /// |
332 | /// In particular, the return value `r` satisfies `0.0 <= r < rhs.abs()` in |
333 | /// most cases. However, due to a floating point round-off error it can |
334 | /// result in `r == rhs.abs()`, violating the mathematical definition, if |
335 | /// `self` is much smaller than `rhs.abs()` in magnitude and `self < 0.0`. |
336 | /// This result is not an element of the function's codomain, but it is the |
337 | /// closest floating point number in the real numbers and thus fulfills the |
338 | /// property `self == self.div_euclid(rhs) * rhs + self.rem_euclid(rhs)` |
339 | /// approximately. |
340 | /// |
341 | /// # Precision |
342 | /// |
343 | /// The result of this operation is guaranteed to be the rounded |
344 | /// infinite-precision result. |
345 | /// |
346 | /// # Examples |
347 | /// |
348 | /// ``` |
349 | /// let a: f64 = 7.0; |
350 | /// let b = 4.0; |
351 | /// assert_eq!(a.rem_euclid(b), 3.0); |
352 | /// assert_eq!((-a).rem_euclid(b), 1.0); |
353 | /// assert_eq!(a.rem_euclid(-b), 3.0); |
354 | /// assert_eq!((-a).rem_euclid(-b), 1.0); |
355 | /// // limitation due to round-off error |
356 | /// assert!((-f64::EPSILON).rem_euclid(3.0) != 0.0); |
357 | /// ``` |
358 | #[doc (alias = "modulo" , alias = "mod" )] |
359 | #[rustc_allow_incoherent_impl ] |
360 | #[must_use = "method returns a new number and does not mutate the original value" ] |
361 | #[inline ] |
362 | #[stable (feature = "euclidean_division" , since = "1.38.0" )] |
363 | pub fn rem_euclid(self, rhs: f64) -> f64 { |
364 | let r = self % rhs; |
365 | if r < 0.0 { r + rhs.abs() } else { r } |
366 | } |
367 | |
368 | /// Raises a number to an integer power. |
369 | /// |
370 | /// Using this function is generally faster than using `powf`. |
371 | /// It might have a different sequence of rounding operations than `powf`, |
372 | /// so the results are not guaranteed to agree. |
373 | /// |
374 | /// # Platform-specific precision |
375 | /// |
376 | /// The precision of this function varies by platform and Rust version. |
377 | /// |
378 | /// # Examples |
379 | /// |
380 | /// ``` |
381 | /// let x = 2.0_f64; |
382 | /// let abs_difference = (x.powi(2) - (x * x)).abs(); |
383 | /// |
384 | /// assert!(abs_difference < 1e-10); |
385 | /// ``` |
386 | #[rustc_allow_incoherent_impl ] |
387 | #[must_use = "method returns a new number and does not mutate the original value" ] |
388 | #[stable (feature = "rust1" , since = "1.0.0" )] |
389 | #[inline ] |
390 | pub fn powi(self, n: i32) -> f64 { |
391 | unsafe { intrinsics::powif64(self, n) } |
392 | } |
393 | |
394 | /// Raises a number to a floating point power. |
395 | /// |
396 | /// # Platform-specific precision |
397 | /// |
398 | /// The precision of this function varies by platform and Rust version. |
399 | /// |
400 | /// # Examples |
401 | /// |
402 | /// ``` |
403 | /// let x = 2.0_f64; |
404 | /// let abs_difference = (x.powf(2.0) - (x * x)).abs(); |
405 | /// |
406 | /// assert!(abs_difference < 1e-10); |
407 | /// ``` |
408 | #[rustc_allow_incoherent_impl ] |
409 | #[must_use = "method returns a new number and does not mutate the original value" ] |
410 | #[stable (feature = "rust1" , since = "1.0.0" )] |
411 | #[inline ] |
412 | pub fn powf(self, n: f64) -> f64 { |
413 | unsafe { intrinsics::powf64(self, n) } |
414 | } |
415 | |
416 | /// Returns the square root of a number. |
417 | /// |
418 | /// Returns NaN if `self` is a negative number other than `-0.0`. |
419 | /// |
420 | /// # Precision |
421 | /// |
422 | /// The result of this operation is guaranteed to be the rounded |
423 | /// infinite-precision result. It is specified by IEEE 754 as `squareRoot` |
424 | /// and guaranteed not to change. |
425 | /// |
426 | /// # Examples |
427 | /// |
428 | /// ``` |
429 | /// let positive = 4.0_f64; |
430 | /// let negative = -4.0_f64; |
431 | /// let negative_zero = -0.0_f64; |
432 | /// |
433 | /// assert_eq!(positive.sqrt(), 2.0); |
434 | /// assert!(negative.sqrt().is_nan()); |
435 | /// assert!(negative_zero.sqrt() == negative_zero); |
436 | /// ``` |
437 | #[rustc_allow_incoherent_impl ] |
438 | #[must_use = "method returns a new number and does not mutate the original value" ] |
439 | #[stable (feature = "rust1" , since = "1.0.0" )] |
440 | #[inline ] |
441 | pub fn sqrt(self) -> f64 { |
442 | unsafe { intrinsics::sqrtf64(self) } |
443 | } |
444 | |
445 | /// Returns `e^(self)`, (the exponential function). |
446 | /// |
447 | /// # Platform-specific precision |
448 | /// |
449 | /// The precision of this function varies by platform and Rust version. |
450 | /// |
451 | /// # Examples |
452 | /// |
453 | /// ``` |
454 | /// let one = 1.0_f64; |
455 | /// // e^1 |
456 | /// let e = one.exp(); |
457 | /// |
458 | /// // ln(e) - 1 == 0 |
459 | /// let abs_difference = (e.ln() - 1.0).abs(); |
460 | /// |
461 | /// assert!(abs_difference < 1e-10); |
462 | /// ``` |
463 | #[rustc_allow_incoherent_impl ] |
464 | #[must_use = "method returns a new number and does not mutate the original value" ] |
465 | #[stable (feature = "rust1" , since = "1.0.0" )] |
466 | #[inline ] |
467 | pub fn exp(self) -> f64 { |
468 | unsafe { intrinsics::expf64(self) } |
469 | } |
470 | |
471 | /// Returns `2^(self)`. |
472 | /// |
473 | /// # Platform-specific precision |
474 | /// |
475 | /// The precision of this function varies by platform and Rust version. |
476 | /// |
477 | /// # Examples |
478 | /// |
479 | /// ``` |
480 | /// let f = 2.0_f64; |
481 | /// |
482 | /// // 2^2 - 4 == 0 |
483 | /// let abs_difference = (f.exp2() - 4.0).abs(); |
484 | /// |
485 | /// assert!(abs_difference < 1e-10); |
486 | /// ``` |
487 | #[rustc_allow_incoherent_impl ] |
488 | #[must_use = "method returns a new number and does not mutate the original value" ] |
489 | #[stable (feature = "rust1" , since = "1.0.0" )] |
490 | #[inline ] |
491 | pub fn exp2(self) -> f64 { |
492 | unsafe { intrinsics::exp2f64(self) } |
493 | } |
494 | |
495 | /// Returns the natural logarithm of the number. |
496 | /// |
497 | /// # Platform-specific precision |
498 | /// |
499 | /// The precision of this function varies by platform and Rust version. |
500 | /// |
501 | /// # Examples |
502 | /// |
503 | /// ``` |
504 | /// let one = 1.0_f64; |
505 | /// // e^1 |
506 | /// let e = one.exp(); |
507 | /// |
508 | /// // ln(e) - 1 == 0 |
509 | /// let abs_difference = (e.ln() - 1.0).abs(); |
510 | /// |
511 | /// assert!(abs_difference < 1e-10); |
512 | /// ``` |
513 | #[rustc_allow_incoherent_impl ] |
514 | #[must_use = "method returns a new number and does not mutate the original value" ] |
515 | #[stable (feature = "rust1" , since = "1.0.0" )] |
516 | #[inline ] |
517 | pub fn ln(self) -> f64 { |
518 | crate::sys::log_wrapper(self, |n| unsafe { intrinsics::logf64(n) }) |
519 | } |
520 | |
521 | /// Returns the logarithm of the number with respect to an arbitrary base. |
522 | /// |
523 | /// The result might not be correctly rounded owing to implementation details; |
524 | /// `self.log2()` can produce more accurate results for base 2, and |
525 | /// `self.log10()` can produce more accurate results for base 10. |
526 | /// |
527 | /// # Platform-specific precision |
528 | /// |
529 | /// The precision of this function varies by platform and Rust version. |
530 | /// |
531 | /// # Examples |
532 | /// |
533 | /// ``` |
534 | /// let twenty_five = 25.0_f64; |
535 | /// |
536 | /// // log5(25) - 2 == 0 |
537 | /// let abs_difference = (twenty_five.log(5.0) - 2.0).abs(); |
538 | /// |
539 | /// assert!(abs_difference < 1e-10); |
540 | /// ``` |
541 | #[rustc_allow_incoherent_impl ] |
542 | #[must_use = "method returns a new number and does not mutate the original value" ] |
543 | #[stable (feature = "rust1" , since = "1.0.0" )] |
544 | #[inline ] |
545 | pub fn log(self, base: f64) -> f64 { |
546 | self.ln() / base.ln() |
547 | } |
548 | |
549 | /// Returns the base 2 logarithm of the number. |
550 | /// |
551 | /// # Platform-specific precision |
552 | /// |
553 | /// The precision of this function varies by platform and Rust version. |
554 | /// |
555 | /// # Examples |
556 | /// |
557 | /// ``` |
558 | /// let four = 4.0_f64; |
559 | /// |
560 | /// // log2(4) - 2 == 0 |
561 | /// let abs_difference = (four.log2() - 2.0).abs(); |
562 | /// |
563 | /// assert!(abs_difference < 1e-10); |
564 | /// ``` |
565 | #[rustc_allow_incoherent_impl ] |
566 | #[must_use = "method returns a new number and does not mutate the original value" ] |
567 | #[stable (feature = "rust1" , since = "1.0.0" )] |
568 | #[inline ] |
569 | pub fn log2(self) -> f64 { |
570 | crate::sys::log_wrapper(self, crate::sys::log2f64) |
571 | } |
572 | |
573 | /// Returns the base 10 logarithm of the number. |
574 | /// |
575 | /// # Platform-specific precision |
576 | /// |
577 | /// The precision of this function varies by platform and Rust version. |
578 | /// |
579 | /// # Examples |
580 | /// |
581 | /// ``` |
582 | /// let hundred = 100.0_f64; |
583 | /// |
584 | /// // log10(100) - 2 == 0 |
585 | /// let abs_difference = (hundred.log10() - 2.0).abs(); |
586 | /// |
587 | /// assert!(abs_difference < 1e-10); |
588 | /// ``` |
589 | #[rustc_allow_incoherent_impl ] |
590 | #[must_use = "method returns a new number and does not mutate the original value" ] |
591 | #[stable (feature = "rust1" , since = "1.0.0" )] |
592 | #[inline ] |
593 | pub fn log10(self) -> f64 { |
594 | crate::sys::log_wrapper(self, |n| unsafe { intrinsics::log10f64(n) }) |
595 | } |
596 | |
597 | /// The positive difference of two numbers. |
598 | /// |
599 | /// * If `self <= other`: `0.0` |
600 | /// * Else: `self - other` |
601 | /// |
602 | /// # Platform-specific precision |
603 | /// |
604 | /// The precision of this function varies by platform and Rust version. |
605 | /// This function currently corresponds to the `fdim` from libc on Unix and |
606 | /// Windows. Note that this might change in the future. |
607 | /// |
608 | /// # Examples |
609 | /// |
610 | /// ``` |
611 | /// let x = 3.0_f64; |
612 | /// let y = -3.0_f64; |
613 | /// |
614 | /// let abs_difference_x = (x.abs_sub(1.0) - 2.0).abs(); |
615 | /// let abs_difference_y = (y.abs_sub(1.0) - 0.0).abs(); |
616 | /// |
617 | /// assert!(abs_difference_x < 1e-10); |
618 | /// assert!(abs_difference_y < 1e-10); |
619 | /// ``` |
620 | #[rustc_allow_incoherent_impl ] |
621 | #[must_use = "method returns a new number and does not mutate the original value" ] |
622 | #[stable (feature = "rust1" , since = "1.0.0" )] |
623 | #[inline ] |
624 | #[deprecated ( |
625 | since = "1.10.0" , |
626 | note = "you probably meant `(self - other).abs()`: \ |
627 | this operation is `(self - other).max(0.0)` \ |
628 | except that `abs_sub` also propagates NaNs (also \ |
629 | known as `fdim` in C). If you truly need the positive \ |
630 | difference, consider using that expression or the C function \ |
631 | `fdim`, depending on how you wish to handle NaN (please consider \ |
632 | filing an issue describing your use-case too)." |
633 | )] |
634 | pub fn abs_sub(self, other: f64) -> f64 { |
635 | unsafe { cmath::fdim(self, other) } |
636 | } |
637 | |
638 | /// Returns the cube root of a number. |
639 | /// |
640 | /// # Platform-specific precision |
641 | /// |
642 | /// The precision of this function varies by platform and Rust version. |
643 | /// This function currently corresponds to the `cbrt` from libc on Unix and |
644 | /// Windows. Note that this might change in the future. |
645 | /// |
646 | /// # Examples |
647 | /// |
648 | /// ``` |
649 | /// let x = 8.0_f64; |
650 | /// |
651 | /// // x^(1/3) - 2 == 0 |
652 | /// let abs_difference = (x.cbrt() - 2.0).abs(); |
653 | /// |
654 | /// assert!(abs_difference < 1e-10); |
655 | /// ``` |
656 | #[rustc_allow_incoherent_impl ] |
657 | #[must_use = "method returns a new number and does not mutate the original value" ] |
658 | #[stable (feature = "rust1" , since = "1.0.0" )] |
659 | #[inline ] |
660 | pub fn cbrt(self) -> f64 { |
661 | unsafe { cmath::cbrt(self) } |
662 | } |
663 | |
664 | /// Compute the distance between the origin and a point (`x`, `y`) on the |
665 | /// Euclidean plane. Equivalently, compute the length of the hypotenuse of a |
666 | /// right-angle triangle with other sides having length `x.abs()` and |
667 | /// `y.abs()`. |
668 | /// |
669 | /// # Platform-specific precision |
670 | /// |
671 | /// The precision of this function varies by platform and Rust version. |
672 | /// This function currently corresponds to the `hypot` from libc on Unix |
673 | /// and Windows. Note that this might change in the future. |
674 | /// |
675 | /// # Examples |
676 | /// |
677 | /// ``` |
678 | /// let x = 2.0_f64; |
679 | /// let y = 3.0_f64; |
680 | /// |
681 | /// // sqrt(x^2 + y^2) |
682 | /// let abs_difference = (x.hypot(y) - (x.powi(2) + y.powi(2)).sqrt()).abs(); |
683 | /// |
684 | /// assert!(abs_difference < 1e-10); |
685 | /// ``` |
686 | #[rustc_allow_incoherent_impl ] |
687 | #[must_use = "method returns a new number and does not mutate the original value" ] |
688 | #[stable (feature = "rust1" , since = "1.0.0" )] |
689 | #[inline ] |
690 | pub fn hypot(self, other: f64) -> f64 { |
691 | unsafe { cmath::hypot(self, other) } |
692 | } |
693 | |
694 | /// Computes the sine of a number (in radians). |
695 | /// |
696 | /// # Platform-specific precision |
697 | /// |
698 | /// The precision of this function varies by platform and Rust version. |
699 | /// |
700 | /// # Examples |
701 | /// |
702 | /// ``` |
703 | /// let x = std::f64::consts::FRAC_PI_2; |
704 | /// |
705 | /// let abs_difference = (x.sin() - 1.0).abs(); |
706 | /// |
707 | /// assert!(abs_difference < 1e-10); |
708 | /// ``` |
709 | #[rustc_allow_incoherent_impl ] |
710 | #[must_use = "method returns a new number and does not mutate the original value" ] |
711 | #[stable (feature = "rust1" , since = "1.0.0" )] |
712 | #[inline ] |
713 | pub fn sin(self) -> f64 { |
714 | unsafe { intrinsics::sinf64(self) } |
715 | } |
716 | |
717 | /// Computes the cosine of a number (in radians). |
718 | /// |
719 | /// # Platform-specific precision |
720 | /// |
721 | /// The precision of this function varies by platform and Rust version. |
722 | /// |
723 | /// # Examples |
724 | /// |
725 | /// ``` |
726 | /// let x = 2.0 * std::f64::consts::PI; |
727 | /// |
728 | /// let abs_difference = (x.cos() - 1.0).abs(); |
729 | /// |
730 | /// assert!(abs_difference < 1e-10); |
731 | /// ``` |
732 | #[rustc_allow_incoherent_impl ] |
733 | #[must_use = "method returns a new number and does not mutate the original value" ] |
734 | #[stable (feature = "rust1" , since = "1.0.0" )] |
735 | #[inline ] |
736 | pub fn cos(self) -> f64 { |
737 | unsafe { intrinsics::cosf64(self) } |
738 | } |
739 | |
740 | /// Computes the tangent of a number (in radians). |
741 | /// |
742 | /// # Platform-specific precision |
743 | /// |
744 | /// The precision of this function varies by platform and Rust version. |
745 | /// This function currently corresponds to the `tan` from libc on Unix and |
746 | /// Windows. Note that this might change in the future. |
747 | /// |
748 | /// # Examples |
749 | /// |
750 | /// ``` |
751 | /// let x = std::f64::consts::FRAC_PI_4; |
752 | /// let abs_difference = (x.tan() - 1.0).abs(); |
753 | /// |
754 | /// assert!(abs_difference < 1e-14); |
755 | /// ``` |
756 | #[rustc_allow_incoherent_impl ] |
757 | #[must_use = "method returns a new number and does not mutate the original value" ] |
758 | #[stable (feature = "rust1" , since = "1.0.0" )] |
759 | #[inline ] |
760 | pub fn tan(self) -> f64 { |
761 | unsafe { cmath::tan(self) } |
762 | } |
763 | |
764 | /// Computes the arcsine of a number. Return value is in radians in |
765 | /// the range [-pi/2, pi/2] or NaN if the number is outside the range |
766 | /// [-1, 1]. |
767 | /// |
768 | /// # Platform-specific precision |
769 | /// |
770 | /// The precision of this function varies by platform and Rust version. |
771 | /// This function currently corresponds to the `asin` from libc on Unix and |
772 | /// Windows. Note that this might change in the future. |
773 | /// |
774 | /// # Examples |
775 | /// |
776 | /// ``` |
777 | /// let f = std::f64::consts::FRAC_PI_2; |
778 | /// |
779 | /// // asin(sin(pi/2)) |
780 | /// let abs_difference = (f.sin().asin() - std::f64::consts::FRAC_PI_2).abs(); |
781 | /// |
782 | /// assert!(abs_difference < 1e-10); |
783 | /// ``` |
784 | #[doc (alias = "arcsin" )] |
785 | #[rustc_allow_incoherent_impl ] |
786 | #[must_use = "method returns a new number and does not mutate the original value" ] |
787 | #[stable (feature = "rust1" , since = "1.0.0" )] |
788 | #[inline ] |
789 | pub fn asin(self) -> f64 { |
790 | unsafe { cmath::asin(self) } |
791 | } |
792 | |
793 | /// Computes the arccosine of a number. Return value is in radians in |
794 | /// the range [0, pi] or NaN if the number is outside the range |
795 | /// [-1, 1]. |
796 | /// |
797 | /// # Platform-specific precision |
798 | /// |
799 | /// The precision of this function varies by platform and Rust version. |
800 | /// This function currently corresponds to the `acos` from libc on Unix and |
801 | /// Windows. Note that this might change in the future. |
802 | /// |
803 | /// # Examples |
804 | /// |
805 | /// ``` |
806 | /// let f = std::f64::consts::FRAC_PI_4; |
807 | /// |
808 | /// // acos(cos(pi/4)) |
809 | /// let abs_difference = (f.cos().acos() - std::f64::consts::FRAC_PI_4).abs(); |
810 | /// |
811 | /// assert!(abs_difference < 1e-10); |
812 | /// ``` |
813 | #[doc (alias = "arccos" )] |
814 | #[rustc_allow_incoherent_impl ] |
815 | #[must_use = "method returns a new number and does not mutate the original value" ] |
816 | #[stable (feature = "rust1" , since = "1.0.0" )] |
817 | #[inline ] |
818 | pub fn acos(self) -> f64 { |
819 | unsafe { cmath::acos(self) } |
820 | } |
821 | |
822 | /// Computes the arctangent of a number. Return value is in radians in the |
823 | /// range [-pi/2, pi/2]; |
824 | /// |
825 | /// # Platform-specific precision |
826 | /// |
827 | /// The precision of this function varies by platform and Rust version. |
828 | /// This function currently corresponds to the `atan` from libc on Unix and |
829 | /// Windows. Note that this might change in the future. |
830 | /// |
831 | /// # Examples |
832 | /// |
833 | /// ``` |
834 | /// let f = 1.0_f64; |
835 | /// |
836 | /// // atan(tan(1)) |
837 | /// let abs_difference = (f.tan().atan() - 1.0).abs(); |
838 | /// |
839 | /// assert!(abs_difference < 1e-10); |
840 | /// ``` |
841 | #[doc (alias = "arctan" )] |
842 | #[rustc_allow_incoherent_impl ] |
843 | #[must_use = "method returns a new number and does not mutate the original value" ] |
844 | #[stable (feature = "rust1" , since = "1.0.0" )] |
845 | #[inline ] |
846 | pub fn atan(self) -> f64 { |
847 | unsafe { cmath::atan(self) } |
848 | } |
849 | |
850 | /// Computes the four quadrant arctangent of `self` (`y`) and `other` (`x`) in radians. |
851 | /// |
852 | /// * `x = 0`, `y = 0`: `0` |
853 | /// * `x >= 0`: `arctan(y/x)` -> `[-pi/2, pi/2]` |
854 | /// * `y >= 0`: `arctan(y/x) + pi` -> `(pi/2, pi]` |
855 | /// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)` |
856 | /// |
857 | /// # Platform-specific precision |
858 | /// |
859 | /// The precision of this function varies by platform and Rust version. |
860 | /// This function currently corresponds to the `atan2` from libc on Unix |
861 | /// and Windows. Note that this might change in the future. |
862 | /// |
863 | /// # Examples |
864 | /// |
865 | /// ``` |
866 | /// // Positive angles measured counter-clockwise |
867 | /// // from positive x axis |
868 | /// // -pi/4 radians (45 deg clockwise) |
869 | /// let x1 = 3.0_f64; |
870 | /// let y1 = -3.0_f64; |
871 | /// |
872 | /// // 3pi/4 radians (135 deg counter-clockwise) |
873 | /// let x2 = -3.0_f64; |
874 | /// let y2 = 3.0_f64; |
875 | /// |
876 | /// let abs_difference_1 = (y1.atan2(x1) - (-std::f64::consts::FRAC_PI_4)).abs(); |
877 | /// let abs_difference_2 = (y2.atan2(x2) - (3.0 * std::f64::consts::FRAC_PI_4)).abs(); |
878 | /// |
879 | /// assert!(abs_difference_1 < 1e-10); |
880 | /// assert!(abs_difference_2 < 1e-10); |
881 | /// ``` |
882 | #[rustc_allow_incoherent_impl ] |
883 | #[must_use = "method returns a new number and does not mutate the original value" ] |
884 | #[stable (feature = "rust1" , since = "1.0.0" )] |
885 | #[inline ] |
886 | pub fn atan2(self, other: f64) -> f64 { |
887 | unsafe { cmath::atan2(self, other) } |
888 | } |
889 | |
890 | /// Simultaneously computes the sine and cosine of the number, `x`. Returns |
891 | /// `(sin(x), cos(x))`. |
892 | /// |
893 | /// # Platform-specific precision |
894 | /// |
895 | /// The precision of this function varies by platform and Rust version. |
896 | /// This function currently corresponds to the `(f64::sin(x), |
897 | /// f64::cos(x))`. Note that this might change in the future. |
898 | /// |
899 | /// # Examples |
900 | /// |
901 | /// ``` |
902 | /// let x = std::f64::consts::FRAC_PI_4; |
903 | /// let f = x.sin_cos(); |
904 | /// |
905 | /// let abs_difference_0 = (f.0 - x.sin()).abs(); |
906 | /// let abs_difference_1 = (f.1 - x.cos()).abs(); |
907 | /// |
908 | /// assert!(abs_difference_0 < 1e-10); |
909 | /// assert!(abs_difference_1 < 1e-10); |
910 | /// ``` |
911 | #[doc (alias = "sincos" )] |
912 | #[rustc_allow_incoherent_impl ] |
913 | #[stable (feature = "rust1" , since = "1.0.0" )] |
914 | #[inline ] |
915 | pub fn sin_cos(self) -> (f64, f64) { |
916 | (self.sin(), self.cos()) |
917 | } |
918 | |
919 | /// Returns `e^(self) - 1` in a way that is accurate even if the |
920 | /// number is close to zero. |
921 | /// |
922 | /// # Platform-specific precision |
923 | /// |
924 | /// The precision of this function varies by platform and Rust version. |
925 | /// This function currently corresponds to the `expm1` from libc on Unix |
926 | /// and Windows. Note that this might change in the future. |
927 | /// |
928 | /// # Examples |
929 | /// |
930 | /// ``` |
931 | /// let x = 1e-16_f64; |
932 | /// |
933 | /// // for very small x, e^x is approximately 1 + x + x^2 / 2 |
934 | /// let approx = x + x * x / 2.0; |
935 | /// let abs_difference = (x.exp_m1() - approx).abs(); |
936 | /// |
937 | /// assert!(abs_difference < 1e-20); |
938 | /// ``` |
939 | #[rustc_allow_incoherent_impl ] |
940 | #[must_use = "method returns a new number and does not mutate the original value" ] |
941 | #[stable (feature = "rust1" , since = "1.0.0" )] |
942 | #[inline ] |
943 | pub fn exp_m1(self) -> f64 { |
944 | unsafe { cmath::expm1(self) } |
945 | } |
946 | |
947 | /// Returns `ln(1+n)` (natural logarithm) more accurately than if |
948 | /// the operations were performed separately. |
949 | /// |
950 | /// # Platform-specific precision |
951 | /// |
952 | /// The precision of this function varies by platform and Rust version. |
953 | /// This function currently corresponds to the `log1p` from libc on Unix |
954 | /// and Windows. Note that this might change in the future. |
955 | /// |
956 | /// # Examples |
957 | /// |
958 | /// ``` |
959 | /// let x = 1e-16_f64; |
960 | /// |
961 | /// // for very small x, ln(1 + x) is approximately x - x^2 / 2 |
962 | /// let approx = x - x * x / 2.0; |
963 | /// let abs_difference = (x.ln_1p() - approx).abs(); |
964 | /// |
965 | /// assert!(abs_difference < 1e-20); |
966 | /// ``` |
967 | #[doc (alias = "log1p" )] |
968 | #[rustc_allow_incoherent_impl ] |
969 | #[must_use = "method returns a new number and does not mutate the original value" ] |
970 | #[stable (feature = "rust1" , since = "1.0.0" )] |
971 | #[inline ] |
972 | pub fn ln_1p(self) -> f64 { |
973 | unsafe { cmath::log1p(self) } |
974 | } |
975 | |
976 | /// Hyperbolic sine function. |
977 | /// |
978 | /// # Platform-specific precision |
979 | /// |
980 | /// The precision of this function varies by platform and Rust version. |
981 | /// This function currently corresponds to the `sinh` from libc on Unix |
982 | /// and Windows. Note that this might change in the future. |
983 | /// |
984 | /// # Examples |
985 | /// |
986 | /// ``` |
987 | /// let e = std::f64::consts::E; |
988 | /// let x = 1.0_f64; |
989 | /// |
990 | /// let f = x.sinh(); |
991 | /// // Solving sinh() at 1 gives `(e^2-1)/(2e)` |
992 | /// let g = ((e * e) - 1.0) / (2.0 * e); |
993 | /// let abs_difference = (f - g).abs(); |
994 | /// |
995 | /// assert!(abs_difference < 1e-10); |
996 | /// ``` |
997 | #[rustc_allow_incoherent_impl ] |
998 | #[must_use = "method returns a new number and does not mutate the original value" ] |
999 | #[stable (feature = "rust1" , since = "1.0.0" )] |
1000 | #[inline ] |
1001 | pub fn sinh(self) -> f64 { |
1002 | unsafe { cmath::sinh(self) } |
1003 | } |
1004 | |
1005 | /// Hyperbolic cosine function. |
1006 | /// |
1007 | /// # Platform-specific precision |
1008 | /// |
1009 | /// The precision of this function varies by platform and Rust version. |
1010 | /// This function currently corresponds to the `cosh` from libc on Unix |
1011 | /// and Windows. Note that this might change in the future. |
1012 | /// |
1013 | /// # Examples |
1014 | /// |
1015 | /// ``` |
1016 | /// let e = std::f64::consts::E; |
1017 | /// let x = 1.0_f64; |
1018 | /// let f = x.cosh(); |
1019 | /// // Solving cosh() at 1 gives this result |
1020 | /// let g = ((e * e) + 1.0) / (2.0 * e); |
1021 | /// let abs_difference = (f - g).abs(); |
1022 | /// |
1023 | /// // Same result |
1024 | /// assert!(abs_difference < 1.0e-10); |
1025 | /// ``` |
1026 | #[rustc_allow_incoherent_impl ] |
1027 | #[must_use = "method returns a new number and does not mutate the original value" ] |
1028 | #[stable (feature = "rust1" , since = "1.0.0" )] |
1029 | #[inline ] |
1030 | pub fn cosh(self) -> f64 { |
1031 | unsafe { cmath::cosh(self) } |
1032 | } |
1033 | |
1034 | /// Hyperbolic tangent function. |
1035 | /// |
1036 | /// # Platform-specific precision |
1037 | /// |
1038 | /// The precision of this function varies by platform and Rust version. |
1039 | /// This function currently corresponds to the `tanh` from libc on Unix |
1040 | /// and Windows. Note that this might change in the future. |
1041 | /// |
1042 | /// # Examples |
1043 | /// |
1044 | /// ``` |
1045 | /// let e = std::f64::consts::E; |
1046 | /// let x = 1.0_f64; |
1047 | /// |
1048 | /// let f = x.tanh(); |
1049 | /// // Solving tanh() at 1 gives `(1 - e^(-2))/(1 + e^(-2))` |
1050 | /// let g = (1.0 - e.powi(-2)) / (1.0 + e.powi(-2)); |
1051 | /// let abs_difference = (f - g).abs(); |
1052 | /// |
1053 | /// assert!(abs_difference < 1.0e-10); |
1054 | /// ``` |
1055 | #[rustc_allow_incoherent_impl ] |
1056 | #[must_use = "method returns a new number and does not mutate the original value" ] |
1057 | #[stable (feature = "rust1" , since = "1.0.0" )] |
1058 | #[inline ] |
1059 | pub fn tanh(self) -> f64 { |
1060 | unsafe { cmath::tanh(self) } |
1061 | } |
1062 | |
1063 | /// Inverse hyperbolic sine function. |
1064 | /// |
1065 | /// # Platform-specific precision |
1066 | /// |
1067 | /// The precision of this function varies by platform and Rust version. |
1068 | /// |
1069 | /// # Examples |
1070 | /// |
1071 | /// ``` |
1072 | /// let x = 1.0_f64; |
1073 | /// let f = x.sinh().asinh(); |
1074 | /// |
1075 | /// let abs_difference = (f - x).abs(); |
1076 | /// |
1077 | /// assert!(abs_difference < 1.0e-10); |
1078 | /// ``` |
1079 | #[doc (alias = "arcsinh" )] |
1080 | #[rustc_allow_incoherent_impl ] |
1081 | #[must_use = "method returns a new number and does not mutate the original value" ] |
1082 | #[stable (feature = "rust1" , since = "1.0.0" )] |
1083 | #[inline ] |
1084 | pub fn asinh(self) -> f64 { |
1085 | let ax = self.abs(); |
1086 | let ix = 1.0 / ax; |
1087 | (ax + (ax / (Self::hypot(1.0, ix) + ix))).ln_1p().copysign(self) |
1088 | } |
1089 | |
1090 | /// Inverse hyperbolic cosine function. |
1091 | /// |
1092 | /// # Platform-specific precision |
1093 | /// |
1094 | /// The precision of this function varies by platform and Rust version. |
1095 | /// |
1096 | /// # Examples |
1097 | /// |
1098 | /// ``` |
1099 | /// let x = 1.0_f64; |
1100 | /// let f = x.cosh().acosh(); |
1101 | /// |
1102 | /// let abs_difference = (f - x).abs(); |
1103 | /// |
1104 | /// assert!(abs_difference < 1.0e-10); |
1105 | /// ``` |
1106 | #[doc (alias = "arccosh" )] |
1107 | #[rustc_allow_incoherent_impl ] |
1108 | #[must_use = "method returns a new number and does not mutate the original value" ] |
1109 | #[stable (feature = "rust1" , since = "1.0.0" )] |
1110 | #[inline ] |
1111 | pub fn acosh(self) -> f64 { |
1112 | if self < 1.0 { |
1113 | Self::NAN |
1114 | } else { |
1115 | (self + ((self - 1.0).sqrt() * (self + 1.0).sqrt())).ln() |
1116 | } |
1117 | } |
1118 | |
1119 | /// Inverse hyperbolic tangent function. |
1120 | /// |
1121 | /// # Platform-specific precision |
1122 | /// |
1123 | /// The precision of this function varies by platform and Rust version. |
1124 | /// |
1125 | /// # Examples |
1126 | /// |
1127 | /// ``` |
1128 | /// let e = std::f64::consts::E; |
1129 | /// let f = e.tanh().atanh(); |
1130 | /// |
1131 | /// let abs_difference = (f - e).abs(); |
1132 | /// |
1133 | /// assert!(abs_difference < 1.0e-10); |
1134 | /// ``` |
1135 | #[doc (alias = "arctanh" )] |
1136 | #[rustc_allow_incoherent_impl ] |
1137 | #[must_use = "method returns a new number and does not mutate the original value" ] |
1138 | #[stable (feature = "rust1" , since = "1.0.0" )] |
1139 | #[inline ] |
1140 | pub fn atanh(self) -> f64 { |
1141 | 0.5 * ((2.0 * self) / (1.0 - self)).ln_1p() |
1142 | } |
1143 | |
1144 | /// Gamma function. |
1145 | /// |
1146 | /// # Platform-specific precision |
1147 | /// |
1148 | /// The precision of this function varies by platform and Rust version. |
1149 | /// This function currently corresponds to the `tgamma` from libc on Unix |
1150 | /// and Windows. Note that this might change in the future. |
1151 | /// |
1152 | /// # Examples |
1153 | /// |
1154 | /// ``` |
1155 | /// #![feature(float_gamma)] |
1156 | /// let x = 5.0f64; |
1157 | /// |
1158 | /// let abs_difference = (x.gamma() - 24.0).abs(); |
1159 | /// |
1160 | /// assert!(abs_difference <= f64::EPSILON); |
1161 | /// ``` |
1162 | #[rustc_allow_incoherent_impl ] |
1163 | #[must_use = "method returns a new number and does not mutate the original value" ] |
1164 | #[unstable (feature = "float_gamma" , issue = "99842" )] |
1165 | #[inline ] |
1166 | pub fn gamma(self) -> f64 { |
1167 | unsafe { cmath::tgamma(self) } |
1168 | } |
1169 | |
1170 | /// Natural logarithm of the absolute value of the gamma function |
1171 | /// |
1172 | /// The integer part of the tuple indicates the sign of the gamma function. |
1173 | /// |
1174 | /// # Platform-specific precision |
1175 | /// |
1176 | /// The precision of this function varies by platform and Rust version. |
1177 | /// This function currently corresponds to the `lgamma_r` from libc on Unix |
1178 | /// and Windows. Note that this might change in the future. |
1179 | /// |
1180 | /// # Examples |
1181 | /// |
1182 | /// ``` |
1183 | /// #![feature(float_gamma)] |
1184 | /// let x = 2.0f64; |
1185 | /// |
1186 | /// let abs_difference = (x.ln_gamma().0 - 0.0).abs(); |
1187 | /// |
1188 | /// assert!(abs_difference <= f64::EPSILON); |
1189 | /// ``` |
1190 | #[rustc_allow_incoherent_impl ] |
1191 | #[must_use = "method returns a new number and does not mutate the original value" ] |
1192 | #[unstable (feature = "float_gamma" , issue = "99842" )] |
1193 | #[inline ] |
1194 | pub fn ln_gamma(self) -> (f64, i32) { |
1195 | let mut signgamp: i32 = 0; |
1196 | let x = unsafe { cmath::lgamma_r(self, &mut signgamp) }; |
1197 | (x, signgamp) |
1198 | } |
1199 | } |
1200 | |