library/std/src/f64.rs

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